Groupe 3F (CMS)

Date de création : 10 novembre 2004
Dernière modification : 18 février 2005
Diffusion : internet

Installation du rendu Cocoon inJac V2

Configuration utilisée :

Ce document a pour but de décrire l'installation de l'application Cocoon du rendu d'inJac, la personnalisation du rendu, et certains aspects de configuration avancée tels que l'accès à une base de donnée, ou le paramétrage de l'utilisation mémoire.

Les sources sont disponibles sur le CVS dans le module Injac/applications/Cocoon, le package peut être téléchargé dans l'espace de téléchargement.

 

Pré-requis

Dépendances

Installation

Personnalisation du rendu

Configuration avancée

 

Pré-requis

Le rendu Cocoon nécessite l'installation préalable de Cocoon 2.1.5.1 , téléchargeable sur le site Apache.

 

Dépendances

Le rendu Cocoon d'inJac V2 est le rendu d'un espace de publication Webdav, il dépends donc du Canal Stockage V3 et du serveur Webdav V2, disponibles sur l'espace de téléchargement.

 

Installation

A. Installer Cocoon dans un moteur de JSP/Servlet (exemple : Tomcat)

  1. Télécharger cocoon à l'adresse http://cocoon.apache.org/mirror.cgi

  2. Dezipper le paquet pour obtenir le répertoire des sources.

  3. Compiler Cocoon en se plaçant à la racine du répertoire des sources, taper :

    - build

    - build war

  4. Copier/coller le fichier cocoon.war depuis le sous répertoire build\cocoon-2.1.5.1\ vers le répertoire webapps de Tomcat.

  5. Si votre serveur est en mode autodeploy il n'y a plus qu'à attendre que le .war se déploie, sinon le déployer à l'aide de l'outil de management de Tomcat.



B. Déployer Injac-Cocoon

1. Dezipper l'archive injac

    Editer le fichier build.properties avant de lancer la commande "ant deploy", pour déployer l'arborescence dans Cocoon.
    Ce fichier comporte principalement le chemin de déploiement de Cocoon :

    deploy.cocoon.home = E:/TestJava/jakarta-tomcat-5.0.28/webapps/cocoon

C. Configuration

Edition du fichier iconf.xml

1. <webdav> et <anon-webdav>

Avant toute chose, vous devez définir les url du serveur Webdav, ainsi que l'url de votre application Injac. Pour gérer les deux mode d'accés, public et avec identification, deux url distinctes sont nécessaires, avec deux hostname différents, un pour chaque mode. Ces hotsname doivent correspondre à ceux définis dans les filtres "TRUSTED" et "ANON" du serveur Webdav(fichier web.xml de l'application Slide) :

<filter>
<filter-name>authenticationRouter</filter-name>

...

<!-- TRUSTED -->

<init-param>
<param-name>org.esupportail.filter.authenticationRouter.destinationHostTRUSTED</param-name>
<param-value>saroumane.enseeiht.fr:8081</param-value>
</init-param>

<!-- UNAUTHENTICATED -->

<init-param>
<param-name>org.esupportail.filter.authenticationRouter.destinationHostUNAUTHENTICATED</param-name>
<param-value>anon.enseeiht.fr:8081</param-value>
</init-param>

...

</filter>

A ces URLs doivent correspondre celles définies dans iconf.xml :

<!-- Webdav URL (serveur + collection) authentificated mode -->
<webdav>saroumane.enseeiht.fr:8081/slide/files/injacRoot</webdav>
<!-- URL Webdav (serveur + répertoire) public mode -->
<anon-webdav>anon.enseeiht.fr:8081/slide/files/injacRoot</anon-webdav>

2. <logoutURL>

Cet élément correspond à l'URL pour clore une connexion identifiée auprés du serveur CAS.

<logoutURL>https://cas.enseeiht.fr:8443/cas/logout?service=http://saroumane.enseeiht.fr:810/cocoon/injac</logoutURL>

La partie en bleu correspond à l'URL de la servlet de logout du serveur CAS, et la partie en rouge à l'élément <localURI> défini plus bas dans le fichier.

Les autres paramètres du fichier iconf.xml concernent le stockage des ressources, les métadonnées utilisées, et l'emplacement des ressources internes:


<trustedpw> : Mot de passe TRUSTED pour la connexion au serveur Webdav

<docmd> : Noms des métadonnées du serveur Webdav concernant un document

<rendermd> : Noms des métadonnées du serveur Webdav concernant la personnalisation du rendu

<typemd> : Noms des métadonnes déterminant le type de la collection et les fichiers par défaut associés(espace et document)
<defaultstyle> : nom de la feuille de style par défaut(obsoléte à partir de la version 2 du Canal de Stockage, où l'utilisateur choisit la feuille parmis une liste établie dans le fichier injac.xml, élément <Renderings> )

<defaultskin> : fichier de skin par défaut(voir personnalisation du rendu)

<localURI> : URL de l'application Cocoon-Injac

<errorsheet> : feuille xsl pour afficher les erreurs. Il y a une feuille pour le deboggage(avec affichage des détails des exceptions) et une feuille pour le fonctionnement en production(plus concise).
<localResource> : Booléen déterminant l'emplacement des ressources.

<webdavresources>emplacement des ressources dans le cas de [localResource=false]

 

Par défaut les ressources du rendu (logos, icones, CSS) sont définies localement, dans le répertoire media pour les graphiques,stylesheets/css four les feuilles CSS, et xml/skin pour les skins.

Note : pour personnaliser le rendu, se reporter au chapitre suivant.

Configuration du filtre CAS

L'accés authentifié se fait par l'intermédiaire d'un filtre java, qui se paramètre dans le fichier web.xml de Cocoon :

<!-- CAS FILTER -->
<filter>
<filter-name>Filtre CAS</filter-name>
<filter-class>edu.yale.its.tp.cas.client.filter.CASFilter</filter-class>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.loginUrl</param-name>
<param-value>https://cas.enseeiht.fr:8443/cas/login</param-value>
</init-param>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.validateUrl</param-name> <!--serviceValidate-->
<param-value>https://cas.enseeiht.fr:8443/cas/serviceValidate</param-value>
</init-param>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.proxyCallBackURL</param-name>
<param-value>https://saroumane.enseeiht.fr:8443/injac/CasProxyServlet</param-value>
</init-param>
<init-param>
<param-name>edu.yale.its.tp.cas.client.filter.serverName</param-name>
<param-value>saroumane.enseeiht.fr</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>Filtre CAS</filter-name>
<url-pattern>/injac/auth/*</url-pattern>
</filter-mapping>
<!-- CAS FILTER -->

En rouge figure le hostname de l'application CAS, en bleu celui d'Injac.

Niveau de débogage

Le niveau de débogage peut être modifier en éditant le fichier WEB-INF\classes\log4j.properties.

Les niveaux disponibles sont : debug, info, error, du plus prolixe au plus concis.

Catalogue de résolution d'entités.

Il faut modifier de façon appropriée le chemin vers les catalogues de résolution d'entités, dans le fichier cocoon/WEB-INF/classes/CatalogManager.properties :

catalogs=E:/Java/jakarta-tomcat-5.0.28/webapps/cocoon/injac/dtd/sdocbook.cat;E:/Java/jakarta-tomcat-5.0.28/webapps/cocoon/injac/dtd/docbk41/docbook.cat
de façon à les faire pointer sur votre répertoire de déploiement d'Injac.

D. Naviguez

Lancez un naviguateur et essayer l'URL {TOMCAT-URL}/cocoon/injac.

    Vous arrivez alors à la page représentant l'espace racine que vous avez défini dans iconf.xml, en mode anonyme.

    Important : Pour que ce mode soit opérationnel, il faut que l'espace racine soit défini en lecture publique dans le Canal de Stockage. Vous pouvez alors naviguer dans les espace WebDAV publics, afficher différents types de documents, et les convertir au format PDF.

    Pour accéder à des espaces et documents protégés, cliquez sur le lien "s'identifier" en haut à droite(dans le rendu par défaut), et vous pourrez alors étendre votre navigation en fonction de vos droits en lecture (qui sont définis par l'administrateur de l'espace dans le Canal de Stockage).

     

Personnalisation du rendu

Dans la version 2, la personnalisation se fait à travers deux fichiers associés :

-un fichier de skin, définissant des options du contenu du rendu(liens, logos, recherche), qui se place dans le sous-répertoire injac/xml. Le fichier skin.xml sert de modèle auquel se réferrer pour construire d'autres fichiers.

-une feuille CSS, qui gère l'aspect graphique du rendu (couleurs, disposition...), située dans le sous-répertoire injac/stylesheets/xsl.

Pour chaque fichier de contenu(skin), on doit donc avoir au moins une feuille CSS correspondante, mais on peut en avoir également plusieurs, pour varier l'apparence d'un même contenu.

C'est à travers l'edition des metadonnées lors de la création ou de l'administartion d'un espace par le Canal de Stockage que l'administrateur d'espace choisit le skin et la feuille de style. Dans la version V3 du canal de Stockage, seule la feuille est paramétrable, le skin utilisé étant alors celui définit par défaut dans iconf.xml. Une liste de ceux-ci doit donc être renseignée dans le fichier de configuration du Canal, properties/injac/injac.xml, sous la forme :

<RENDERINGS>

<RENDERING
url="ma-feuille.css"
label="Mon rendu"
/>

</RENDERINGS>

Pour plus d'information sur l'installation et la configuration du Canal de Stockage, se rendre à la documentation adéquate.

1. Le skin

Pour créer un nouveau skin, on peut partir du fichier skin.xml dont voici le contenu :

<skin>
<header>
<logos>
<logo id="[id-pour logo]" name="School" src="[votre-image]" />

</logos>
<links layout="htable">
<link id="[id-pour-lien]" name="[intitulé-du-lien]" href="[url]" />
</links>
</header>
<tools>
<tool type="lucene" text="Rechercher" />
</tools>
</skin

Voici une description des éléments qu'il contient :

logo : permet d'ajouter une image au rendu.

- l'attribut "id" permet d'établir une correspondance avec la feuille CSS en étant l'identifiant de la balise div générée dans le rendu HTML.

- name est le nom alternatif de l'image

- src est le nom du fichier de l'image(cf. accés au ressources)

link : permet d'ajouter un lien au rendu.

- l'attribut "id" permet d'établir une correspondance avec la feuille CSS en étant l'identifiant de la balise div générée dans le rendu HTML.

- name est le nom affiché du lien

- href est l'URL absolue de la page.

L'administrateur du rendu peut ajouter autant de logos et de liens qu'il veut, mais dois également ajouter les éléments correspondant dans la feuille de style associée. Chaque logo ou lien est identifié par une balise <div> comme suis :

ex. :

pour <logo id="toulschool" name="School" src="_images/toulouse.jpg" />

--> une balise <div id="toulschool"> est générée

pour <link id="esuplink" name="Esup-Portail" href="http://www.esup-portail.org/" />

--> une balise <div id="esuplink"> est générée.

Il est donc conseiller de choisir des identifiants suffisamment spécifiques pour qu'il n'y ait pas de risque de collisions avec d'autres identifiants.

Dans la feuille de style(style1.css par défaut), on doit donc retrouver ces identifiants :

#toulschool

{ ... }

#esuplink

{ ... }

 

2. Le style CSS

L'autre façon de personnaliser le rendu est de modifier la feuille de style ou d'en créer une autre sur le même modèle, si on veut avoir plusieurs styles disponibles.

Là encore, chaque élément de la page de rendu est identifié par un nom :

iHeader






iNavBar

iNavPan

iDocRender
























Exemple:

On souhaite ajouter une image d'arrière-plan(background.png) à l'espace de rendu du document.

1. placer l'image dans le repertoire des ressources(injac/media si l'option localResources est à true)

  1. editer la feuille de style et modifier l'élément iDocRender :

#iDocRender

{

position:relative;

top:140px;

left:150px;

width:55%;

background-image: url(_images/background.png);

}

Note: toute url pour les ressources graphiques internes à inJac doit inclure le chemin _images devant le nom de l'image, et ce que l'emplacement des ressources soit défini en local ou non(cf iconf.xml). Cette url sert à différencier les pipelines du sitemap inJac.



Configuration avancée

A. Configuration de Tomcat et Cocoon

1. Options de rechargement de Cocoon ou du sitemap


Une url permet forcer le rechargement de Cocoon aprés par exemple une modification de xconf.conf :

 

http://localhost:8080/cocoon?cocoon-reload=true


Note: Chaque fois que je l'ai testée, elle a fait planter le servlet.

En mode développement ce n'est pas gênant, mais en production, il ne faut pas oublier de le désactiver dans cocoon/WEB-INF/web.xml:

<!--
   Allow reinstantiating (reloading) of the cocoon instance. If this is
   set to "yes" or "true", a new cocoon instance can be created using
   the request parameter "cocoon-reload"
.-->
<init-param>
  <param-name>allow-reload</param-name>
  <param-value>no</param-value>
</init-param>


En outre le rechargement du sitemap peut aussi être configuré dans cocoon.xconf à la dernière ligne :

<sitemap file="sitemap.xmap" reload-method="asynchron" check-reload="yes"/>

 

2. Configuration mémoire de Tomcat

Cocoon nécessite un minimum de 128M pour fonctionner correctement, sachant que rien qu'au lancement 75mo sont utilisés, et le maximum reste dépendant du nombre d'utilisateurs. Il faut donc indiquer à la jvm que le servlet container doit se lancer avec les options -Xms128m -Xmx256(min et max de mémoire) :

Dans le répertoire {$CATALINA_HOME}/bin, editer le fichier catalina.bat et/ou catalina.sh, et chercher la variable CATALINA_OPTS, et lui rajouter les options -Xms128m -Xmx256 :

catalina.bat :

set CATALINA_OPTS=-Xms128m -Xmx256m -server -Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000

catalina.sh :

CATALINA_OPTS="-Xms128m -Xmx256m $CATALINA_OPTS"

 

B. Connecter une base de données

Pour utiliser des résultats de requêtes SQL dans un pipeline Cocoon, voici les étapes nécessaires, avec pour illustrer l'exemple d'une connection à la base « uportal » sous MYSQL :

 

1. Placer l'archive jar contenant le driver jdbc dans cocoon\WEB-INF\lib

Ex. : mysql-connector-java-3.0.10-stable-bin.jar

 

2. Editer le fichier web.xml et rajouter les lignes en rouges (dans cocoon\WEB-INF)

Ex.:

<init-param>

<param-name>load-class</param-name>

<param-value>

<!-- For parent ComponentManager sample:

org.apache.cocoon.samples.parentcm.Configurator -->

<!-- For IBM WebSphere:

com.ibm.servlet.classloader.Handler -->

<!-- For Database Driver: -->

org.hsqldb.jdbcDriver

<!-- For Mysql Database: -->

com.mysql.jdbc.Driver

</param-value>

</init-param>


3. Editer le fichier cocoon.xconf (dans cocoon\WEB-INF):

Dans l'élément <datasources>, ajouter un élément <jdbc> décrivant la connexion :

Ex. :

<jdbc logger="core.datasources.anouncement" name="anouncement">

<pool-controller max="10" min="5"/>

<auto-commit>true</auto-commit>

<dburl>jdbc:mysql://localhost:3306/uportal</dburl>

<user>uportalU</user>

<password>azerty</password>

</jdbc>

Dans l'élément <autoincrement-modules>, choisissez la ligne qui va bien :

Ex. :

<component-instance class="org.apache.cocoon.components.modules.database.MysqlAutoIncrementModule" logger="core.modules.auto" name="auto" />


4. Faire un fichier de requête xml (exemple :cocoon\injac\queries\cat_anouncement-sql.xml) :

Ex. :

<?xml version="1.0"?>

<anouncement xmlns:sql="http://apache.org/cocoon/SQL/2.0">

<execute-query xmlns="http://apache.org/cocoon/SQL/2.0">

<query>

select TITLE, DESCRIPTION from upc_cu_ann_topic limit 5

</query>

</execute-query>

</anouncement>


5. Dans le sitemap :

Ajout d'un pipeline utilisant SQLTransformer

ex.:

<map:match pattern="Anouncement" >

<map:generate src="cat_anouncement_sql.xml" />

<map:transform type="sql">

<map:parameter name="use-connection" value="anouncement"/>

</map:transform>

<map:serialize/>

</map:match>