How cooperative portlets work

Cooperative portlets are portlets that can communicate with each other by sending messages. They work in any of three ways:

• A portlet can be a cooperative source, meaning that it can send data to other portlets.

• It can be a cooperative target, meaning that it can receive data from other portlets.

• A portlet can also be a cooperative source and a target at the same time. Rational Application Developer Version 7 provides a set of tools to define your source and target portlets and to pass data between them.

IBM® WebSphere® Portal facilitates communication between portlets through two mechanisms: the property broker and Click-to-Action. The property broker mechanism may be used by Java™ Specification Request (JSR) 168 and IBM API portlets. Click-to-Action is currently available only to IBM API portlets. This article focuses on the property broker mechanism.

The property broker is a service provided by WebSphere Portal, which acts as a central hub to receive data from source portlets and to pass it on to target portlets, according to a set of defined wires. Each wire is a 1-to-1 mapping between a source action and a target action. When a portlet is enabled for cooperation, a WSDL file (Web Services Description Language) is created that defines the type of data that it can share, how that data will be shared, and the action that will trigger the property transfer to take place.

There are three mains steps involved in creating a cooperative portlet application:

1. Define the data transfer as either incoming (for target) or outgoing (for source).

2. Implement the action processing to make the data available to the property broker if it is a cooperative source or, if it is a cooperative target, to get data passed in by the property broker.

3. Deploy it to the server and wire the portlets together by using the wiring tool.

The exercise that follows takes you through each of these steps and produces a working cooperative application that you can deploy to a WebSphere Portal server.

Cooperative portlet tools in Rational Application Developer

Before getting into the example, let's take a quick look at the cooperative tools for JSR 168 portlets available in Rational Application Developer V7.

The Cooperative Source wizard

Purpose: Use this wizard (Figure 1) to enable a portlet as a cooperative source. After clicking Finish, a WSDL file is created that defines the type of data to share, how to share it, and what action will trigger the property transfer. You can run this wizard multiple times on a single portlet to define additional properties to transfer.

To access this wizard:

1. Expand the Portlet Deployment Descriptor node in the Project Explorer and right-click on a portlet.
2. Select Cooperative > Enable this Portlet to Send Data (Source).

Files that it creates or updates:

• WebContent/wsdl/[portletName].wsdl: This file defines the type of data to share, how to share it, and what action will trigger the property transfer.
• WebContent/WEB-INF/portlet.xml: The wizard updates this file to contain a portlet preference referencing the WSDL file.
• The properties file: Two optional caption values are added to the portlet's properties file.

The Cooperative Target wizard

Purpose: Use this wizard (Figure 2) to enable a portlet as a cooperative target. After clicking Finish, a WSDL file is created that defines the type of data to receive, how to retrieve it from the property broker, and what action to perform when it has been received.

To access this wizard:

1. Expand the Portlet Deployment Descriptor node in the Project Explorer and right-click on a portlet.
2. Select Cooperative > Enable this Portlet to Receive Data (Target).

Files that it creates or updates:

• WebContent/wsdl/[portletName].wsdl: This file defines the type of data to receive, how to retrieve it, and what action to perform after it has been received.
• WebContent/WEB-INF/portlet.xml: The wizard updates this file to contain a portlet preference that references the WSDL file. When enabling a JavaServer™ Faces (JSF) portlet, two initialization parameters (init params) that reference the name of the input property and the name of the target action are also added.
• The properties file: Two optional caption values are added to the portlet's properties file.

The Cooperative Source Trigger

Purpose: Use this wizard (Figure 3) to implement the action processing step for JavaServer Faces or Basic cooperative source portlets. It inserts the necessary input elements into JavaServer Pages™ (JSPs) to trigger a property transfer and generates action processing code to make the data available to the property broker. You may need to modify the generated code to meet the exact needs of your application.

To access this tool:

1. Open the Portlet drawer in the Palette view.
2. Drag the Cooperative Source Trigger item onto the JSP page.

Files that it updates:

• The JSP: Appropriate UI data will be added to the JavaServer Pages file. Either a link or a button is added. When clicked, it triggers the property transfer.
• The page code file (JavaServer Faces, or JSF, only): An action method is created in the page code that makes the shared data available to the property broker.
• The portlet class (Basic only): The wizard updates the processAction() method to make the shared data available to the property broker.

The Project Explorer

Purpose: Cooperative actions and data types are displayed in the Project Explorer (Figure 4) as children of the portlet, so that you can get a high-level view of what source and target portlets have been enabled. This view also provides access to cooperative editing wizards and deletion dialogs.

To access this information:

1. Expand the Portlet Deployment Descriptor node in the Project Explorer.
2. Expand the portlet nodes.

The Edit Data Type wizard

Purpose: This wizard (Figure 5) functions in the same way as the wizard used to enable source or target portlets. When you select a data type to edit from the Project Explorer, its values will be pre-populated into this wizard. Any changes that you make will edit the existing values in the WSDL file rather than creating a new entry.

To access this wizard:

1. Expand the Portlet Deployment Descriptor node in the Project Explorer, and then expand the portlet that contains the data type that you want to edit.
2. Expand the action that the data type is associated with, and right-click on it.
3. Select Edit Data Type.

Files that it updates:

• WebContent/wsdl/[portletName].wsdl: Updates the existing values in the WSDL file
• WebContent/WEB-INF/portlet.xml: When editing a Faces portlet, the two init params that reference the name of the input property and the name of the target action will be updated, if necessary.

The Delete Action and Delete Data Type dialogs

Purpose: These dialogs enable you to automatically remove an action or data type from the WSDL file. (See Figure 6 and Figure 7.)

To access these tools:

1. Right-click on a cooperative action or data type node in the Project Explorer.
2. Select Delete.

Files that these tools update:

• WebContent/wsdl/[portletName].wsdl: Removes the action or data type from the WSDL file.
• WebContent/WEB-INF/portlet.xml: When editing a Faces portlet two init-params referencing the name of the input property and the name of the target action may be deleted as needed.

The Disable Cooperative action dialog

Purpose: This dialog (Figure 8) can remove all cooperative related artifacts associated with a portlet and return it to a non-cooperative portlet state.

To access this tool:

1. Right-click on the portlet node in Project Explorer.
2. Select Disable Cooperative.

Files that it removes or updates:

• WebContent/wsdl/[portletName].wsdl: Deletes this file.
• WebContent/WEB-INF/portlet.xml: Removes references to the WSDL file and any init params created.

Let's begin the tutorial.

Step 1. Define the data transfer type

Now you'll create a simple JSR 168 Faces portlet application that has a single-source portlet and a single-target portlet. In your source code, you will allow the user to enter a name and display the value in the target portlet.

Create a portlet project

Begin by creating a new JSR 168 Faces Portlet project:

1. In Rational Application Developer V7 select File > New > Project.
2. Select Portlet Project and click Next. (If asked to enable Portal Development, click OK.)
3. Enter JSRFacesCooperative as the Project name.
4. Make sure that WebSphere Portal V6.0 is selected as the Target Runtime and that the Add project to an EAR check box is selected.
5. Make sure that the Portlet API is set to JSR 168 Portlet and Portlet type is set to Faces Portlet.
6. Enter JSRFacesCooperativeSource as the Portlet name.
7. Click Next, and then Finish. (Switch to the Web Perspective if prompted.)

Now, add a second portlet to our project to be the target.

8. Right-click on the project called JSRFacesCooperative and select New > Portlet.
9. In the New Portlet wizard, set the name of the portlet as JSRFacesCooperativeTarget.
10. Click Next, and then click Finish.

Enable the portlet to share data

Now you will enable the source portlet to share data by using the Cooperative Source wizard.

1. Expand the Portlet Deployment Descriptor node in the Project Explorer (Figure 9).
2. Right-click on the JSRFacesCooperativeSource portlet, and select Cooperative > Enable this Portlet to Send Data (Source).

On the first page of the wizard (Figure 10), you define the type of data that you are sharing.

Note:
You must specify a URL and a Java type (screen shows URI, rather than URL). Two portlets can be wired together to share data only if they define the same Data Type URL.

3. Change the Data Type URL to http://jsrfacescooperative#name.
4. You are sharing only simple string data in this example, so you can leave java.lang.String as the Java™ type. It is possible to put a more complex object here, such as a Java bean, however.

5. Click Next.

Step 2. Implement the action processing

On the second page of the wizard (Figure 11), you define the source action that triggers the property transfer. In JSR 168 portlets, a property transfer is triggered when a parameter with the name and value that you specify here is present in the action request.

1. Leave the Action Parameter as it is, but change the Action Value to SendName.

Also on this page, you specify the name and location of a variable that will contain the data being sent from the source portlet. When the source action that you just specified takes place, the property broker looks at this location to retrieve the output property, so that it can then send it on to the target portlet.

2. Use Request attribute as the Location.

Tip:
If you pull down the combination (combo) box, you'll see that you can store the output property in several different scopes, such as parameter or session scope.

3. Change Property Name to outputName.

4. Click Next.

Enter caption names (optional)

The next page of the wizard (Figure 12) is for entering optional caption values. Captions are used in the wiring tool as simple names to refer to the property and action names. These values will not be shown to a user of the portlet application.

1. Use the default setting for the Resource Bundle field.
2. Leave the Property and Action captions as they are, and click Next.

The final page of the wizard (Figure 13) shows you the next steps for setting up a cooperative application. You can save this file for future reference.

3. Now, click Finish.

You have now enabled the first portlet to be your source. Open the WebContent/wsdl/JSRFacesCooperativeSource.wsdl file, and you'll find it populated with the various items that you entered in the wizard. Also note that, in the Project Explorer, your portlet icon has changed, and you can now expand it to see the action and data type that you just defined.

Insert UI controls that trigger a property transfer

Now you'll use the Cooperative Source Trigger to add a user interface (UI) to your JSP file, create the action, and make the data available to the property broker.

1. Open up the source portlet JSP file, JSRFacesCooperativeSourceView.jsp, and change the Place content here text to Enter Name: (including the colon).
2. Drag a JSF Input component from the Palette onto the JSP page, and drop it after the Enter Name: text.
3. Right-click in Page Data View and create a new Param Scope variable. Call it nameParam.
4. Bind the new Param Scope variable to the input component by dragging the parameter onto the component onto the JSP.
5. Go to the Palette and open up the Portlet drawer.
6. Select the Cooperative Source Trigger and drop it on the JSP next to the Input component.
7. When the Insert Cooperative Source Trigger wizard appears (Figure 14), select JSRFacesCooperativeSource as the Source portlet.
8. Pull down the Action Value combo box and select the action that you defined in the Cooperative Source wizard.
9. Pull down the Property Name combo box, and select the property name that you defined in the Cooperative Source wizard.
10. Select the Browse button next to the Value to Send field, expand the parameter node, and select the nameParam parameter that you just created.
11. Click OK.

12. Leave the UI type as Link, and click Finish.
13. A link should appear on the JavaServer Page, or JSP (Figure 15). Change the text to Send Name, if you wish.

The source portlet is now ready to share data. If you switch to the source view of the Page Designer, you'll see that you created a command link that contains a single parameter. The parameter holds the Action Parameter (ACTION_NAME_PARAM) and Action Value (SendName) that you specified in the wizard. When a user clicks that link, those values are put into an action request, thereby triggering the property transfer.

14. Now, right-click on the Source page and select Edit Page Code.
15. Scroll down until you find the method doCooperativeLinkAction(). Here, you place the data to send into the request scope with the Property Name (outputName) that you specified in the Cooperative Source wizard.

Enable the target portlet to receive data

Next, you will enable the target portlet to receive data by using the Cooperative Target wizard.

1. Expand the Portlet Deployment Descriptor node in the Project Explorer (Figure 16).
2. Right-click on the JSRFacesCooperativeTarget portlet and select Cooperative > Enable this Portlet to Receive Data (Target).
3. Pull down the Data Type URI (URL) combo box, and select the same data type that you defined in the source portlet.

Important:
These values must match for a property transfer between two portlets.

4. Leave the Java type as it is, and click Next.

5. Next to Action Value (Figure 17), click Browse, select JSRFacesCooperativeTargetView.jsp from the dialog, and then click OK.
6. Leave Location as Request Param and change Property Name to inputName.

Note:
When the property broker has data available for a target portlet, it calls the target action and makes the data available in a parameter given by the Property Name, and then places it in the location specified. It is then the portlet's responsibility to retrieve the data to use during the action processing phase.

7. Click Next.
8. Change the Action caption to something easier to read, such as Name Target Action. This helps you understand which actions you are working in the wiring tool later.
9. Click Finish.

Now, create some UI data on the target JSP to display the incoming data.

10. Open the target JSP, JSRFacesCooperativeTargetView.jsp.
11. Change the Place content here text to Display Name: (include the colon).
12. Drop a JSF Output component from the palette onto the JSP.
13. Create a Param scope variable (the location of the property according to the settings in the cooperative target wizard) in Page Data View named inputName (the name of the property according to the settings in the cooperative target wizard), and then bind it to the Output component.

Back to top

Step 3. Deploy your project to the portal server

You are now ready to deploy your project onto the WebSphere Portal server.

1. Right-click your project, JSRFacesCooperative, and select Run As… > Run on Server.
2. Fill in the necessary information, and click Finish.
3. For details of testing on WebSphere Portal 6.0, check Help in Rational Application Developer V7.

When the portlet page loads in the Web browser, you should see what Figure 18 shows.

Before you can start transferring data, you must wire these portlets together.

4. Click the name of your page in the left column, and select Edit Page Layout (Figure 19).

5. Then select the Wires tab along the top of the page to launch the wiring tool (Figure 20).

6. Use the combo boxes to make your way across the page, filling in the available values.
7. When you are finished, click the + (plus sign) button, and then select Done. This will take you back to your portlets.
8. Now, enter text in the Enter Name field (Figure 21), and then click the link.

You will see that the text that you entered in the source portlet is now displayed in the target portlet.

How to use a command button rather than a link

The application described here uses a command link to trigger the property transfer, but it is also possible to use a command button. The major difference between the two is the way the action parameter and value are passed into the action request.

Let's look at the JSP source code that uses a command link and compare it to the source code that uses a command button. Notice that for a command link, a parameter (<f:param>) is nested as a child element (Listing 1). When the command link is clicked, the JavaServer Faces framework places that parameter in the action request as a request parameter.

                
<h:form id="form1" styleClass="form">
	Enter Name: <h:inputText id="text1" styleClass="inputText"
	value="#{param.nameParam}"></h:inputText>

	<h:commandLink id="link1" styleClass="commandLink"
action="#{pc_JSRFacesCooperativeSourceView.doCooperativeLinkAction}">

	<f:param id="parameter1" name="ACTION_NAME_PARAM" value="SendName"></f:param>
	<h:outputText id="text2" styleClass="outputText" value="Send Name"></h:outputText>

	</h:commandLink>
</h:form>

Now, look at the similar code that uses a command button, instead (Listing 2). The main difference is that the action parameter is passed by using an HTML hidden field element rather than in a Faces parameter. This is because the JavaServer Faces framework does not add Faces parameters (<f:param>) to the action request when they are child elements of a command button.

                
<h:form id="form1" styleClass="form">		
	Enter Name: <h:inputText id="text1" styleClass="inputText"
	value="#{param.nameParam}"></h:inputText>
		
<INPUT type="hidden" name="ACTION_NAME_PARAM" value="SendName"> 
	<hx:commandExButton type="submit" value="Submit" id="button1"
styleClass="commandExButton" action="#{pc_JSRFacesCooperativeSourceView.doButton1Action}">
	</hx:commandExButton>
		
</h:form>

Other than this one change, command links and command buttons perform in exactly the same way.

How JSR 168 Basic and Struts portlets differ from Faces portlets

The primary difference between Faces, Basic, and Struts cooperative applications is the means by which their actions are processed and that data is passed to the property broker. In all three portlet types, a property transfer is triggered when a request parameter is presented to the action request with the name and value given in the Cooperative Source wizard.

• The name and value can be any string except in the case of JSR 168 Struts portlets, where the parameter name must be spf_strutsAction. This is a default parameter name for all Struts action and cannot be changed. Struts portlets use a Struts action to trigger the property transfer. When a Struts action takes place, its action class passes data to the property broker.
• Faces portlets typically pass the action name and value into the action request using a parameter in the JSP. They will then use a Faces action to pass the data to the property broker. You saw this in the example that you worked through here.
• Basic portlets also pass the action name and value into the action request from the JSP. They will generally do this using a parameter (<portlet:param>, an action URL (<portlet:actionURL>), or a hidden field in a form. The data will then be passed to the property broker using the processAction()method of the portlet class.

You can see examples of these steps in the Cooperative Source or Cooperative Target wizards by clicking Next until you reach the Next Steps page. There, you will see the steps required to trigger the action in the JSP and how to pass the data to the property broker.

Resources

Learn

• "What's new in IBM Rational Application Developer V7.0" This IBM developerWorks® article (December 2006) provides an overview of the new features of IBM Rational Application Developer V7.0, which is one of the premier tools for developing software solutions and applications.
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  
• Subscribe to the developerWorks Rational zone newsletter. Keep up with developerWorks Rational content. Every other week, you'll receive updates on the latest technical resources and best practices for the Rational Software Delivery Platform.
  
  
• Subscribe to The Rational Edge e-zine for articles on the concepts behind effective software development.
  
  
• Stay current with developerWorks technical events and Webcasts.
  
  

Get products and technologies

• Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  
• Download a free trial version of Rational Application Developer.
  
  

Discuss

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  
• Rational Software Architect, Data Architect, Software Modeler, Application Developer and Web Developer forum: Ask questions about Rational Application Developer.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• How cooperative portlets work
• Cooperative portlet tools in Rational Application Developer
• Step 1. Define the data transfer type
• Step 2. Implement the action processing
• Step 3. Deploy your project to the portal server
• How JSR 168 Basic and Struts portlets differ from Faces portlets
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Rational Application Developer for WebSphere Software
• Demo: Build, test and deploy JAX-WS Web services
• Webcast: Webcast: Develop innovative applications efficiently using the right application foundation in today's economy
• Briefing: Software development conference
• Buy: Rational Application Developer for WebSphere Software

My developerWorks community

Dig deeper into Rational on developerWorks

Try Rational System Architect

See how this fully integrated collection of models and documents can help you better align your IT systems and infrastructure to simplify business processes

Special offers