Enabling cooperative sources

To enable a cooperative source in preparation for wiring portlets, perform 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 Source from the pop-up menu. The Enable Cooperative Source dialog opens. Alternatively, open a JSP page, ensure that it has focus, and select Page > Cooperative > Enable Source from the menu.
    Enable Cooperative Source dialog
  3. Provide values for the following fields:
    Data type
    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. The specified value will be stored in a 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.
    [Source action] Name
    Specify the portlet action name. The execution of the specified action will trigger the property broker to send the output property to the target portlet(s).

    For the IBM® portlet API, the action name specified here is the one that this portlet receives as ActionEvent.getActionString(). For a Faces portlet that uses the IBM portlet API, the action name should be com.ibm.faces.portlet.ACTION. For the JSR 168 portlet API, the action name specified here is the value of the action request parameter specified in Name parameter below.

    Name parameter (optional, only for JSR 168 portlets)
    Specify the action name parameter. When the cooperative source is a JSR 168 API portlet, the property broker will look for this particular parameter in the action request. In the example dialog above, when a parameter with the name ACTION_NAME and value MyAction is present in an action request, the property broker will recognize that an output property is being published, and will perform the appropriate operations to retrieve the output property value.

    If Name parameter is omitted, an action request parameter, com.ibm.portal.propertybroker.action, is used to specify the action name.

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

    [Parameter] Parameter
    Specifies the name of the parameter whose value will be the output property, so that the property broker can retrieve it and 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 retrieve the published output property.
    Caption (optional)
    Specify a caption for the parameter that contains the output property. This caption is used by the wiring tool to identify a particular output 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 published output property is located, so that the property broker can retrieve it to make it available to target portlets. This value is used in conjunction with the value of the Parameter field, which specifies the name of the parameter, so that the property broker can precisely determine how to retrieve the published output property. Currently, this attribute can specify one of the following values only:
    • render-parameter: [JSR 168 API only] This specifies that the value is bound as a render parameter in the ActionResponse (output parameters 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.

    The following example shows the actionPerformed() method of the OrderDetailPortlet.java in the Cooperative Portlets application sample from the Sample Gallery. The portlet passes the TRACKING_ID parameter to property broker in its actionPerformed() method. This parameter corresponds to an output parameter in the binding section of the portlet's WSDL file ( OrderDetail.wsdl, in this example).

    OrderDetailPortlet.java
    OrderDetailPortlet.java
    
    
    ...
    	private static final String PREFIX = ""; //$NON-NLS-1$
    	public static final String ACTION_NAME = PREFIX + "actionName"; //$NON-NLS-1$
    	public static final String ORDER_DETAILS = PREFIX + "orderDetails"; //$NON-NLS-1$
    	public static final String ORDER_ID_ENTRY = PREFIX + "orderIdEntry"; //$NON-NLS-1$
    	public static final String ORDER_ID = PREFIX + "orderId"; //$NON-NLS-1$
    	public static final String ORDER_DETAIL_BEAN = PREFIX + "orderDetailBean"; //$NON-NLS-1$
    	public static final String ORDER_DETAIL = PREFIX + "orderDetail"; //$NON-NLS-1$
    	public static final String TRACKING_ID = PREFIX + "trackingId"; //$NON-NLS-1$
    ...
    	public void actionPerformed(ActionEvent event) {
    		String actionName = event.getActionString();		PortletRequest request = event.getRequest();		//An action causes the state to be modified
    		ShippingUtils.setLastModified(request);		if (getPortletLog().isDebugEnabled()) {
    			getPortletLog().debug(Messages.getString("OrderDetailPortlet_action_entry")); //$NON-NLS-1$
    		}		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
    			 */
    			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);
    		}
    	}
    ...
    OrderDetail.wsdl (The property broker receives the tracking ID parameter from the request attribute.)
    ...
    <binding 
        name="OrderDetailBinding" 
        type="tns:OrderDetail_Service">
      <portlet:binding></portlet:binding>
      <operation name="order_Detail">
        <portlet:action name="orderDetails" type="simple" caption="Order.Details" description="Get.details.for.specified.order.id"/>
        <input>
          <portlet:param name="orderId" partname="order_Id" caption="order.id"/>
        </input>
        <output>
          <portlet:param name="trackingId" partname="tracking_Id" boundTo="request-attribute" caption="tracking.id"/> 
        </output>
      </operation>
    </binding>
    
    ...
    Resource bundle (optional)
    Specify the base name of a national language resource file that contains captions and descriptions of actions and properties. If you want to display a readable string in the Portlet Wiring Tool on the server or in Portal Designer, you should specify a resource bundle with a key specified to correspond with the Caption field.

    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 edit the appropriate language-specific resource bundles: nls\shippingc2a<_lang>.properties to specify translated captions and descriptions in the key=translated text format.

    Source portlet (Required)
    Specify the concrete portlet to be enabled as the cooperative source.
  4. Click OK. The cooperatively-enabled portlet is shown with a source portlet icon ( Cooperative source portlet icon) in the Project Explorer view.

The Enable Cooperative Source 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 configuration parameters to each concrete portlet that exposes actions to the property broker through the WSDL file, and specifies 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>
  3. Imports an additional library, pbportlet.jar, to /WEB-INF/lib in the portlet project for use by the property broker. [IBM portlet API only]
  4. Creates the specified 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.
Related concepts
Developing cooperative portlets
Related tasks
Enabling existing portlets for cooperation
Enabling cooperative sources with a Faces action
Enabling cooperative targets
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.