Tooling support for events and public render parameters for portal and portlet applications

最新推荐文章于 2024-07-10 17:13:50 发布

alexsuncam

最新推荐文章于 2024-07-10 17:13:50 发布

阅读量637

点赞数

文章标签： portlet events parameters deployment descriptor application

Key concepts

The key concepts of this article are explained first, and then these concepts are illustrated by using a sample portlet application.

Events

Version 2 of the Java™ Specification Request (JSR) 286 specification makes it possible for portlets to send and receive events. Events permit the portlets to communicate with each other. IBM® Rational® Application Developer Version 7.5 provides a set of tools to define events, enable the portlets, and pass data between them by using events. A portlet can handle both ends of communication:

Send events to other portlets
Receive and process events from other portlets

Attributes of events

Each event must have a name and, possibly, other attributes:

Name: A unique name for the event. The event name can be a full QName, a qualified name as defined in the XML specification, consisting of a namespace (for example, http://www.ibm.com) and a local part (for example, sampleEvent). Alternatively, you can use the same namespace for many events by declaring it as the default namespace and then specifying only the local part for each event.

Description: (Optional) A description of the event.
Value type: (Optional) A fully qualified Java class name of the value to be transferred with the event.
Alias: (Optional) A namespace-qualified name for the event.

To create a portlet application that incorporates events and public render parameters for communication between portlets, complete these tasks:

Create a JSR 286 portlet project and portlets.
Create an event definition in the portlet deployment descriptor (PDD).
Add the event as a supported publishing or a processing event by the portlet.
Modify the process action or event code in the portlet class to publish or process the event.
Add the public render parameters.
Publish the portlet project to the server.
Wire the portlets together.

These tasks are greatly simplified by using the tools provided by Rational Application Developer V7.5.

Public render parameters

The JSR 286 specification provides another mechanism that enables coordination between portlets: public render parameters (see Resources for where to find out more about them). These parameters provide a way to share request parameters across portlets.

Attributes of public render parameters

Each parameter must have a name and possibly other attributes:

Name: (Required) A unique name for the parameter, either a string or namespace-qualified name. Select the default namespace or specify a different one. The localized string that you entered as the event name is appended to the namespace.
Identifier: (Required) A string used in the portlet code to refer to the render parameter.
Description: (Optional) A description of the render parameter.
Alias: (Optional) A namespace-qualified name for the parameter.

Sample application used in this article

In this article, a sample portlet application demonstrates the usefulness of the events and public render parameter features of JSR 286. The sample application is used by a shipping company to maintain the details of its orders and customers. It consists of three portlets:

The Orders portlet maintains the monthly details of the orders of the company.
The OrderDetails portlet shows the details of one order.
The TrackingDetails portlet shows the tracking details of one order.

The article demonstrates how to create events and public render parameters and use them in the sample. See Download to get the complete sample.

The use case for the sample

A user can select an order ID of a month to view its order and tracking details. This is implemented by using events and public render parameters. The Orders portlet summarizes information for all of the orders over a month. When the user clicks the ID for an order in the Orders portlet, the portlet triggers an event. This event is processed by the OrderDetails portlet that shows the order details for the selected order ID. The OrderDetails portlet then fetches the tracking ID of the order from the order details, and passes the details to the TrackingDetails portlet as a render parameter. The TrackingDetails portlet then shows the tracking details of that order.

To make this use case work, use the Portal Toolkit in Rational Application Developer 7.5 to first declare an event called OrderIDType . This event is added as a supported publishing event for the Orders portlet and as a supported processing event for the OrderDetails portlet.
You then create the TrackingIDType public render parameter and make the OrderDetails and TrackingDetails portlets support the parameter.

Create the JSR 286 portlet project and portlets

The Portlet Project wizard in Rational Application Developer supports the creation of JSR 286-compliant portlet projects.

To create the portlet project:

Click File > New > Portlet Project to open the wizard.
Specify the details, as shown in Figure 1:
1. For the target runtime environment, select WebSphere Portal v6.1 .
2. For the portlet API, select JSR 286 Portlet .
3. For the portlet type, select Basic Portlet .

Figure 1. JSR 286 portlet project creation wizard
New Portlet Project view

The next step is to add the required portlets to the portlet application that you created. Given that the article covers three portlets in the sample application, you can add these portlets to the portlet project (see Figure 2):

Right-click the portlet deployment descriptor and select New > Portlet .
Enter the portlet name as OrderDetail , and click Finish .
Repeat these steps to add the other two portlets: OrdersPortlet and TrackingPortlet.

Figure 2. Portlet creation wizard
Portlet wizard using the JSR 286 specification

Note:
This article does not discuss how to modify the Java™Server Pages (JSP™) files and add the function that you want to the portlets, because the focus is on creating events and public render parameters. The assumption is that the portlets have been modified, with the Orders portlet showing the orders for the month, the OrderDetail portlet showing the order details, and the Tracking portlet showing the tracking details of the order.

Figure 3 shows how the OrdersPortlet will look when it is published on WebSphere Application Server V6.1.

Figure 3. Orders Portlet
Orders for September

Create an event definition in the portlet deployment descriptor

It is easy to create events with the event wizard included in Rational Application Developer. To create the three events:

Expand the portlet project in the Project Explorer.
Right-click the portlet deployment descriptor and select Event .

As Figure 4 shows, two options are available under Event:

Enable this Portlet to Publish Event
Enable this Portlet to Process Event

Figure 4. Events options
Drop-down menu options selected

Click to enlarge

Add the event as a portlet publishing event

These actions are performed when you select the first option, which is "Enable this Portlet to Publish Event:"

Add the event definition to the portlet application
Add the event as a supported publishing event for the portlet
Modify either the processAction() or processEvent() methods to publish the event

These options are performed when you select the other option, "Enable this Portlet to Process Event:"

Add the event definition to the portlet application, if this event definition does not yet exist
Add the event as a supported processing event to the portlet
Modify the processEvent() methods to process the event

The next step is to create the event by using the wizard. To enable the Orders portlet to publish the OrderIDType event:

Right-click the Orders portlet under the portlet deployment descriptor.
Select Event > Enable this Portlet to Publish events . This action opens the wizard.
Specify the details, as in Figure 5:
1. For the Event name, select OrderIDType .
2. For the Value type, specify String .

Figure 5. Wizard to enable a portlet to publish events
'Describe the event being published' page

Click Finish .

This wizard makes two changes to the portlet deployment descriptor:

Adds the event definition to the portlet application
Adds the event as a supported published event for the portlet

The code in bold in Listing 1 shows how the portlet deployment descriptor code is modified by the event wizard.

Listing 1. Deployment descriptor code modifications

<?xml version="1.0" encoding="UTF-8"?>

<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" 

version="2.0" 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd 

http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" 

id="com.ibm.jsr286eventrenderparam.JSR286EventRenderParamPortlet.19a07d46c1">

	<portlet>

		<portlet-name>OrderDetail</portlet-name>

	<?xml version="1.0" encoding="UTF-8"?>

<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" 

version="2.0" 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 

xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd 

http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" 

id="com.ibm.jsr286eventrenderparam.JSR286EventRenderParamPortlet.19a07d46c1">

	<portlet>

		<portlet-name>OrderDetail</portlet-name>

		<display-name xml:lang="en">OrderDetail</display-name>

		<display-name>OrderDetail</display-name>

		<portlet-class>

		com.ibm.jsr286eventrenderparam.OrderDetailPortlet

		</portlet-class>

		<init-param>

			<name>wps.markup</name>

			<value>html</value>

		</init-param>

		<expiration-cache>0</expiration-cache>

		<supports>

			<mime-type>text/html</mime-type>

			<portlet-mode>view</portlet-mode>

		</supports>

		<supported-locale>en</supported-locale>

		<resource-bundle>

		com.ibm.jsr286eventrenderparam.nl.OrderDetailPortletResoure

		</resource-bundle>

		<portlet-info>

			<title>OrderDetail</title>

			<short-title>OrderDetail</short-title>

			<keywords>OrderDetail</keywords>

		</portlet-info>

	</portlet>

	<portlet>

		<portlet-name>OrdersPortlet</portlet-name>

		<display-name xml:lang="en">OrdersPortlet</display-name>

		<display-name>OrdersPortlet</display-name>

		<portlet-class>

		com.ibm.jsr286eventrenderparam.OrdersPortlet

		</portlet-class>

		<init-param>

			<name>wps.markup</name>

			<value>html</value>

		</init-param>

		<expiration-cache>0</expiration-cache>

		<supports>

			<mime-type>text/html</mime-type>

			<portlet-mode>view</portlet-mode>

		</supports>

		<supported-locale>en</supported-locale>

		<resource-bundle>

		com.ibm.jsr286eventrenderparam.nl.OrdersPortletResource

		</resource-bundle>

		<portlet-info>

			<title>OrdersPortlet</title>

			<short-title>OrdersPortlet</short-title>

			<keywords>OrdersPortlet</keywords>

		</portlet-info>

		<supported-publishing-event>


			<name>OrderIDType</name>

		</supported-publishing-event>


	</portlet>

	<portlet>

		<portlet-name>TrackingPortlet</portlet-name>

		<display-name xml:lang="en">TrackingPortlet</display-name>

		<display-name>TrackingPortlet</display-name>

		<portlet-class>

		com.ibm.jsr286eventrenderparam.TrackingPortlet

		</portlet-class>

		<init-param>

			<name>wps.markup</name>

			<value>html</value>

		</init-param>

		<expiration-cache>0</expiration-cache>

		<supports>

			<mime-type>text/html</mime-type>

			<portlet-mode>view</portlet-mode>

		</supports>

		<supported-locale>en</supported-locale>

		<resource-bundle>

		com.ibm.jsr286eventrenderparam.nl.TrackingPortletResource

		</resource-bundle>

		<portlet-info>

			<title>TrackingPortlet</title>

			<short-title>TrackingPortlet</short-title>

			<keywords>TrackingPortlet</keywords>

		</portlet-info>

	</portlet>

	<default-namespace>http://JSR286EventRenderParam/</default-namespace>

	<event-definition>

		<name>OrderIDType</name>

		<value-type>java.lang.String</value-type>

	</event-definition>

</portlet-app>

Modify the process action code in the portlet class to publish the event

The processAction() method is then modified to publish the event, as Listing 2 shows.

Listing 2. Modifications to the processAction( ) event

public void processAction
(ActionRequest request, ActionResponse response) 

throws PortletException, java.io.IOException {

	if( request.getParameter(FORM_SUBMIT) != null ) {

		// Set form text in the session bean

		OrdersPortletSessionBean sessionBean = getSessionBean(request);

		if( sessionBean != null )

			sessionBean.setFormText(request.getParameter(FORM_TEXT));

	}

//Initialize the fields in the class as per your requirement


	java.lang.String sampleObject = new java.lang.String();

	response.setEvent("OrderIDType", sampleObject);



}

You must customize the code that is generated by the event wizard to fit your requirement. Because the OrderIDType needs to be sent, the order ID comes from the action request parameter when the order ID is selected (see Listing 3).

Listing 3. Code to send the OrderIDType

String order_id = request.getParameter(ORDER_ID);

	if (order_id!=null)

 response.setEvent("OrderIDType", order_id);

The wizard modifies the portlet under the portlet deployment descriptor, as shown in the Project Explorer in Figure 6. Under the OrdersPortlet node, the OrderIDType event appears.

Figure 6. Project Explorer
Enterprise Explorer tab view

Add the event as a processing event supported by the portlet

Next, the order ID needs to be received by the OrderDetail portlet. In other words, the event that was published now needs to be processed by the OrderDetail portlet.

To enable the portlet to process the event:

Expand the Portlet Deployment Descriptor node.
Right-click the OrderDetail portlet and select Event > Enable this Portlet to Process Event .

Figure 7. The process events option
Drop-down menus show selections described

Click to enlarge

The "Enable this portlet to process events" wizard opens, as shown in Figure 8.

Figure 8. Enable this Portlet to Process events window
OrderIDType entered in Event Name field

For the Event Name, select OrderIDType , which has already been declared using the event publishing wizard. You cannot modify the event definition here, but you can edit it manually in the portlet deployment descriptor.
Click Finish to complete this processing:
- Add the supported-processing-event element for the OrderDetail Portlet (you already added the event definition when you published this event)
- Modify the processEvent() method to process the event

The portlet section for the OrderDetail portlet is modified as Listing 4 shows.

Listing 4. Modifications to the OrderDetail portlet

<portlet>

	<portlet-name>OrderDetail</portlet-name>

	<display-name xml:lang="en">OrderDetail</display-name>

	<display-name>OrderDetail</display-name>

	<portlet-class>

	com.ibm.jsr286eventrenderparam.OrderDetailPortlet

	</portlet-class>

	<init-param>

		<name>wps.markup</name>

		<value>html</value>

	</init-param>

	<expiration-cache>0</expiration-cache>

	<supports>

		<mime-type>text/html</mime-type>

		<portlet-mode>view</portlet-mode>

	</supports>

	<supported-locale>en</supported-locale>

	<resource-bundle>

	com.ibm.jsr286eventrenderparam.nl.OrderDetailPortletResoure

	</resource-bundle>

	<portlet-info>

		<title>OrderDetail</title>

		<short-title>OrderDetail</short-title>

		<keywords>OrderDetail</keywords>

	</portlet-info>

	<supported-processing-event>

		<name>OrderIDType</name>

	</supported-processing-event>

</portlet>

Modify the event code in the portlet class to process the event

As Listing 5 shows, changes are also made to the processEvent() method that is responsible for processing the event that is received.

Listing 5. Modifications to the processEvent( ) method

public void processEvent(EventRequest request, EventResponse response) 

throws PortletException, java.io.IOException {

	Event sampleEvent = request.getEvent();

		if(sampleEvent.getName().toString().equals("OrderIDType")) {

			Object sampleProcessObject = sampleEvent.getValue();

		}

You need to send the TrackingID from the OrderDetail portlet to the Tracking portlet. Therefore, you need to modify the processEvent() method, as the code in bold in Listing 6 shows.

Listing 6. Modifications to the processEvent( ) method

public void processEvent(EventRequest request, EventResponse response)

    throws IOException, PortletException {

     Event sampleEvent = request.getEvent();

	if(sampleEvent .getName().equals("OrderIDType")) {	

	 	   Object sampleProcessObject = sampleEvent.getValue();

	         response.setRenderParameter(ORDER_ID, sampleProcessObject.toString());

	         //set the order id as a render parameter

	         OrderDetail od = ShippingDB.getOrderDetail(ev.getValue().toString());

      if (od != null) {

            request.getPortletSession().setAttribute(ORDER_DETAIL, od);

            response.setRenderParameter("TrackingID", od.getTrackingId());

            //fetch the tracking id from the order details, and set it as a 

            render parameter.

            }

	  }

}

For the OrderDetails Portlet to show the Order Details, you need to modify the doView() method to add the code that Listing 7 shows in bold.

Listing 7. Modifications to the doView( ) method

String orderId = (String) request.getParameter(ORDER_ID
);//get the order set 

in the processAction()

  OrderDetail od = ShippingDB.getOrderDetail(orderId);

   PortletURL actionURL = ShippingUtils.createSimpleActionURL(ORDER_DETAILS, response);

    odb.setActionURL(actionURL);

	if (od != null) 

        odb.setOrderDetail(od);

     getPortletContext().getRequestDispatcher(getJspFilePath(request, VIEW_JSP))

     .include(request, response);

Add the public render parameters

The next step is to use the public render parameter mechanism to share the tracking ID between the OrderDetail portlet and the Tracking portlet:

Open the portlet deployment descriptor for the EventSample project.
Select the Render Params tab, and then click Add to create a public render parameter with the default name, NewPublicRenderParam.
Change the Name and Identifier fields to TrackingID , as shown in Figure 9.

Figure 9. Render Params tab in the Portlet Deployment Descriptor editor
Public Render parameters window

Click to enlarge

This action adds the section shown in Listing 8 to the portlet application definition of the portlet deployment descriptor.

Listing 8. Code snippet added to the portlet deployment descriptor

<public-render-parameter>

	<identifier>TrackingID</identifier>

	<name>TrackingID</name>

</public-render-parameter>

Because this parameter needs to be shared by the Tracking and OrderDetail portlets, you need to add it as a supported public render parameter for each of those portlets.
1. From the Portlets tab, select the Tracking portlet.
2. Scroll down to the Supported Public Render Parameters section in the right pane, and click Select .
For the name, select Tracking ID , which was created in the Render Params tab in the editor, as shown in Figure 10.
Click OK .
Repeat Steps 4 and 5 to add TrackingID as a supported public render parameter for the OrdersPortlet.

Figure 10 shows the public render parameter added to the portlets.

Figure 10. Supported public render parameter added
Portlets view

Click to enlarge

The changes shown in bold in Listing 9 are made to the portlet deployment descriptor.

Listing 9. Modifications to the portlet deployment descriptor

<portlet>

		<portlet-name>OrdersPortlet</portlet-name>

		<display-name xml:lang="en">OrdersPortlet</display-name>

		<display-name>OrdersPortlet</display-name>

		<portlet-class>

			com.ibm.jsr286eventrenderparam.OrdersPortlet

		</portlet-class>

		<init-param>

			<name>wps.markup</name>

			<value>html</value>

		</init-param>

		<expiration-cache>0</expiration-cache>

		<supports>

			<mime-type>text/html</mime-type>

			<portlet-mode>view</portlet-mode>

		</supports>

		<supported-locale>en</supported-locale>

		<resource-bundle>

			com.ibm.jsr286eventrenderparam.nl.OrdersPortletResource

		</resource-bundle>

		<portlet-info>

			<title>OrdersPortlet</title>

			<short-title>OrdersPortlet</short-title>

			<keywords>OrdersPortlet</keywords>

		</portlet-info>

		<supported-publishing-event>

			<name>OrderIDType</name>

		</supported-publishing-event>

		<supported-public-render-parameter>

			TrackingID

		</supported-public-render-parameter>

	</portlet>

	<portlet>

		<portlet-name>TrackingPortlet</portlet-name>

		<display-name xml:lang="en">TrackingPortlet</display-name>

		<display-name>TrackingPortlet</display-name>

		<portlet-class>

			com.ibm.jsr286eventrenderparam.TrackingPortlet

		</portlet-class>

		<init-param>

			<name>wps.markup</name>

			<value>html</value>

		</init-param>

		<expiration-cache>0</expiration-cache>

		<supports>

			<mime-type>text/html</mime-type>

			<portlet-mode>view</portlet-mode>

		</supports>

		<supported-locale>en</supported-locale>

		<resource-bundle>

		com.ibm.jsr286eventrenderparam.nl.TrackingPortletResource

		</resource-bundle>

		<portlet-info>

			<title>TrackingPortlet</title>

			<short-title>TrackingPortlet</short-title>

			<keywords>TrackingPortlet</keywords>

		</portlet-info>

		<supported-public-render-parameter>TrackingID

		</supported-public-render-parameter>

	</portlet>

You must modify the doView() method of the Tracking portlet to display the tracking details, based on the TrackingID of the order (see Listing 10).

Listing 10. Modifications for the doView( ) method

String renderParam = request.getParameter("TrackingID");

//fetch the tracking id render param which was set in the OrderDetails Portlet

	TrackingDetailBean tdb = new TrackingDetailBean();

	request.setAttribute(TRACKING_DETAIL_BEAN, tdb);

	if (renderParam!=null && renderParam.length()>0) {

		PortletURL actionURL = 

		ShippingUtils.createSimpleActionURL(TRACKING_DETAILS, response);

            tdb.setActionURL(actionURL);

	PortletURL rdActionURL = 

	ShippingUtils.createSimpleActionURL(ROUTING_DETAILS, response);

             tdb.setRoutingDetailActionURL(rdActionURL);

		TrackingDetail td = ShippingDB.getTrackingDetail(renderParam);

		 if (td != null) {

		tdb.setTrackingDetail(td);

		getPortletContext().getRequestDispatcher(getJspFilePath

		(request, VIEW_JSP)).include(request, response);

		} else {

		  //Tracking id not found; print error page

		 tdb.setErrorMessage("Tracking Id " + renderParam + " not found.");

		 getPortletContext().getRequestDispatcher(getJspFilePath

		(request, ERROR_JSP)).include(request, response);

		        }

		}

Publish the portlet project

Now you can publish the portlet application on WebSphere Application Server V6.1:

Right-click the portlet project (see Figure 11) and select Run As > Run on Server .

Figure 11. Publish the portlet project
Selections made in drop-down menus

Click to enlarge

Select the WebSphere Portal V6.1 Server , as in Figure 12.
Click Next , and then click Finish .

Figure 12. Select the server where you want to run your portlet application
Run on Server window

Wire the portlets together

The wiring tool that is available on the portal server can help you wire the relationships between portlets that share events between them.

To access the wiring tool:

Select Edit Page Layout for the page on which the portlets are placed.
Select the Wires tab.
For the source portlet, select OrdersPortle t from the drop-down menu, and for the target portlet, select the OrderDetail portlet (Figure 13). For the event names, click the drop-down arrow for the Sending and Receiving fields.

Figure 13. Add wires to define the relationships in the portlet application
Portlet Wiring Tool view

Click to enlarge

Click the plus sign and then click Done .
Select an order ID (for example, the first one in the OrdersPortlet).

When you click the order ID, an event is triggered by the Orders portlet, which sends the Order_ID value to the Order Details portlet. When that portlet receives the order ID, the Order Details Portlet processes the event. It fetches the details of the order ID and displays them for the user. In addition, the Order Details portlet retrieves the tracking ID for the order and communicates the ID to the tracking details portlet, because the TrackingID has been added as a shared render parameter for both the Order Details and Tracking portlets. Thus, once the user clicks on an order ID, the order details and the tracking details are shown to the user (see Figure 14).

Figure 14. The Orders portlet
Orders Portlet view

The user can now see the order and tracking details, as Figure 15 shows. Thus, events and public render parameters are used to transfer the OrderID and the TrackingID to the respective portlets.

Figure 15. Order and Tracking detail portlets
TrackingPortlet view

Click to enlarge

As you have seen here, the tools provided by Rational Application Developer 7.5 greatly simplify the creation of events and public render parameters. You need to customize only the code that is generated to fit the requirements of your application.

Download

Description	Name	Size	Download method
How to create events and public render parameters	JSR286EventRenderParam.zip	63KB	HTTP

Information about download methods

Resources

Learn

Learn What's new in the Java Service Specification V2.0 JSR 286) for portlets .
Read What's new in IBM WebSphere Portal V6.1: JSR 286 features to learn how the concepts of the new standards, particularly interportlet communication, have been integrated and get guidelines for choosing between using portlet events or public render parameters for communication.
Find out more about public render parameters , which enable JSR 286 portlets to share navigational state information.
Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
Subscribe to the IBM developerWorks newsletter , a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
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 newsletter for articles on the concepts behind effective software development.
Browse the technology bookstore for books on these and other technical topics.