Interoperability between JSR 286 portlet events and JSR 168 cooperative portlets | HCL Digital Experience
By concept, cooperative portlets are similar to JSR 286 portlet events. Both concepts describe publish/subscribe communication patterns that are based on typed information that is published and received by portlets and propagated via communication links.
Because the concepts are quite similar, the portal supports data exchange between JSR 168 cooperative portlets and JSR 286 portlets that support events. This means that you can extend an existing setup using JSR 168 cooperative portlets with new JSR 286 portlets and that you can smoothly migrate individual cooperative portlets to the new API without losing communication possibilities.
Aspect of similarity | Cooperative portlets | JSR 286 events |
---|---|---|
Event declaration | in a WSDL deployment descriptor | as part of portlet.xml |
Sending data | as a side effect of action processing, for example by setting a request attribute that is declared as an output property | by using the portlet API setEvent() call on an
action or event response |
Receiving data | as a portlet action with input properties, for example, request parameters | by using the portlet API processEvent()
callback |
Writing interoperable portlets
In both models, portlets declare their external inputs and outputs so that they can be matched for communication. The outputs and inputs are matched based on an XML qualified name, which is associated with an XML namespace to make it globally unique. For JSR 286 portlets, the matching information is denoted by the event name while for cooperative portlets, the matching is based on XML data type declared or referenced in the WSDL. In addition, inputs and outputs carry data that has a specific Java language data type.
- The XML type name of the action's output property matches the name or an alias of the processing event.
- The Java type of the output property is the same as the Java type of the procesing event payload.
- The name or an alias of the publishing event matches the XML type name of the action's input property.
- The Java type of the publishing event payload is the same as the Java type of the input property.
- A JSR 286 event without an associated Java type (no
<value-type>
declaration) cannot be connected with a cooperative portlet. - Exchanged data types must be primitive types or they must be Java and JAXB serializable (because JSR 286 requires this) and deployed in a shared class loader (because cooperative portlets do not support cross-class loader marshalling).
Example for migrating deployment descriptors
The following cooperative portlet WSDL declares a portlet action OrdersForMonth that takes a month name as input and produces an order ID and a customer ID as outputs.
<definitions name="OrderDetail_Service"
xmlns="http://schemas.xmlsoap.org/wsdl/"
targetNamespace="http://www.ibm.com/wps/c2a/examples/shipping"
xmlns:shipping="http://www.ibm.com/wps/c2a/examples/shipping"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<types>
<xsd:schema targetNamespace="http://www.ibm.com/wps/c2a/examples/shipping">
<xsd:simpleType name="MonthType">
<xsd:restriction base="xsd:string"/>
</xsd:simpleType>
<xsd:simpleType name="OrderIDType">
<xsd:restriction base="xsd:string"/>
</xsd:simpleType>
<xsd:simpleType name="CustomerIDType">
<xsd:restriction base="xsd:string"/>
</xsd:simpleType>
</xsd:schema>
</types>
<message name="OrderMonthRequest">
<part name="order_month" type="shipping:MonthType"/>
</message>
<message name="OrderMonthResponse">
<part name="order_Id" type="shipping:OrderIDType"/>
<part name="customer_Id" type="shipping:CustomerIDType"/>
</message>
<portType name="OrderMonth_Service">
<operation name="order_Month">
<input message="shipping:OrderMonthRequest"/>
<output message="shipping:OrderMonthResponse"/>
</operation>
</portType>
<binding name="OrderMonthBinding" type="shipping:OrderMonth_Service">
<portlet:binding/>
<operation name="order_Month">
<portlet:action name="OrdersForMonth" type="standard"/>
<input>
<portlet:param name="month" partname="order_month" class="java.lang.String"/>
</input>
<output>
<portlet:param name="orderId" partname="order_Id"/>
<portlet:param name="customerId" partname="customer_Id"/>
</output>
</operation>
</binding>
</definitions>
The containing portlet can be converted to a JSR 286 portlet that exposes the same external
behavior. Each action that has an input property becomes a processing event that can be sent
to the portlet. Each output property of an action becomes a publishing event that can be
emitted by the portlet. The wiring behavior can be maintained by declaring an alias for each
event that has the same name as the WSDL data type of the corresponding input or output
parameter: For example, the customerId.published
event
declares an alias shipping:CustomerIDType
so that it can be
wired to any processing event or portlet action that takes a customer ID as input.
<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"
xmlns:shipping="http://www.ibm.com/wps/c2a/examples/shipping"
version="1.0">
<portlet ...>
...
<supported-processing-event>
<qname>shipping:OrdersForMonth</qname>
</supported-processing-event>
<supported-publishing-event>
<qname>shipping:orderId.published</qname>
</supported-publishing-event>
<supported-publishing-event>
<qname>shipping:customerId.published</qname>
</supported-publishing-event>
</portlet>
<event-definition>
<qname>shipping:OrdersForMonth</qname>
<alias>shipping:MonthType</name>
<value-type>java.lang.String</value-type>
</event-definition>
<event-definition>
<qname>shipping:orderId.published</qname>
<alias>shipping:OrderIDType</name>
<value-type>java.lang.String</value-type>
</event-definition>
<event-definition>
<qname>shipping:customerId.published</qname>
<alias>shipping:CustomerIDType</name>
<value-type>java.lang.String</value-type>
</event-definition>
</portet-app>
- The fact that the cooperative portlet properties use
java.lang.String
as data type and that the corresponding events must be declared with<value-type>java.lang.String
depends only on theclass="java.lang.String"
attribute of the <portlet:param>WSDL element. If no class attribute is present,java.lang.String
is also used as default value. The XML type declarations in the WSDL are not used to determine the Java type of a property. - The declaration of cooperative portlet actions does not allow multiple input parameters. Actions or events that require multiple inputs must instead be declared with a single compound input property or event payload that combines all required data.