Référence WSDL pour portlet coopératifs

Le format WSDL est souvent associé à des services Web, afin de définir des interfaces mises en oeuvre par un service Web. Les éléments dans le fichier WSDL utilisés par click-to-action sont décrits, ainsi que les extensions de l'élément <binding> et le schéma des extensions WSDL.

Généralement, une liaison SOAP permet de spécifier la réalisation concrète de l'interface par un service Web qui prend en charge le protocole SOAP. Les paragraphes suivants montrent comment Click-to-Action utilise certains des éléments contenus dans le document WSDL. Vous y trouverez une description des extensions de l'élément <binding> ainsi que la totalité du schéma des extensions WSDL.

<types>
Pour les portlets coopératifs, cet attribut déclare le type des données à transférer. Cette déclaration s'effectue à l'aide des types de données du schéma SML (XSD, voir la page XSD specification). Il est possible de définir de multiples types dans le document.
Voici une déclaration de TrackingIDType :
```
    <types>
      <xsd:simpleType name="TrackingIDType">
        <xsd:restriction base="xsd:string">
        </xsd:restriction>
      </xsd:simpleType>
    </types>
   
```
<message>
Les messages d'entrée peuvent ne contenir qu'une seule partie.
<operation>
Fournit une définition abstraite d'une opération Click-to-Action. N'oubliez pas la restriction appliquée aux messages d'entrée mentionnée précédemment.
<portType>
Définit une collection abstraite d'opérations. Les opérations doivent être définies dans le document. Une opération correspond à chaque action effectuée sur le portlet activé pour Click-to-Action. Seules les actions activées pour Click-to-Action doivent être déclarées.
<binding>
Cet élément est étendu afin d'associer les actions de portlet à des opérations. Pour chaque opération, il faut fournir le nom de l'action du portlet. Ce nom peut être spécifié à l'aide de l'attribut name de la balise de l'action figurant dans la section de définition des liens du fichier WSDL. S'il est omis, l'attribut name de la balise de l'opération est utilisé en tant que nom de l'action du portlet.

Pour chaque paramètre d'opération, il faut fournir le nom du paramètre de l'action. Le nom du paramètre de portlet peut être spécifié avec l'attribut name de la balise de paramètre dans la section de définition des liens du fichier WSDL. S'il est omis, l'attribut name de la balise part associée à la balise param est utilisé en tant que nom de paramètre du portlet.

De plus, il est possible d'utiliser l'attribut boundTo pour spécifier l'emplacement où le paramètre sera lié. Vous avez le choix entre paramètre de requête, attribut de requête, attribut de session ou attribut d'action.

L'élément <binding> inclut des extensions de portlets coopératifs, décrites dans la sous-section Extensions de l'élément <binding>.

Si vous connaissez le langage WSDL, vous remarquerez peut-être que la section relative aux services (englobée par l'élément <service> dans WSDL) n'est pas utilisée dans le fichier de déclarations des actions C2A. En effet, le fichier est associé à un portlet particulier qui implémente les opérations définies dans le dit fichier par le biais d'un moyen externe (une entrée contenue dans le fichier portlet.xml associé au portlet).

Extensions de l'élément <binding>

L'élément <binding> a été étendu pour permettre la prise en charge de portlets coopératifs. Chaque élément d'extension contient le préfixe portlet:, qui fait référence à l'espace de nom de C2A, http://www.ibm.com/wps/c2a. Le préfixe portlet: permet d'identifier les éléments d'extension dans cette section, mais un nom différent peut être utilisé pour le préfixe tant qu'il fait référence à l'espace de nom de C2A. Voir Schéma d'extension de WSDL

<portlet:binding>
Il doit constituer le premier élément enfant de l'élément WSDL <binding>. Sa présence identifie la section en tant qu'extension de l'appel de l'action du portlet. Cet élément peut être associé à l'attribut suivant :
- style
  Déprécié. La spécification style="struts" indique que les actions Struts sont en cours de déclaration. A cet effet, utilisez type=struts sur l'élément <portlet:action> à la place.
<portlet:action>
Il doit constituer le premier élément enfant de l'élément WSDL <operation> dans la section de liaison. Il contient les attributs suivants :
- name
  Nom de l'action du portlet. S'il n'est pas indiqué, le nom de l'élément operation associé est utilisé en tant que nom de l'action du portlet.
- caption
  Courte chaîne relative à l'action convenant à l'affichage de l'interface utilisateur du portlet. Pour les libellés traduits, indiquez dans un format à points le nom de la clé figurant dans les regroupements de ressources à partir desquels obtenir le libellé.
- type
  Désigne l'une des valeurs suivantes :
  - default indique qu'un objet DefaultPortletAction est utilisé. Cet objet est déconseillé mais il est toujours pris en charge pour la migration.
  - simple indique qu'une chaîne d'action de portlet simple est utilisée.
  - struts indique qu'une action Struts est utilisée.
  - standard indique qu'une action de portlet (JSR) standard est utilisée.
  - standard-struts indique qu'une action Struts est utilisée avec un portlet (JSR) standard.
- actionNameParameter
  (Standard uniquement) Le nom du paramètre de requête qui sera utilisé pour fournir le nom de l'action.
- description
  Description sous forme de texte de l'action. Pour les descriptions traduites, indiquez dans un format à points le nom de la clé figurant dans les regroupements de ressources à partir desquels obtenir la description.
- activeOnStartup
  Indique la valeur "true" ou "false". Si la valeur est false, l'action doit être programmée pour être activée dans chaque session. Si la valeur est true (par défaut), l'action est active dès l'initialisation du portlet.
- selectOnMultipleMatch
  Dans le cas où plusieurs actions répondraient au critère de type de données du portlet, cet attribut permet de préciser l'action à déclencher. L'existence de multiples actions correspondantes peut s'expliquer lorsqu'un utilisateur diffuse une action portant sur une source. En l'absence de spécification, cet attribut prend par défaut la valeur false. Lorsque aucune action n'est définie par la valeur true, les données ne sont pas transmises à la cible.
  Dans l'exemple ci-dessous, extrait du fichier TrackingC2A.wsdl, deux actions sont déclarées : trackingDetails et routingDetails. selectOnMultipleMatch permet d'indiquer que l'attribut trackingDetails doit être utilisé en présence de correspondances multiples.
```
<binding name="TrackingBinding" type="tns:Tracking_Service">
   <portlet:binding/>
   <operation name="trackingDetails">
      <portlet:action caption="Tracking Details"
               description="Get tracking details for specified tracking id"
               selectOnMultipleMatch="true"/>
      <input>
          <portlet:param name="trackingId" partname="trackingId"/>
      </input>
      <output>
          <portlet:param name="customerName" partname="custName" 
                         boundTo="session"/>
      </output>
   </operation>
   <operation name="routingDetails">
      <portlet:action caption="Routing Details"
               description="Get routing details for specified tracking id"/>
      <input>
          <portlet:param name="trackingId" partname="trackingId"/>
      </input>
   </operation>
</binding>

   
```
<constant:param>
Sert à définir la valeur renvoyée par la méthode getConstantParameters de l'action. Chaque paramètre constant sera lié comme paramètre de requête avec le nom et la valeur spécifiés lorsque l'action est appelée. Plusieurs paramètres constants peuvent être spécifiés.
- name
  Nom du paramètre.
- value
  spécifie la valeur du paramètre.
L'exemple suivant illustre l'utilisation du paramètre constant.
```
	  <portlet:constant-params>
        <portlet:constant-param name="defaultMonth" value="January"/>
      </portlet:constant-params> 
```
<portlet:param>
Il doit apparaître en tant qu'élément enfant dans les sous-éléments <input> ou <output> de l'élément <operation> figurant dans la liaison. Il spécifie les paramètres fournis (lorsqu'il est imbriqué dans l'élément <input>) ou générés (lorsqu'il est imbriqué dans l'élément <output>) par l'action du portlet. A l'heure actuelle, le nombre de paramètres fournis se réduit à un au plus. Le nombre de paramètres générés n'est pas limité. Cet élément contient les attributs suivants :
- name
  Nom du paramètre. S'il n'est pas indiqué, la valeur de l'attribut de nom de l'élément part est utilisée en tant que nom du paramètre.
- partname
  Fait référence à un élément partiel de l'entrée ou de la sortie de l'opération. Il peut être omis si l'entrée ou la sortie n'et constituée que d'une seule partie.
- boundTo
  Spécifie l'emplacement où la valeur du paramètre est liée. A l'heure actuelle, cet attribut ne peut spécifier que l'une des valeurs suivantes :
  - request-parameter : Spécifie que la valeur est liée en tant que paramètre dans l'objet PortletRequest. Il s'agit de la valeur par défaut en cas d'omission de l'attribut boundTo. Vous remarquerez que, pour les paramètres de sortie, il faut généralement spécifier une valeur différente puisque l'implémentation par défaut de PortletRequest fournie par HCL Portal ne permet pas de définir des paramètres pendant le traitement des actions.
  - request-attribute : Spécifie que la valeur est liée en tant qu'attribut dans l'objet PortletRequest.
  - session : Spécifie que la valeur est liée à l'objet PortletSession.
  - action : Spécifie que la valeur est liée à une action de portlet.
  - render-parameter: (JSR uniquement) Spécifie que la valeur est liée comme paramètre d'affichage dans ActionResponse (paramètres de sortie uniquement).
- presentIfNullValue
  Spécifie si les valeurs nulles pour le paramètre sont significatives pour l'appel de l'action associée. La valeur peut être "true" ou "false", "false" étant la valeur par défaut. Avec la valeur "true", la présence du paramètre entraînera l'appel de l'action associée même si la valeur du paramètre est nulle. Avec la valeur "false", la présence du paramètre entraînera l'appel de l'action associée uniquement si la valeur du paramètre est non nulle. Peut être spécifié pour les paramètres d'entrée ou de sortie (c'est à dire que le traitement des valeurs de paramètres nulles peut être contrôlé depuis la source ou la cible).

Schéma d'extension WSDL

Vous trouverez ci-après le schéma associé aux éléments d'extensibilité introduits par l'appel de l'action du portlet à l'aide de Click-to-Action. Les lignes ont été rompues pour permettre l'impression sur une page.


<?xml version="1.0" encoding="UTF-8" ?>
<xsd:schema xmlns="http://www.w3.org/2001/XMLSchema"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               targetNamespace="http://www.ibm.com/wps/c2a"
               xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
               xsi:schemaLocation="http://schemas.xmlsoap.org/wsdl/ 
                                   http://schemas.xmlsoap.org/wsdl/ 
                                   http://www.w3.org/2001/XMLSchema 
                                   http://www.w3.org/2001/XMLSchema.xsd" 
               xmlns:portlet="http://www.ibm.com/wps/c2a">
   <!-- The binding  element indicates that the binding section 
       contains custom extensions describing a mapping of operations to 
       portlet actions. This must be placed within a WSDL 
       binding element. -->
<element name="binding" type="portlet:bindingType"/>
<complexType name="bindingType">
   <!-- DEPRECATED, retained for compatibility with version 4. Use the
   type attribute with the action element instead. Set value to be 
   "struts" for a portlet implemented using the struts framework. -->
   <attribute name="style" type="string" use="optional"/>
</complexType>
<!-- The action element is used to provide all the information 
  about the portlet action necessary for the property broker to
  invoke it. This must be placed within an wsdl:operation element 
  in the wsdl:binding section. -->
<element name="action" type="portlet:actionType"/>
<complexType name="actionType">
    <sequence>
        <!-- The constant-params element is used to provide constant
             parameters associated with the action. These are bound
             as request parameters when the action is invoked -->
        <element name="constant-params" type="portlet:constantParamsType"
             minOccurs="0" maxOccurs="1"/>
        </sequence>
         <!-- The name of the action. 
              Will be set as the portlet action name.  
              If omitted, the name of the corresponding operation 
              element will be used as the action name. -->
        <attribute name="name" type="string" use="optional"/>
        <!-- The type of the action. Currently recognized values
             are default, simple, struts, and standard, 
             with default being the default. 
             The values specify whether the legacy DefaultPortletAction,
             legacy simple portlet action, legacy portlet
             struts action, or standard (JSR-168) portlet 
             action mechanism is used to invoke the portlet action. 
             The use of DefaultPortletAction is 
             deprecated, and the default is set to this 
             value for backwards compatibility.-->
        <attribute name="type" type="string" use="optional" 
           default="default"/>
        <!-- A short name for  the action which is displayed to the 
          user.If a message resource file is 
          provided for the portlet,
          the value is used as a key to retrieve a translated string -->
        <attribute name="caption" type="string" use="optional"/>
        <!-- A description for  the action which is
             displayed to the user. 
             If a message resource file is provided for the portlet, the
             value is used as a key to retrieve a translated string -->
        <attribute name="description" type="string" use="optional"/>
        <!-- If more than one portlet action can simultaneously process 
             a property value, only those with the 
             invokeOnMultipleMatch attribute
             set to true will be invoked -->
        <attribute name="selectOnMultipleMatch" type="boolean" 
           use="optional" default="false"/>
        <!-- If the activeOnStartup attribute is true, 
             the action may be selected for invocation 
             at any time unless  programmatically
             deactivated on a per-session basis. 
             If the activeOnStartup is false, the action may not be 
             selected for invocation, unless
             programmatically activated on a per-session basis -->
        <attribute name="activeOnStartup" type="boolean" 
           use="optional" default="true"/>
        <!-- The actionNameParameter attribute is used to specify
             the name of a request parameter whose value will carry
             the action name. It is recommended that all actions of
             a portlet use the same value of this parameter. This is
             used to identify the specific action which is being executed
             on the portlet, as the processAction method in JSR 168
             does not explicitly pass any information identifying the
             action. If this attribute is omitted, the
             actionNameParameter value defaults to 
             com.ibm.portal.propertybroker.action -->
        <attribute name="actionNameParameter" type="string" 
           use="optional" 
           default="com.ibm.portal.propertybroker.action"/>
    </complexType>
    <complexType name="constantParamsType">
        <!-- The constant-params element is used to provide constant
             parameters associated with the action. These are bound
             as request parameters when the action is invoked -->
        <sequence>
        <!-- The constant-param element is used to provide a name
             and a value which will be bound as a request parameter
             when the portlet's action is invoked -->
        <element name="constant-param" type="portlet:constantParamType" 
         minOccurs="0" maxOccurs="unbounded"/>
        </sequence>
    </complexType>
    <complexType name="constantParamType">
        <!-- The constant-param element is used to provide a name
             and a value which will be bound as a request parameter
             when the portlet's action is invoked -->
        <!-- The name of the constant-parameter -->
        <attribute name="name" type="string" use="required"/>
        <!-- The value of the constant-parameter -->
        <attribute name="value" type="string" use="required"/>
    </complexType>
    <!-- The param element is used to indicate information 
             about the input or output property associated with the 
             action and the mechanism for passing parameters to or from
             the action. It must be placed within a
             wsdl:input or wsdl:output element. -->
    <element name="param" type="portlet:paramType"/>
    <complexType name="paramType">
    <!-- The param element indicates how the parameter is to be 
         delivered to the portlet action or retrieved from 
         it once the action has executed -->
        <!-- The name of the parameter which will be used on 
         action invocation. If omitted, the partname is used. 
         This name will also be set as the name of the 
         corresponding property. -->
        <attribute name="name" type="string" use="optional"/>
        <!-- The name of the corresponding part. May be omitted only if 
             there is a single parameter for the action, 
             in which case it will be inferred from
             the associated operation definition -->
        <attribute name="partname" type="string" use="optional"/>
        <!-- Where to place the parameter prior to invoking the action 
             (in case of in parameters), or where to look for it 
             after invoking the action (in case of out parameters).
             request-attribute, request-parameter, session are
             allowed for both standard and legacy portlets. A value of
             action is allowed for legacy portlets only, and a value
             of render-parameter is allowed for standard portlets only 
        -->
        <attribute name="boundTo" type="string" 
         default="request-parameter"/>
        <!-- If the parameter is found but its value is null, this attribute
        determines if the parameter is deemed to be present for brokered
        communication purposes. If the value is set to true, the parameter
        is deemed to be present and the null value will be propagated. The
        default is false. 
        -->
        <attribute name="presentIfNullValue" type="string" 
         default="false" use="optional"/>
        <!-- The java class for the parameter. 
             The default is java.lang.String. 
             If a non-default value is provided, it will be
             used in conjunction with type and namespace to 
             restrict matches
        -->
        <attribute name="class" type="string" 
         default="java.lang.String"/>
        <!-- A short name for the parameter which is displayed 
             to the user. If a message resource file is 
             provided for the portlet,
             the value is used as a key to retrieve a 
             translated string -->
        <attribute name="caption" type="string" use="optional"/>
        <!-- A description for  the parameter which is displayed to the 
             user. If a message resource file is provided for the 
             portlet, the value is used as a key to retrieve a 
             translated string -->
        <attribute name="description" type="string" use="optional"/>
    </complexType>
</xsd:schema>