Cooperative portlet programming model

View information on how properties and actions are registered, how properties are generated and received, and some available APIs.

Registering properties and actions

The declarative method can be used with either standard portlets or IBM portlets, and is the only registration implementation supported for standard portlets. The programmatic method can be used only with IBM portlets.

• All portlets:

  Declarative (WSDL)

  Target portlets associate their actions with an input property which has been declared as an XML type. The actions are declared using WSDL, with a custom binding extension which specifies the mapping from the abstract action declaration to the actual action implementation. WSDL is a language used to define collections of abstract operations, together with the input and output parameters (called parts in WSDL) for each operation.

  Associated with each action is zero or one input parameters and zero or more output parameters. Each input or output parameter is associated with exactly one property. Each property is associated with an XML type. The input property's type is used for matching the action to output properties which are produced by portlets. The output parameters are produced as a result of executing the action, and can be wired to other actions subject to the type matching constraint mentioned previously. Fewer changes need to be made to portlets to enable them to interact with other cooperative portlets using the declarative approach versus the programmatic approach. Existing portletso that already use action processing can often simply declare their actions to the property broker using WSDL without making additional source code changes.

  Fewer changes need to be made to existing portlets to enable them to interact with other cooperative portlets using the declarative approach versus the programmatic approach. Existing portlets that already use action processing simply declare their actions to the property broker using WSDL.

• IBM portlets only:

  Programmatic

  Registration of properties can be done programmatically only for IBM portlets. Properties can be registered programmatically using the registerProperties() method from the PropertyBrokerService interface.

Generating property values

• All portlets:

  Action bindings

  The WSDL custom binding extension provides mapping information from the abstract operation declaration to the actual action implemented by the portlet. The custom binding extension defines how information is delivered to the action implementation and received from the action implementation. Actions can generate output properties to transfer information, and the binding used in the implementation must match the parameter binding declared in the WSDL file.

• IBM portlets only:

  • JSP tags

    JSP tags should be used to implement dynamic displays for the user.

    For example, Click-to-Action tags such as...

    • <c2a:encodeProperty/>
    • <c2a:encodeProperties/>

    ...can be used to create Click-to-Action menus.

    Source portlets use has a set of custom JSP tags to specify the type and value of the data being contributed. At the point where such a tag occurs, the property broker inserts markup that can display the menu of action choices for the user. The markup provides a standard icon which displays a menu when clicked and allows the user to initiate the transfer of the output property. Once a wire has been created, clicking on the icon does not display a menu but triggers the wired actions instead. The output property is propagated according to the settings saved in the wire.

    Advanced options on the JSP tags allow the programmer to indicate whether a broadcast action is to be added to the menu, or to scatter of has a set of property values (rather than a single value) to all portlets. The appearance of the icon and menu can be determined by the theme and can also be overridden programmatically. WebSphere Portal provides the default icons in...

    PORTAL_HOME /installer/wp.ear/installableApps/wps.ear/wps_theme.war/themes/html/

    ...which include...

    • c2a.gif
    • c2amultiple.gif
    • c2awired.gif
    • c2amultiplewired.gif

    The menu look can be controlled using menu style attributes in the theme's CSS files.

  • Programmatic

    A new output property can be created and passed to the broker using the changedProperties() method in the PropertyBrokerService interface.

Receiving property values

• All portlets:

  Action bindings

  Action bindings may also be used to receive property values. The bindings used to provide the property values to the action implementation will match the input parameter bindings specified in the WSDL file.

• IBM portlets only

  PropertyListener interface

  An IBM target portlet can receive property changes directly through the setProperties method of the PropertyListener interface.

Advanced programmatic APIs

For both standard and IBM portlets, the property broker provides additional APIs to give developers more control over inter-portlet communication. The following functionality can be implemented using the programmatic APIs:

• All portlets:

  • Activate or deactivate actions for a session. Only active actions can be triggered through wires or through Click-to-Action menus.

  • Determine if a property is wired, and if it is a cross-page wire. It can also determine if the wire is actually active (the target action is active). This knowledge may be used to render links for triggering wired actions.

• IBM portlets only:

  • Publish output properties using the changedProperties() method instead of using action bindings.

  • Register actions programmatically instead of declaring them in a WSDL file. This alternative may be useful when the portlet is generated using a builder tool.

  • Generate Click-to-Action markup using an API call instead of JSP tags. This allows the Click-to-Action menus to be associated with arbitrary clickable elements.

  • Use the setProperties() method to receive change notifications instead of using action bindings.

Both sources and targets must register their input and output properties and actions for wire creation to be possible.

The following packages define the programmatic APIs provided by the property broker.

• Standard portlets

  • com.ibm.portal.propertybroker.service.PropertyBrokerService (this is an interface)

• IBM portlets
  • com.ibm.wps.pb.property
  • com.ibm.wps.pb.portlet
  • com.ibm.wps.pb.service

Parent: Cooperative portlets
Related:
Cooperative portlets overview
Packaging, deploying and compiling cooperative portlets
WSDL reference for cooperative portlets