Concepts of cooperative portlets

 

+

Search Tips   |   Advanced Search

 


Content

  1. Overview
  2. Features of cooperative portlets
  3. Property broker runtime components
  4. Event handling
  5. Sample flow of cooperative portlet interaction
  6. Property transfer using wires
  7. Property broker programming model

 

Overview

Cooperative portlets subscribe to a model for declaring, publishing, and sharing information with each other using the WebSphere Portal property broker. Portlets subscribe to the broker by publishing typed data items, or properties, that they can share, either as a provider or as a recipient.

  • The portlet that provides a property is called the source portlet.

  • The properties that the source portlet publishes are called output properties.

  • The portlet that receives a property is called the target portlet.

  • The properties that are received by the target are called input properties.

Target portlets optionally provide actions to process the properties that it receives. Action processing in target portlets often does not need to distinguish between an action initiated within its own portlet area and an action initiated by the transfer of a portlet property value. Each action is also associated with a single input parameter and zero or more output parameters. Each parameter is associated with exactly one property. A parameter provides additional information about how the property value is transferred to or from the action. Parameters associated with input properties are called input parameters, while those associated with output properties are called output parameters.

At runtime, the property broker matches the data type of output properties from a source portlet with the data type of input properties from one or more target portlets. If a match is determined, the portlets are capable of sharing the property. The actual transfer of the property can be initiated by one of the following methods:

  • JSR 168 Compliant and IBM

    • Using the Portlet Wiring Tool, a user can create a persistent connection between two portlets, called a wire. This allows portlets to exchange properties.

    • The source IBM portlet can do a programmatic publish of properties to the broker when it determines that property values have changed. Such property values are transferred to the target(s) only if wires have been created. While only IBM portlets have a programmatic API for publishing, both IBM and JSR 168 portlets can make new property values available to the broker as a side-effect of actions.

  • IBM portlets only

    • A user launches a Click-to-Action event from an icon on the source portlet. The icon presents a pop-up menu containing the list of targets for the action. After the user selects a specific target, the property broker delivers the data to the target in the form of the corresponding portlet action. Using the Click-to-Action delivery method, users can transfer data with a simple click from a source portlet to one or more target portlets, causing the target react to the action and display a new view with the results. Such transfer is performed without requiring the targets to be wired to the source. The user can also broadcast the property to all portlets on the page that have declared an action associated with a matching input property.

    • A user holds the Ctrl key while clicking a Click-to-Action icon action and chooses to have the action selection(s) from the menu saved persistently. This results in the property associated with the icon being wired to the target action(s). If a wire is present the next time the user clicks on the icon, no selection menu is shown. Instead the wired action(s) are automatically fired. Subsequent updates to that property are transferred without further deliberate user choice.

      Wires can also be created using the Portlet Wiring Tool.

    Currently, a JSR 168 compliant portlet cannot be wired to an IBM portlet. Wires can only be created between portlets using the same standard. For example, JSR 168 compliant portlets can only be wired to other JSR 168 compliant portlets.

Cooperative portlets can be source portlets, target portlets, or both.

  • Source portlets identify to the property broker properties which they are able to share with other portlets.

  • Target portlets identify to the property broker actions which are able to process properties contributed by other portlets.

 

Features of cooperative portlets

The property broker is used to facilitate development of portlets that may be dynamically integrated, without requiring previous coordination at development time. Portlets may be developed and deployed separately or together, but as compatible portlets are placed on the page, they can exchange information and react in a coordinated manner, thus improving the end-user experience. Conversely, as portlets are removed from the page, the remaining portlets on the page will still be able to function correctly and in a coordinated manner.

Some of the specific features of cooperative portlets include:

  • JSR 168 compliant and IBM:

    • Property transfers saved as wires:

      Users and administrators can create wires between cooperative portlets using the Portlet Wiring Tool. For IBM portlets only: Users can combine the Ctrl key while clicking on a Click-to-Action icon to save the property transfer preferences as wires between portlets on a page. The next time the user clicks on the icon, the saved menu selection is used and the property is transferred without prompting the user.

    • Chained propagation of data transfer

      Sending data to one portlet can cause that portlet to send data to another portlet, which can in turn transmit data. This feature supports the synchronization of multiple portlet views in a single request-response cycle. For example, transferring the order ID to the Order Details portlet also triggers the transfer of the tracking ID for the order to the tracking details portlet, which in turn triggers the transfer of the customer name associated with the order to the customer details portlet, causing all three to display information pertaining to the same order. The property broker ensures that chained propagation does not turn into endless looping.

      Chained propagation works only when wires have been setup between the cooperative portlets. This feature can be enabled by specifying output parameters for the portlet. When the target receives data from a source, this can in turn cause the transfer of one or more output parameters values.

    • Simple enablement for portlet development

      • For a portlet to be a source of data, programmers can use a custom JSP tag library to flag sharable data on their output pages. The tags require a data type to be specified as well as a specific value corresponding to an instance of this type.

      • For a portlet to be a target, programmers describe a subset of their portlet actions, including type information for the action parameters. For JSR 168 compliant and IBM portlets, WSDL with some custom extensions is a supported format for declaring actions and their associated parameters. For IBM portlets only, this can also be achieved programmatically.

        For JSR 168 compliant portlets, WSDL is the only way to provide information on portlet actions.

    • Broadcast source data to all matching actions on the page

      Users can create wires from a single source property to multiple source portlets on a page. For IBM portlets only, end users of the Click-to-Action function can specify the target of the action or broadcast the action to all portlets on the page. This feature is available in the source portlet when the broadcast attribute is specified for the <c2a:encodeProperty/> tag.

  • IBM portlets only:

    • User-friendly interface

      Cooperative portlets provide an easy, menu-driven method to enable the sharing of compatible data between portlets.

    • Scatter multiple related sources to targets on the page with a single click

      The Click-to-Action menu can allow users to send multiple property values with a single click. For example, the Order Summary portlet in the Order Shipping Example has a "Send to all" pop-up menu item, which allows the user to transfer the properties in the selected row (the order ID and customer ID) to all actions on the page which can consume any of the properties. As a result, all portlets on the page display information about the same order - the scatter feature, combined with the chained data transfer feature, has resulted in the synchronization of all the information on the page through a single user click.

    • Advanced programming features

      The setProperties() method in the PropertyListener interface can be used in place of the actionPerformed() method in the ActionListener interface for other programming needs. This allows changes to any property which the portlet is interested in to be received through a single, generic method, instead of requiring multiple actions to be declared. For example, you can process the property and save it in a bean without performing any action. You can also attach the Click-to-Action menu to custom markup elements using the getActionTriggerMarkup() method.

 

Property broker runtime components

The property broker runtime comprises of a generic wrapper portlet, which is used to wrap each portlet enabled for cooperation, as well as a broker component. The wrapper portlet is only used for IBM portlets, and not for JSR 168 compliant portlets. These components also interface with the WebSphere Portal core runtime.

The purpose of the wrapper is to intercept calls to the application portlet and interface with the broker appropriately, to transparently register actions supported by the portlet, and to initiate data transfer from source to target portlets using the property broker. The wrapper is packaged in each cooperative portlet's WAR file.

In the case of JSR 168 compliant portlets, the function of the wrapper is provided through a portlet filter which is part of the runtime component and not the WAR file. The broker centrally maintains a repository of actions and properties on each portlet, performs source and target matches at runtime using this information, and generates additional markup to allow users to trigger data transfers across portlets.

 

Event handling

The portlet programming model involves an event phase and a render phase in each request-response cycle

The event phase is when the property broker delivers notifications to cooperative portlets and when the cooperative portlets can notify the property broker of property value changes. During the event phase, an action may be delivered on one portlet as the result of a user clicking on an action link generated by the portlet in its markup. If cooperative portlets are used, this may result in other actions being triggered on other portlets. The event phase is followed by the render phase, in which each portlet is asked to return markup, which is then aggregated in a single page. The markup may embed action links which can be used to invoke actions. The page is then returned to the client (such as a browser).

At any point during the event phase, a portlet may publish the value of an output property to the property broker. The portlet may provide a value at any time during the event phase. The property broker determines what needs to be done with the values. If wires exist for this property, the property broker will deliver the property value to the actions specified by the target end of the wires.

Note that the process may continue recursively; the property broker detects loops and breaks them.

The property broker guarantees the completion of all property value notifications to target portlets by the end of the event phase. The event phase is followed by the render phase, during which the portlet runtime renders the markup that each portlet produces.

 

Sample flow of cooperative portlet interaction

The request-response flows involving cooperative portlets for both JSR 168 and IBM portlets are listed below. The IBM sample illustrates the use of Click-to-Action. For JSR 168 compliant portlets, the WSDL file is now processed at deployment time.

JSR 168 compliant

This example assumes that wires already exist between the source and target portlets.

  1. The portlets are deployed. The WSDL file is processed and actions and properties are registered with the portal runtime.

  2. During the render phase of a request cycle, the portlet container requests markup from portlets. The resulting page is returned to the browser.

  3. The user initiates an action, for example clicking on a submit form button.

  4. In the action phase, the portlet container receives the request and calls the source portlet's processAction(), which may generate output property values.

  5. The property broker transfers the property values to any wired targets by invoking the target actions associated with the wires.

  6. The target portlet processes these property values. Steps 4-6 may repeat.

  7. All action processing for all portlets on the page completes. Render processing begins.

  8. After all render callbacks are completed, the portal assembles the response page and returns it to the client.

IBM portlets only

This example uses Click-to-Action as an illustration, but it is similar to the series of events in the programmatic or wired interaction scenarios.

Click-to-Action flow

  1. During portlet deployment, the WSDL file associated with the application portlet is processed and actions and properties are registered with the portal runtime.

  2. During the render phase of a request cycle, the portlet container requests markup from each portlet. This may result in JSPs associated with the portlets being processed. Any Click-to-Action tags in the JSPs result in calls to the property broker, which determines matching actions on the page based on type information, and generates additional markup to display the icon used to invoke the pop-up menu.

  3. After all render phase portlet callbacks have been completed, the portal assembles the response page and returns it to the client.

  4. The end-user may click on the icon for a source to view a menu of compatible actions on the page and select one.

  5. A new request containing the chosen source and action information is generated and sent to the portal.

  6. The portal core runtime delivers the action to the target portlet. This is intercepted by the wrapper, which may interact with the broker to further process the request before delivering the action to the target.

  7. Wires may be triggered as in the previous flow.

 

Property transfer using wires

Wires are used to save property transfers between portlets on a page. JSR 168 compliant portlets can only be connected by wires through the Portlet Wiring Tool. IBM portlets can be connected by wires through the Portlet Wiring Tool or using Click-to-Action. If a wire is present when the user clicks on the Click-to-Action icon, no selection menu is shown. Instead the wired action is automatically fired. Wires may also be used to initiate property value transfers in the absence of Click-to-Action icons, simply as a side effect of an action being executed on the source portlet.

If a wired action is associated with output parameters, the property broker checks for values for the properties associated with the parameters once the action has finished executing. If such properties are found, the property broker examines wires with source ends that correspond to the output properties of the action. If such wires are found:

  • If the target end of the wire is an input parameter, the actions on the target are invoked and the property value delivered using the input parameter information.

  • If the target end of the wire is an input property, the property value will be delivered to the portlet's setProperties() method, (using the PropertyListener interface).

 

Property broker programming model

 

Registering properties and actions

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

  • JSR 168 compliant and IBM 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 above. Fewer changes need to be made to portlets to enable them to interact with other cooperative portlets on the page using the declarative approach versus the programmatic approach. Existing portlets 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 on the page 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. For more information on registering properties using WSDL,

 

Generating property values

  • JSR 168 compliant and IBM 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. section

  • IBM portlets only:

    • JSP tags

      JSP tags should be used to implement dynamic displays for the end user. For example, Click-to-Action tags such as <c2a:encodeProperty/> and <c2a:encodeProperties/> can be used to create Click-to-Action menus.

      Source portlets use 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 pop-up 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 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...

      was_root/installedApps/hostname/wps.ear/wps.war/themes/html/

    • Programmatic

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

 

Receiving property values

  • JSR 168 compliant and IBM 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 JSR 168 compliant 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:

  • JSR 168 compliant and IBM 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. 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.

  • JSR 168 compliant

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

  • IBM portlets only

    • com.ibm.wps.pb.property

    • com.ibm.wps.pb.portlet

    • com.ibm.wps.pb.service

 

See also

Home |

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.