Enabling cooperative targets

Enabling cooperative targets for both Click-to-Action and wired portlets includes the following activities:
  1. Enabling the cooperative target
  2. Implementing the action
  3. Providing translations

To enable a cooperative target:

  1. Enable the cooperative target, as described in the following steps:
    1. In the Project Explorer view, select a portlet or the Portlet Deployment Descriptor. Portlets are displayed when you expand the Portlet Deployment Descriptor node under the portlet project folder.
    2. Right-click the desired portlet, and select Cooperative > Enable Target from the pop-up menu. The Enable Cooperative Target dialog appears. Alternatively, open a JSP file, ensure that it has focus, and select the Page > Cooperative > Enable Target menu option.
      Enable Cooperative Target dialog
    3. Provide values for the following fields:
      Data type (Required)
      Specify a name of the data type of the data to be transferred by the source portlet. Alternatively, if the data type you want to publish has been already declared, click the Browse button to open the Select Type dialog and select a WSDL data type that you wish to publish. The data type and the namespace in the WSDL file will be specified in each field. The specified value will be used to declare the data type in the <types> element in WSDL file.
      Namespace
      Specify the namespace for the type. For example, "http:/www.yourco.com/c2a". When an existing WSDL file is specified below, the field gets disabled. The specified value will be stored in WSDL file and will be used in conjunction with the Data type name to uniquely identify the output property's data type to the cooperative runtime environment.
      [Target action] Name (Required)
      Specify the portlet action name. This target action name is used as the invocation target by the property broker. The property broker, once it identifies that the target portlet's input property matches an output property that it previously obtained, will invoke the target action on the target portlet and make the input property value available to the target portlet.

      If any Faces actions associated with command-controls or Struts actions defined in Struts configuration files are available, you can select from among them in the Select Action dialog. To open this dialog, click the Browse button. The specified value will be stored in WSDL file as the name attribute of <portlet:action> element.

      Name parameter (optional, only for JSR 168 portlets)
      Specify the portlet action name parameter. When the cooperative target is a JSR 168 API portlet, the property broker will set this particular parameter in the action request when invoking the target portlet. This is how the property broker communicates to the target portlet that an invocation has occurred, and an input property will be available. Accordingly, in the target portlet control logic, whenever a request parameter of this name is available, with a value matching the value of the Parameter field, it indicates that an invocation by the property broker has occurred.

      For JSR 168 Struts portlets, the action name parameter must be specified as spf_strutsAction.

      [Parameter] Parameter (Required)
      Specify the name of the parameter whose value will be the input property, so that the property broker can make it available to target portlets. This value is used in conjunction with the value for the Bound to field, which specifies the location of the parameter, so that the property broker can precisely determine how to set the input property.

      The specified value will be stored in the WSDL file as the name attribute of <portlet:param> element.

      Caption (optional)
      Specify a caption for the parameter that contains the input property. This caption is used by the wiring tool to identify a particular input property.
      Note: This field takes a key in the resource bundle, as described below, as opposed to the actual string value.
      Bound to
      Specify where the property broker should put the input property to make it available to the target portlets. This value is used in conjunction with the value for the Parameter field, which specifies the name of the parameter, so that the property broker can precisely determine how to set the input property. Currently, this attribute can specify one of the following values only:
      • request-parameter: This specifies that the value is bound as a parameter in the PortletRequest object. This is the default value if the boundTo attribute is omitted. Note that for output parameters, a different value should usually be specified as the default PortletRequest implementation provided by WebSphere® Portal does not allow parameters to be set during action processing.
      • request-attribute: This specifies that the value is bound as an attribute in the PortletRequest object.
      • session: This specifies that the value is bound to the PortletSession object.
      Label
      Specify a short string about the action suitable for displaying in the portlet user interface. Both the WebSphere Portal Portlet Wiring Tool and the Click-to-Action runtime environment use it for identifying the target action to invoke. If this value is left blank, or the resource bundle does not have a valid entry that corresponds to the key value specified here, the wiring tool and the Click-to-Action runtime environment will default to using the action Name specified above, instead.

      For translated captions, specify the name of the key in the resource bundles. Specify the translated captions in the key=translated caption format in the resource bundles that are specified in the Resources bundle field in this dialog. The specified value will be stored in WSDL file as the caption attribute of <portlet:action> element.

      Wiring tool example:

      Click-to-Action example:
      Click-to-Action portlet displaying a label

      Description
      Specify a text description of the action. The value is documented in the WSDL file.

      For translated descriptions, specify the name of the key in the resource bundles. Specify the translated description in the key=translated description format in the resource bundles that are specified in the Resources bundle field in this dialog. The specified value will be stored in WSDL file as the description attribute of <portlet:action> element.

      Resource bundle
      Specify the base name of an NLS resource file containing translated texts that correspond to labels and descriptions of actions and properties.

      The specified base name will be defined by the c2a-nls-file configuration parameter in the portlet deployment descriptor, and an empty resource bundle will be generated under the Java Resources node. For example, if you enter nls.shippingc2a, then you will edit the language-specific resource bundle: nls\shippingc2a<_lang>.properties under the JavaSource node to specify translated captions and descriptions in the key=translated text format.

      Target portlet (Required)
      Specify the concrete portlet to be enabled as the cooperative target.
    4. Click OK. The Click-to-Action-enabled portlet is shown with a target portlet icon (Click-to-Action Target Portlet icon) in the Project Explorer view.
  2. Ensure that the code for the target portlet class meets the following requirements:
    • The action must be implemented either as a portlet action, a Faces action or a Struts action. For portlet actions, you should use the simple action Strings rather than the deprecated PortletAction class.
    • Portlet actions must accept a single parameter. The parameter may appear as a request parameter, a request attribute, a session attribute, or an action attribute (deprecated), as specified in the action declaration or registration.

    The following example shows the actionPerformed() method of the OrderDetailPortlet.java in the Cooperative Portlets application sample from the Sample Gallery. This portlet accepts the ORDER_ID parameter in its actionPerformed() method. This parameter corresponds to an input parameter in the binding section of the portlet's WSDL file ( OrderDetailC2A.wsdl in this example).

    ...
    
       private static final String PREFIX = "";
       public static final String ORDER_ID = PREFIX + "orderId";
       public static final String TRACKING_ID = PREFIX + "trackingId";
    
    ...
        
        public void actionPerformed (ActionEvent event) 
        {
    //        DefaultPortletAction action = (DefaultPortletAction) event.getAction();
       String actionName = event.getActionString();
    
            PortletRequest request = event.getRequest();
    
            //An action causes the state to be modified
            ShippingUtils.setLastModified(request);
    
           if( getPortletLog().isDebugEnabled() ) {
               getPortletLog().debug("OrderDetailActionListener - Action called");
           }
           
            if (actionName.equals(ORDER_DETAILS)) {
                request.getPortletSession().setAttribute(ACTION_NAME, ORDER_DETAILS);
                request.getPortletSession().setAttribute(ORDER_ID, request.getParameter(ORDER_ID));
    
           //We do this as tracking id is an out param in the C2A WSDL file
           //We write the tracking id in the request so it can be published by
           //the broker in the same event cycle
                String orderId = (String) request.getPortletSession().getAttribute(ORDER_ID);
           OrderDetail od = ShippingDB.getOrderDetail(request.getParameter(ORDER_ID));
                request.getPortletSession().setAttribute(ORDER_DETAIL, od);
           request.setAttribute(TRACKING_ID, od.getTrackingId());
    
            }  else if (actionName.equals(ORDER_ID_ENTRY)) {
                request.getPortletSession().setAttribute(ACTION_NAME, ORDER_ID_ENTRY);
       }
        }
    ...
  3. Provide translated text that corresponds to the label and description in the resource bundle files. The base name of resource bundle is specified in the Resource bundle field and it is stored by the c2a-nls-file configuration parameter in the portlet deployment descriptor. Edit the language-specific resource bundles under the JavaSource node. To specify translated captions and descriptions, use the key=translated text format and keys that are specified as the Label and Description.

The Enable Cooperative Target action performs the following tasks for you.

  1. Modifies web.xml to add a servlet class entry to refer to the property broker classes [IBM portlet API only]:
    <servlet-class>com.ibm.wps.pb.wrapper.PortletWrapper</servlet-class>
    <init-param>
       <param-name>c2a-application-portlet-class</param-name>
       <param-value>servlet-class</param-value>
    </init-param>
  2. Modifies portlet.xml:
    • To add a configuration parameter to each concrete portlet that receives the input property broker through the WSDL file and to specify the base name of a national language resource file.
      <config-param>
              <param-name>c2a-action-descriptor</param-name>
              <param-value>WSDL file</param-value>
      </config-param>
      <config-param>
              <param-name>c2a-nls-file</param-name>
              <param-value>resource bundle name</param-value>
      </config-param>
    • To add a configuration parameter for a Faces portlet to specify the target action name and its parameter name.
  3. Imports an additional library, pbportlet.jar, to /WEB-INF/lib in the portlet project for use of the property broker. [IBM portlet API only]
  4. Creates a WSDL file with the following sections:
    <definitions>
    Acts as root.
    <types>
    The data type is declared using XML Schema Datatypes (XSD).
    <message>
    An output message.
    <portType>
    Defines an abstract collection of operations. <output>.
    <binding>
    Always extended to <portlet:binding> to identify the section as a cooperative binding extension for portlet action invocation.
  5. Generates a resource bundle file that includes the key value (from the key=translated string text format) that was specified in Label field in the Enable Cooperative Target dialog.
Related concepts
Developing cooperative portlets
Related tasks
Enabling existing portlets for cooperation
Enabling cooperative sources
Enabling cooperative targets without a Faces action
Inserting Click-to-Action encodeProperty
Inserting Click-to-Action encodeProperties
Editing Click-to-Action encodeProperty
Editing Click-to-Action encodeProperties
Related reference
Web Services Description Language (WSDL) 1.1
WebSphere Portal Information Center
XML Schema Part 2: Datatypes
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.