...

• Les actions sont définies dans le fichier de configuration avec le format suivant :

<!--
  	<action *name="nom logique de l'action"
			type="type de l'action : normal ou servant - normal par defaut"
			*classname="classe de type SubChannel a  instancier pour realiser l'action"
			rendertype="type de rendu : xsl ou ssl - xsl par defaut"
			xslfile="fichier xsl a  utiliser si rendertype=xsl - par defaut name.xsl"
			sslfile="nom du fichier ssl a  utiliser - null par defaut"
			ssltitle="entree a  utiliser dans le fichier ssl - par defaut le nom de l'action"
			init="methode d'initialisation de l'action - init par defaut"
			setoutput="methode qui fixe les parama¨tres xsl/xml/ssl - setOutput par defaut"
			setxml="methode qui fixe le XML - setXML par defaut"
			renderxml="methode qui effectue le rendu XML - renderXML par defaut"
			servantfinish="action sur laquelle passer lorsque le servant est fini. Cas ou type=servant"
			servantinit="action sur laquelle le servant démarre (cas ou le servant est conçu avec MAG). default par défaut. Cas ou type=servant"
			cachetype="type de cache (default|channel|instance) - default par defaut"
			<param name="nom du param1">
				<value>premiere valeur du param1</value>
				<value>deuxieme valeur du param1</value>
				...
			</param>
			...
			<param name="nom du paramN">
				<value>valeur du paramN</value>
			</param>
		/>
	* = obligatoire
	toutes les methodes sont eventuellement implementees dans classname
-->

...

• Elle sert à valuer la variable xml de la subChannel qui contient le xml à utiliser lors de la transformation xslt
• Il est facultatif de définir l'enveloppe du xml. Si elle n'est pas définie le xml généré sera enveloppé dans :

<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>
<xml>
le xml généré dans setXML
</xml>

• L'implémentation de cette méthode est facultative. Par défaut elle renvoie la chaine xml suivante :

<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>
<xml>
</xml>

...

• Le framework permet le mapping entre le nom local d'un groupe et son identifiant dans la base de données uPortal.
• Ce mapping se définit de la façon suivante dans le fichier de configuration :

<groupmapping>
	<group localname="group1" uportalid="local.101"/>
	<group localname="group2" uportalid="local.102"/>
</groupmapping>

• Il est alors possible de récupérer l'identifiant du groupe via une appel du type :

 Config.getInstance().getGroupmapping().get("group1");

...

• Un constructeur par défaut qui ne gère que le message d'erreur en le fixant avec "Une erreur est survenue dans l'exécution du canal. Veuillez réessayer ultérieurement." : FrameWorkException();
• Un constructeur, identique au précédent à ceci près qu'il permet de spécifier son propre message d'erreur : FrameWorkException(<message pour l'utilisateur>);

  Pas de formatcode
  throw new FrameWorkException(Config.getInstance().getDisplayError());

  * Un constructeur qui permet de spécifier un message et d'envoyer un mail au responsable technique : FrameWorkException(<fichier de config contenant les informations relatives aux frameworkException>,<message d'erreur à indiquer dans le mail>);

  Pas de formatcode
  throw new FrameWorkException(Config.getInstance(),"CNabucoAdmin::CData::getXmlPers(String,String) : Erreur SQL " + e, MainChannel.stack2html(e));

  * Un constructeur qui permet en plus de spécifier l'état de la pile d'exécution au moment où l'exception est levée : FrameWorkException(<fichier de config >,<message d'erreur indiqué dans le mail>, <état de la pile>);

  Pas de formatcode
  throw new FrameWorkException(Config.getInstance(),"CNabucoAdmin::CData::getXmlPers(String,String) : Erreur SQL " + e, MainChannel.stack2html(e));

...

• Le framework posséde un mécanisme pour l'instanciation et la gestion des canaux servants
• Pour pouvoir utiliser un servant, il convient de définir dans le fichier de configuration une action de type "servant". Une action de ce type doit définir quatre attributs :
  • name, nom de l'action
  • type, "servant" donc
  • classname, la classe principale du servant
  • servantfinish, l'action qui doit être appelée par la mainChannel lorsque le servant rend la main

Exemple :

<action name="servantAnnuaire"
        type="servant"
        classname="org.esupportail.portal.channels.CAnnuaire.CAnnuaireServant"
        servantfinish="rechParPers" />

• Le mécanisme d'instanciation fixe les staticdata et les runtimedata du servant avec celles de la mainChannel. Il peut arriver que l'on veuille fixer des staticdata spécifiques au moment de l'instanciation du servant pour par exemple, dans le cas du servant annuaire, fixer l'annuaire à utiliser ou encore fixer le nombre de résultats que l'on attend en retour. Pour ce faire, il faut surcharger la méthode initServant() dans la classe principale de la channel "maître". Exemple :

public void initServant(IServant servant) throws PortalException {
     staticData.setParameter("serverView", Config.getInstance().getAnnuaire());
     if (this.currentAction.getName().equals("servantAnnuaire1")) {
	     staticData.setParameter("returnServant","single");
     }
     else if (this.currentAction.getName().equals("servantAnnuaire2"))
     	 staticData.setParameter("returnServant","multiple");
     super.initServant(servant);
}

• A partir du moment où l'action "servant " est appelée, l'ensemble des runtimedata sont passées au servant tant que la méthode isFinished() du servant ne renvoie pas "true"
• A la fin de l'exécution du servant, ses résultats sont stockées dans un tableau d'objet, variable d'instance de l'objet mainChannel. On les récupère grâce à la méthode getServantResults() de mainChannel. Les résultats restent disponibles tant que la méthode clearServantResults() n'est pas appellée

Services utiles fournis par le framework

...

• La méthode redirect permet, depuis une des méthode init, setXML ou setOutput d'une SubChannel, de se rediriger vers une autre action que l'action en cours. Dans ce cas, ne pas oublier de renvoyer Boolean.FALSE comme résultat de la méthode en cours (voir exemple)
• La méthode setConfigActions prend en paramètre une instance de fichier de configuration de type IConfigActions et remplit la liste des actions de la mainChannel
• Les méthodes getCurrentAction et getPreviousAction renvoient les actions en cours et précédentes (peuvent être NULL)
• La méthode getServantResults retourne la liste des objets résultats lorsqu'un servant est finished.
• La méthode logParams liste dans le fichier de log uPortal la liste des paramètres GET ou POST reçus par la MainChannel
• La méthode logConfigActions liste dans le fichier de log uPortal la liste des actions de la MainChannel
• La méthode getPrefForm renvoie une chaine unique pour l'instance de la channel qui peut servir à identifier de manière unique des objects javascipt (voir services de la SubChannel)
• La méthode clearServantResults efface le résultat de l'exécution d'un servant
• La méthode statique stack2string permet de renvoyer la pile d'exception sous forme de String.
• La méthode statique stack2html permet de renvoyer la pile d'exception sous forme de flux html (pour les mails d'erreur).
• La méthode log permet de d'enregistrer des informations dans uportal.log tout en profitant du paramétrage du niveau de log de la balise <actions> - Cette methode ne doit plus être utilisée

SubChannel

• La méthode clearChannel est la méthode qui est appelée lorsqu'une action a déjà été instanciée et qu'elle est réutilisée. Par défaut elle efface la liste des paramètres XSL. Il est possible de la surcharger.
• La méthode getXML est utilisée dans renderXML pour retourner la chaine XML qui a été fixée par setXML. Elle a la particularité d'envelopper le XML si cela n'a pas été fait par le développeur. Par exemple, si dans setXML on a fait :

xml = "<MESSAGE>Bonjour !</MESSAGE>";

alors getXML renverra

<?xml version=\"1.0\" encoding=\"ISO-8859-1\"?>
<xml>
<MESSAGE>Bonjour !</MESSAGE>
</xml>

• La méthode addDefaultXslParameters ajoute les paramètres XSL suivants à la liste des paramètres de l'action. Elle est appelée systématiquement dans renderXML donc vous en bénéficiez automatiquement :
  • baseActionURL qui permet de construire un lien http vers la channel elle-même
  • prefForm qui renvoie une chaine d'identification unique pour l'instance de la channel et peut donc servir à identifier de manière unique un formulaire javascript
  • mediaPath qui donne le chemin vers les médias de la channel (images par exemple)
• La méthode setDefaultXslParameters remplace les paramètres XSL courants par les paramètres par défaut.
• Les méthodes generateKey et isCacheValid gèrent le cache au niveau de la SubChannel. Il est possible de les surcharger.
• La méthode getMainChannel renvoie l'instance en cours de la MainChannel
• La méthode log permet de d'enregistrer des informations dans uportal.log tout en profitant du paramétrage du niveau de log de la balise <action> - Cette methode ne doit plus être utilisée

Autres classes du framework

...

• L'action default (obligatoire) sera celle qui présente la liste des liens
• On aura une action par type d'affichage mais qui pointeront toutes vers une même classe et une même méthode d'initialisation qui elle utilisera le plugin todo
• la page principale a un cache du type channel c'est à dire qu'elle est cachée pour la channel (quel que soit l'utilisateur)

 <actions>
   <action name="default"
   classname="RenderStatic"
   cachetype="channel"/>
   <action name="etat_civil"
   classname="RenderStatic"
   init="temp"/>
   <action name="inscriptions"
   classname="RenderStatic"
   init="temp"/>
   <action name="calendrier"
   classname="RenderStatic"
   init="temp"/>
   <action name="notes"
   classname="RenderStatic"
   init="temp"/>
   </actions>

...

• On créé une classe Config qui étend la classe ConfigChannel

public class Config extends ConfigChannel

• On implémente le mécanisme de singleton //déclaration des variables de la classe

  Pas de formatcode
  private static Config singleton = null; static { singleton = new Config(); } /** * * @return ConfigChannel Instance * @throws IOException * @throws JspException */ public static Config getInstance() { return singleton; }

  * On implémente la méthode getConfigFile qui indique où se trouve le fichier de configuration

 protected String getConfigFile() {
   return "/properties/channels/org_esup/CMonDossierWeb/CMonDossierWeb.xml";
   }

...

• Cette classe étend MainChannelpublic class CMonDossierWeb extends MainChannel* Création du constructeur qui charge la liste des actions avec la méthode setConfigActions et qui enregistre le plugin Todo à cette liste.

 public CMonDossierWeb() {
   setConfigActions(Config.getInstance());
   Todo.register(getConfigAction().getActions());
   }

• Les méthodes ChannelRuntimeProperties, receiveEvent et setStaticData ont un comportement par défaut dans la classe mainChannel

 public ChannelRuntimeProperties getRuntimeProperties() {
   return new ChannelRuntimeProperties();
   }

 public void receiveEvent(PortalEvent ev) {
   }

 public void setStaticData(ChannelStaticData sd) throws PortalException {
   staticData = sd;
   }

...

• Elle étend la classe SubChannel qui propose un comportement par défautpublic class RenderStatic extends SubChannel* Pour les besoins de cette channel (besoins très limités ) on a juste besoin d'implémenter la méthode temp (référencée pour les différentes actions dans le fichier de configuration) :noformat

public Boolean temp(ChannelRuntimeData rd) throws PortalException, FrameWorkException
{
   Todo.todo(getMainChannel(), rd, "default");
   return Boolean.FALSE;
   }

* Remarquez l'appel du plugin todo qui prend en paramètres l'instance de la channel principale, les runtimeData et l'action vers laquelle on est redirigé lorsque l'on clique sur OK dans ce plugin.

• Remarquez aussi que la méthode renvoie Boolean.FALSE car l'affichage est maintenant déporté sur le plugin et donc l'action en cours n'a pas à poursuivre son cycle de vie.

Plugins livrés avec le MAG

• Todo
• Message
• Confirm
• RestrictedAction