Descripteurs de déploiement

Les descripteurs de déploiement définissent les informations de configuration des portlets contenus dans une application de portlet.

Chaque application de portlets requiert deux descripteurs de déploiement :

  • Le portlet deployment descriptor fournit au serveur du portail les informations sur les ressources de portlet dans l'application, y compris la configuration, les caractéristiques de support et les titres. Ces informations permettent au serveur de portail d'offrir des services au portlet. Par exemple, si un portlet enregistre une prise en charge des modes aide et édition dans le descripteur de déploiement du portlet, le serveur du portail affiche des icônes qui permettent à l'utilisateur de démarrer les pages d'aide et d'édition du portlet. Ce fichier est toujours nommé portlet.xml.
  • Le web application descriptor fournit au serveur d'applications les informations sur les ressources Web dans l'application. Ce fichier est toujours nommé web.xml. Le format de ce fichier est décrit dans le chapitre Descripteur de déploiement de la Spécification de servlet.
Les rubriques suivantes décrivent les descripteurs de déploiement d'une collection de portlets

Descripteur de déploiement d'application Web

Cette section décrit les éléments requis du fichier web.xml pour les portlets standard. Pour plus d'informations sur le descripteur de déploiement d'application Web, voir Java Servlet Specification Version 2.3.

Descripteur d'application Web pour les portlets standard
Comme indiqué dans la spécification Java Portlet Specification, une application de portlet est une application Web étendue qui a donc un contexte de servlet. Le contexte de portlet utilise la plupart de ses fonctions à partir du contexte de servlet de l'application de portlets. Etant donné que le fichier web.xml est obligatoire dans une archive Java Platform, Enterprise Edition web ARchive, vous devez vérifier que votre application de portlets inclut un fichier web.xml dans son fichier WAR qui soit conforme à la spécification de servlet Java version 2.3 ou suivante. Cela garantit la compatibilité de l'application de portlet avec les autres implémentations de serveur de portail et avec HCL Portal. Le fichier web.xml doit au moins contenir les éléments <web-app/> et <display-name/>. Vous pouvez également inclure des paramètres relatifs au contexte en utilisant l'élément <init-param>. Pour plus d'informations sur la structure du descripteur de déploiement d'application Web, voir Version de spécification de servlet Java.
Descripteur d'application Web HCL
Comme pour d'autres servlets conformes au modèle Java Platform, Enterprise Edition, les portlets sont conditionnés sous forme de fichiers WAR ou EAR accompagnés d'un descripteur de déploiement d'application Web, web.xml. Ce descripteur définit chaque portlet comme un servlet au sein de l'application Web, incluant des identificateurs uniques pour chaque portlet, la classe du portlet et les paramètres d'initialisation.

La définition des servlets dans le descripteur de déploiement d'application Web web.xml doit être présentée dans le même ordre que celle des portlets dans le descripteur de déploiement de portlet portlet.xml. L'identificateur du servlet doit être référencé par le descripteur de déploiement du portlet, à l'aide de l'attribut href de la balise <portlet>. Comme illustré dans le tableau suivant, l'attribut href indique le chemin du descripteur de l'application Web dans le fichier WAR ajouté par l'ID de servlet en tant que point d'ancrage.

Tableau 1. Attribut href dans les fichiers portlet.xml et web.xml
portlet.xml web.xml 
  <portlet id="Portlet_1"
           href="WEB-INF/web.xml#Servlet_1">
    <portlet-name>Mail</portlet-name>
    ...
  </portlet>

  <servlet
    id="Servlet_1">
    <servlet-name>MailPortlet</servlet-name>
    ...
  </servlet>

  <portlet id="Portlet_2"
           href="WEB-INF/web.xml#Servlet_2">
    <portlet-name>Calendar</portlet-name>
    ...
  </portlet>

  <servlet
    id="Servlet_2">
    <servlet-name>CalendarPortlet</servlet-name>
    ...
  </servlet>

Descripteur de déploiement de portlet

Cette section décrit le fichier portlet.xml pour les portlets standard.

  • Les éléments et la structure du fichier portlet.xml HCL sont décrits dans cette rubrique.
  • Pour plus de détails sur le descripteur de déploiement de portlet pour l'API de portlet standard, voir la spécification de portlet Java.
Directives relatives aux identificateurs de collection de portlets
Les identificateurs d'applications de portlets doivent identifier celles-ci de manière univoque dans leur zone d'utilisation, qui peut s'étendre au monde entier. Le principe est identique pour les applications de portlets concrets. Pour que cela soit possible, respectez les principes suivants.
  • Incluez l'espace de nom du portlet dans l'identificateur, en utilisant le même format que celui employé dans les packages Java
  • Ajoutez une description propre à l'application de portlets
  • Ajoutez un certains nombre de caractères arbitraires pour garantir l'univocité au sein de l'espace de nom, par exemple : 
     com.ibm.wps.samplet.mail.4969
  • En ce qui concerne les portlets HCL, ajoutez des suffixes pour les applications de portlets concrets correspondantes, par exemple : 
     com.ibm.wps.samplet.mail.4969.1
Les identificateurs de portlet doivent être uniques au sein de l'application.
Descripteur de déploiement de portlet standard
Dans la spécification de portlet Java, le descripteur de portlet est contenu dans le format d'un schéma XML. Dans la mesure où le portlet n'est pas un servlet, le descripteur de portlet ne fait référence à aucun ID de servlet correspondant dans le fichier web.xml. L'élément de premier niveau est <portlet-app/> et contient une ou plusieurs définitions <portlet/>. Les paramètres d'initialisation spécifiques aux portlets sont stockés dans le fichier portlet.xml à l'aide de l'élément <init-param/> et sont obtenus via l'objet PortletConfig fourni au cours de l'initialisation.
Descripteur de déploiement de portlet HCL
La structure du descripteur de déploiement de portlet HCL est définie par un fichier DTD, à l'emplacement wps.war/dtd/portlet_1.1.dtd.
Pour les portlets HCL, chaque définition de portlet concret indique son portlet parent grâce à l'attribut href de la balise <concrete-portlet>. Comme illustré dans le tableau suivant, l'attribut href désigne l'ID du servlet comme un point d'ancrage.
Tableau 2. Attribut href dans la balise de portlet et la balise de portlet concret
Balise de portlet balise de portlet concret 
  <portlet id="Portlet_1"
           href="WEB-INF/web.xml#Servlet_1">
    <portlet-name>Mail</portlet-name>
    ...
  </portlet>

  <concrete-portlet href="#Portlet_1">
    <portlet-name>Mail Box</portlet-name>
    ...
  </concrete-portlet>

  <portlet id="Portlet_2"
           href="WEB-INF/web.xml#Servlet_2">
    <portlet-name>Calendar</portlet-name>
    ...
  </portlet>

  <concrete-portlet href="#Portlet_2">
    <portlet-name>Group calendar</portlet-name>
    ...
  </concrete-portlet>
-->

Noms des paramètres réservés

Cette section décrit les paramètres qui peuvent être définis pour les portlets. Il existe deux types de paramètres :

Paramètres de configuration
Ce sont des paramètres d'un portlet qui peuvent être modifiés uniquement par un administrateur. Ils sont définis dans le fichier portlet.xml à l'aide de l'élément <config-param/> (pour les portlets HCL) ou de l'élément <preferences/> marqué en lecture seule (pour les portlets standard).
Paramètres d'initialisation
Ces paramètres sont définis lors du déploiement. Pour les portlets standard, ils sont définis par l'élément <init-param/> dans le fichier portlet.xml. Pour les portlets HCL, ils sont définis par l'élément <init-param/> dans le fichier web.xml.

Les paramètres suivants peuvent être définis comme paramètres de configuration dans les portlets IBM ou comme paramètres d'initialisation dans les portlets standard :

redirect.action.without.session = (false)
Définissez ce paramètre sur true pour imposer un réacheminement après une action sur des pages anonymes pour ce portlet.
wps.enforce.redirect = (false)
Affectez à ce paramètre la valeur true si votre portlet demande une redirection pour une action de portlet. L'avantage de la redirection est que l'URL change pour contenir l'état complet ; l'URL modifiée apparaît dans le navigateur et peut être marquée avec un signet. L'inconvénient est que la requête supplémentaire augmente la charge du serveur. Le portlet n'a pas besoin d'une redirection après l'action s'il ne définit aucun paramètre de rendu public ou privé dans processAction ou processEvent.
wps.markup
Paramètre d'initialisation dans les portlets standard permettant de définir les types de balisage pris en charge par le portlet. Utilisez-le pour différencier plusieurs types de balisage, tels que HTML et cHTML, qui utilisent le même type MIME.
com.ibm.portal.automaximize
Définissez ce paramètre sur la valeur true pour agrandir automatiquement le portlet lorsque l'utilisateur passe du mode d'affichage à un autre des modes pris en charge. La valeur par défaut est false.
wps.multiple.action.execution
Définissez ce paramètre sur true pour permettre à l'utilisateur d'exécuter plusieurs fois la même URL d'action.

Le paramètre suivant peut être défini comme paramètre de configuration dans les portlets IBM ou comme préférences en lecture seule dans les portlets standard :

com.ibm.portal.pagecontext.enable = (false)
Lorsque vous définissez ce paramètre sur true, vous indiquez que le portlet peut récupérer les propriétés de tâche. Ce paramètre est utilisé par les portlets de traitement des tâches. La valeur par défaut est false.

Options d'exécution de conteneur

Le portail définit les options d'exécution de conteneur qui peuvent être utilisées par les portlets qui sont conformes à Java Portlet Specification 2.0 (JSR286). Vous définissez ces paramètres à l'aide de l'élément <container-runtime-option> figurant dans le fichier portlet.xml.
com.ibm.portal.public.session
Attribuez la valeur true à ce paramètre pour autoriser la création de sessions pour les utilisateurs anonymes de ce portlet particulier. Exemple : 
<container-runtime-option>
   <name>com.ibm.portal.public.session</name>
   <value>true</value>
</container-runtime-option>