Understanding the Portlet Container 2.1 Software

This article describes new features available in the Portlet Container 2.1 software. Portlet Container 2.1 is a part of the Java Application Platform SDK Update 7 software.

Note: See the Portlet Container 2.1 Release Notes and Installation Instructions for Java Application Platform SDK Update 7.

• Overview
• Events
• • Sample Application
• Public Render Parameters
• • Sample Application
• Portlet Filters
• • Sample Application
• Resource serving
• • Sample Application
• Portlet Policy
• Conclusion
• References

The article Introducing Java Portlet Specifications: JSR 168 and JSR 286 describes portlets as web-based components that enable integration between applications and portals and thus delivery of applications on portals. The heart of a portal is a portlet container, and as a servlet container is to servlets, so is a portlet container is to portlets. Portlet containers execute portlets and manage their life cycle.

The Java Portlet Specification 2.0, Java Specification Request (JSR) 286 was approved and released recently.

The JSR 286 includes the following new features:

• Events – Enable portlets to communicate with each other by sending and receiving events
• Public render parameters – Enable portlets to specify which render parameters they can share with other portlets
• Portlet filters – Enables dynamic transformation of the content of portlet requests and responses
• Resource serving – Enable portlets to serve resources within the portlet context

The Portlet Container 2.1 software implements the above features of the Java Portlet Specification 2.0. In addition to this, the Portlet Container 2.1 software provides a portlet driver, a lightweight portlet rendering environment. This driver simulates some capabilities of a typical portal product like the Sun Java System Portal Server.

This article describes the new features that are available in Portlet Container 2.1 software along with a sample application to demonstrate how to write portlets with these features. The steps to deploy portlets are the same as in Portlet Container 1.0. To know more about how to deploy portlets, see Understanding the Portlet Container 1.0 Software and Deploying Portlets.

An event is a life cycle operation that occurs before the rendering phase. Events can be described as a loosely coupled, brokered means of communication between portlets. Events allow portlets to respond on actions or state changes not directly related to an interaction of the user with the portlet.

A portlet can declare events in its deployment descriptor by using the event-definition element in the portlet application section.

In the portlet application section, each portlet specifies the events it would like to publish through the supported-publishing-event element and the events it would like to process through the supported-processing-event element.

The supported-publishing-event and supported-processing-event elements must reference the event name defined in the portlet application section in a event-definition element.

The portlet creates events using the setEvent() method during action processing. This will be processed by the portlet container after the action processing has finished.

To receive events, the portlet must implement the javax.Portlet.EventPortlet interface. The portlet container calls the processEvent() method for each event targeted to the portlet with an EventRequest and EventResponse object. The portlet can access the event that triggered the current process event call by using the EventRequest.getEvent() method. This method returns an object of type Event encapsulating the current event name and value.

Event names are represented as QNames to identify them uniquely. The event name can be retrieved by using the getQName() method that returns the complete QName of the event, or by using the getName() method that only returns the local part of the event name. The value of the event must be based on the type defined in the deployment descriptor.

To create portlets that use the event feature, follow these steps:

1. Declare the events in the portlet.xml file
2. • Set the event definition at the portlet application level. This specifies the event name and the object type.
     Note: The object must be serializable and must be annotated with the XML root element.
     

     <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/ portlet-app_2_0.xsd" 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="myPortletApp" version="2.0"> <portlet> . . . . . . </portlet> <event-definition> <qname xmlns:x="http:sun.com/mapevents">x:Continent</qname> <value-type>com.sun.portal.portlet.mapevent .Continent</value-type> </event-definition> </portlet-app> @XmlRootElement public class Continent implements Serializable { public Continent() { } private String name; private String description; public String getName() { return name; } public void setName(String name) { this.name = name; } public String getDescription() { return description; } public void setDescription(String description) this.description = description; } }

      
     
   • In the portlet section, specify the event name defined above for the portlets that you want to publish in this event.
     

     <portlet-app xmlns=" http://java.sun.com/xml/ns/portlet/ portlet-app_2_0.xsd" 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="myPortletApp" version="2.0"> <portlet> <description>ContinentPortlet</description> <portlet-name>ContinentPortlet</portlet-name> <display-name>ContinentPortlet</display-name> <portlet-class>com.sun.portal.portlet.event.ContinentPortlet</portlet-class> . . . <supported-publishing-event> <qname xmlns:x= "http:sun.com/events">x:Continent</qname> </supported-publishing-event> </portlet> . . . </portlet-app><portlet-class> </portlet-class>

      
     
   • In the portlet section, specify the event name defined above for the portlets that want to process in this event.
     

     <portlet-app xmlns= "http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" 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="myPortletApp" version="2.0"> <portlet> <description>ContinentMapPortlet</description> <portlet-name>ContinentMapPortlet</portlet-name> <display-name>ContinentMapPortlet</display-name> <portlet-class>com.sun.portal.portlet.event.ContinentMapPortlet</portlet-class> . . . <supported-processing-event> <qname xmlns:x= "http:sun.com/events">x:Continent</qname> </supported-processing-event> </portlet> <portlet> <description>ContinentInfoPortlet</description> <portlet-name>ContinentInfoPortlet</portlet-name> <display-name>ContinentInfoPortlet</display-name> <portlet-class>com.sun.portal.portlet.event.ContinentInfoPortlet</portlet-class> . . . <supported-processing-event> <qname xmlns:x= "http:sun.com/events">x:Continent</qname> </supported-processing-event> </portlet> . . . </portlet-app>

      
     
3. Issue an event in the portlet that was specified as a supported-publishing-event event in the portlet.
   
   

   public class ContinentPortlet extends GenericPortlet { public void processAction(ActionRequest request, ActionResponse response) throws PortletException,IOException { QName qname = new QName("http:sun.com/mapevents" , "Continent") String value = request.getParameter("continent"); Continent continent = new Continent(); continent.setName(value); ResourceBundle rb = getPortletConfig() .getResourceBundle(request.getLocale()); continent.setDescription(rb.getString(value)); response.setEvent(qname, continent); } . . . }

    
   
4. Process the event in the portlet that has been specified as a supported-processing-event event in the portlet.
   
   

   public class ContinentInfoPortlet extends GenericPortlet { public void processEvent(EventRequest request, EventResponse response) { Event event = request.getEvent(); if(event.getName().equals("Continent")){ Continent payload = (Continent)event.getValue(); response.setRenderParameter("continentDescription", payload.getDescription()); } } . . . } public class ContinentMapPortlet extends GenericPortlet { public void processEvent(EventRequest request, EventResponse response) { Event event = request.getEvent(); if(event.getName().equals("Continent")){ Continent payload = (Continent)event.getValue(); response.setRenderParameter("continentName", payload.getName()); } } . . . }

    
   

As an illustration, here is a sample application, compressed as a ZIP file. You can also download the binary EventingMap.war file to deploy and run the application.

Figure 1 shows the World Map, Continent Information, and Continent Map Portlets that participate in the event. Clicking on any continent in the World Map triggers an event. This event is processed by the Continent Information and Continent Map Portlets to show the relevant information.

Figure 1: Sample Application: Events

In Java Portlet Specification 1.0 (JSR 168), the render parameters set in the processAction() method are available only in the render phase of the same portlet.

By using the public render parameters feature, the render parameters set in the processAction() method of one portlet are available in render parameters of the other portlets. Using public render parameters instead of events avoids the additional process event call.

To enable coordination of render parameters with other portlets within the same portlet application or across portlet applications, the portlet can declare public render parameters in its deployment descriptor using the public-render-parameter element in the portlet application section. Public render parameters can be viewed and changed by other portlets or components.

In the portlet section, each portlet can specify the public render parameters to be shared through the supported-public-render-parameter element. The supported-public-render-parameter element must reference the identifier of a public render parameter defined in the portlet application section in a public-render-parameter element.

To create portlets that use the public render parameters, follow these steps:

1. Declare the render parameters to be shared in the portlet.xml file by setting the public render parameters at the portlet application level.
   
   

   <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/ portlet-app_2_0.xsd" 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="myPortletApp" version="2.0"> <portlet> . . . </portlet> <public-render-parameter> <identifier>zip-id</identifier> <qname xmlns:x="http://sun.com/params">x:zip</qname> </public-render-parameter> </portlet-app>

    
   
2. Specify the render parameter that the portlet would like to share in the portlet section.
   
   

   <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/ portlet-app_2_0.xsd" 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="myPortletApp" version="2.0"> <portlet> <description>WeatherPortlet</description> <portlet-name>WeatherPortlet</portlet-name> <display-name>WeatherPortlet</display-name> <portlet-class>com.sun.portal.portlet.WeatherPortlet</portlet-class> <supported-public-render-parameter>zip-id</supported-public- render-parameter> </portlet> <portlet> <description>MapPortlet</description> <portlet-name>MapPortlet</portlet-name> <display-name>MapPortlet</display-name> <portlet-class>com.sun.portal.portlet.MapPortlet</portlet-class> . . . <supported-public-render-parameter>zip-id</supported-public- render-parameter> </portlet> . . . </portlet-app>

    
   
3. Set the render parameter in the processAction() method by using the defined public render parameter identifier as the key.
   
   

   public class WeatherPortlet extends GenericPortlet { . . . public void processAction(ActionRequest req, ActionResponse res) throws IOException, PortletException { . . . res.setRenderParameter("zip-id", zip); } . . . }

    
   

Here is a sample application, compressed as a ZIP file. You can also download the binary WeatherMap.war file to deploy and run the sample application.

Figure 2 shows the Weather and Map portlets. The Weather portlet sets the zip which is declared as a Public Render Parameter. This parameter is supported by both Weather and Map portlets. Any change in the value of zip by Weather portlet is reflected during the render phase of both weather and map portlets.

Figure 2: Sample Application: Public Render Parameters

A portlet filter is a Java technology-based component that can be used to modify the content of the portlet request and portlet response before or after any life cycle method of the portlet. The concept of a portlet filter is same as that of a servlet filter. The only difference is that a servlet has only one request handling method, service() and therefore there is only one type of the servlet filter. A portlet on the other hand has four types of request handling methods and therefore there are four different types of portlet filters.

The portlet API defines the following interfaces for creating portlet filters:

•  javax.portlet.filter.ResourceFilter - For serveResource method
•  javax.portlet.filter.RenderFilter - For render method
•  javax.portlet.filter.ActionFilter - For processAction method
•  javax.portlet.filter.EventFilter - For processEvent method

Each of the above filter interface contains a single doFilter(*Request, *Response, FilterChain chain) method which differs in the type of request and response object. For example, the doFilter() method of ActionFilter takes instances of ActionRequest and ActionResponse objects while the doFilter() method of RenderFilter takes instances of the RenderRequest and RenderResponse.

Each filter interface extends a common base interface called javax.portlet.filter.PortletFilter. This common base interface contains the following two methods:

• init(javax.portlet.filter.FilterConfig filterConfig) - The init() method makes sure that every filter has access to a FilterConfig object from which it can obtain its initialization parameters, a reference to the PortletContext which it can use, for example, to load resources needed for filtering tasks.
• destroy() - Signifying the end of service of the filter.

The init() and destroy() methods of a portlet filter are called only once during their lifetime.

A single filter class can provide filter functionality for more than one life cycle method. Also, a single filter can provide filter functionality for more than one portlet. Multiple filters can be associated with one life cycle method of a portlet. The doFilter() method of a portlet filter might create customized request and response objects by using the *RequestWrapper and *ResponseWrapper classes and by passing these wrappers to the doFilter() method of the FilterChain object.

To write a portlet filter, follow these steps:

1. Write a filter class.
   A filter class should implement one or more of the above mentioned four interfaces and should provide a no argument public constructor. The filter class should also override the init() and destroy() methods of the javax.portlet.filter.PortletFilter interface.
   
   

   public class HitCounterFilter implements RenderFilter { private FilterConfig filterConfig = null; public void init(FilterConfig filterConfig) throws PortletException { this.filterConfig = filterConfig; } public void doFilter(RenderRequest renderRequest, RenderResponse renderResponse, FilterChain filterChain) throws IOException, PortletException { . . . StringWriter sw = new StringWriter(); PrintWriter writer = new PrintWriter(sw); . . . writer.println(); writer.println("==============="); writer.println("The number of hits is: " +count); writer.println("==============="); . . . filterChain.doFilter(renderRequest, renderResponse); } public void destroy() { } }

    
   
2. Add the following XML fragments in the portlet.xmlfiles after you write the portlet filter class.
   
   

   <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/ portlet-app_2_0.xsd" 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="myPortletApp" version="2.0"> <portlet> . . . <filter> <filter-name>HitCounterRenderFilter</filter-name> <filter-class>com.sun.portal.portlet.filter .HitCounterFilter</filter-class> <lifecycle>RENDER_PHASE</lifecycle> </filter> <filter-mapping> <filter-name>HitCounterRenderFilter</filter-name> <portlet-name>HelloWorld</portlet-name> </filter-mapping> </portlet-app>

    
   

Here is a sample application, compressed as a ZIP file. Download the PortletFilter.war file to deploy and run the sample application.

The number of times the sample portlet has been accessed is logged using a Filter. Access the portlet and check the application server log file. The log file shows the number of times the portlet has been accessed.

Figure 3: Sample Application: Portlet Filters

The resource serving feature enables a portlet to serve a resource. Portlets can create two kinds of resource links to serve requests:

• Direct links to the resources in the same portlet web application.
  Direct links are not guaranteed to pass through the portal server and will not have portlet context available. So a  direct link should be used in cases where access to the portlet context and access through portal server is not needed.
• Resource URL links that point back to the portlet.
  These links call the serveResource() method of ResourceServingPortlet. This way, the portlet can serve a resource that is protected by the portal security and can leverage the portlet context. Portlet container does not render any output in addition to the content returned by the serveResource call. Thus, the serveResource() method provides more control to you by giving access to write directly on the response object where portal server just acts as a proxy.

• By invoking the createResourceURL() method of the RenderResponse object or ResourceResponse object .
• By using resourceURL tag(i.e portlet:resourceURL).

The presentation logic for the resource serving portlet looks as below:

  <%@ taglib uri=
                      
"http://java.sun.com/portlet_2_0" prefix="portlet" %>
                      


         .........
                      


<portlet:defineObjects/>
                      


       .........
                      


       .........
                      


                       


<portlet:resourceURL var="jsURL" id="js" escapeXml="false" />
                      


                       


/* Load Dojo library, if it hasn't already */
                      


if (typeof dojo == "undefined") {
                      


    /* build script tag */
                      


    var script = document.createElement("script");
                      


    script.src =
                      


"<%=renderResponse.encodeURL(jsURL.toString())%>";
                      


         .........
                      


}
                      


         .........
                      


   
                      


                       
<portlet:resourceURL var="invoiceURL" id="invoice" escapeXml="false" />
                      


                       


    <script type="text/javascript">
                      


/* Use Dojo.io.bind to asynchronously get invoice content */
                      


function <portlet:namespace/>_loadInvoice(invoice) {
                      


    /* If an invoice was selected */
                      


    if (invoice != null && invoice != "null") {
                      


         .........
                      


        var bindArgs = {
                      


            url: "<%=renderResponse.encodeURL(invoiceURL.toString())%>",
                      


            method: "POST",
                      


            content: querystring,
                      


            handle: function(type, data, evt) {
                      


                if (type == "error") {
                      


                    /* Swap returned error message */
                      


                    data = "<p style='color:red'>" + data.message + "</p>";
                      


                       


                }
                      


                       


                /* Swap returned data into div tag */
                      


                var div = document.getElementById("<portlet:namespace/>_content");
                      


                div.innerHTML = "";
                      


                div.innerHTML = data;
                      


            },
                      


            mimetype: "text/html"
                      


        };
                      


        dojo.io.bind(bindArgs);
                      


    }
                      


                       


};
                    

The portlet class that serves the resource looks as below:

public class InvoicePortlet extends GenericPortlet {
                      


    .........
                      


   
                      


    @Override
                      


                       


    public void serveResource(ResourceRequest request, ResourceResponse response) throws PortletException, IOException {
                      


       
                      


        response.setContentType("text/html");
                      


        String resourceID = request.getResourceID();
                      


        Locale locale = request.getLocale();
                      


        
                      


        if (resourceID.equals("invoice")) {
                      


            String invoice = request.getParameter("invoice");
                      


            if (invoice == null) {
                      


                throw new PortletException("Required parameter, invoice, is missing."); } else {
                      


                       


                String path = "/html/" + invoice + ".html";
                      


                String content = getContents(path, locale, true);
                      


                PrintWriter writer = response.getWriter();
                      


                writer.print(content);
                      


            }
                      


                       


        } else if (resourceID.equals("js")) {
                      


                       


            String content = getContents(jsPage, locale, false);
                      


            PrintWriter writer = response.getWriter();
                      


            writer.print(content);
                      


        }
                      


    }
                      


      .........
                      


                       


}
                    

Here is a sample application, compressed as a ZIP file. You can also download the binary InvoiceAjaxPortlet.war file to deploy and run the sample application.

Figure 4 shows the Invoice Portlet. When the user selects a invoice number in the drop-down box, an asynchronous request (AJAX call) is made by the JavaScript client to the portlet. The serveResource() method of the portlet is invoked to serve the content.

Figure 4: Sample Application: Invoice Ajax Portlet

Portlet Container 2.1 introduces a Portlet Policy that governs policies related to events, container events and public render parameters. The policy specifies how the events, container events, and public render parameters are distributed. It also specifies the maximum generation of events to prevent endless loops. If a portlet sends an event to other portlets, it is considered as one event generation. If the other portlets send events, that is considered as two event generations and so on. It also provides the ability to enable/disable the container events.

The portlet-policy.xml file is located in <javaee.home>/domains/domain1/portlet-container/config. The schema is located at https://portlet-container.dev.java.net/xml/portlet-policy.xsd

The portlet-policy.xml file looks like this:

  <portlet-policy
                      


   xmlns=
                      
"https://portlet-container.dev.java.net/xml/portlet-policy.xsd"
                      


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


   xsi:schemaLocation=
                      
"https://portlet-container.dev.java.net/xml/portlet-policy.xsd"
                      


   version="1.0">
                      


                       


      <event-policy>
                      


         <event-distribution>VISIBLE_PORTLETS_ON_PAGE</event-distribution>
                      


         <max-event-generation>3</max-event-generation>
                      


       </event-policy>
                      


                       


      <container-event-policy>
                      


         <event-distribution>ALL_PORTLETS</event-distribution>
                      


         <max-event-generation>2</max-event-generation>
                      


         <event>
                      


             <name>login</name>
                      


             <status>enabled</status>
                      


         </event>
                      


                       


        <event>
                      


             <name>logout</name>
                      


             <status>enabled</status>
                      


        </event>
                      


                       


     </container-event-policy>
                      


                       


     <public-render-parameter-policy>
                      


          <public-render-parameter-distribution>VISIBLE_PORTLETS_ON_PAGE</public-render-parameter-distribution>
                      


     </public-render-parameter-policy>
                      


                       


</portlet-policy>
                    

The above example shows that only visible portlets on the page will receive events and public render parameters. This also specifies that the maximum number of events permitted to be generated is two. This also specifies that the container events, login and logout are enabled.

Currently, only login and logout container events are supported.

Any portlet interested in login event should specify the following in its portlet.xml.
The portlet's processEvent() method will be called when the user logs in.

<supported-processing-event>
                    


    <qname xmlns:x="urn:oasis:names:tc:wsrp:v2:types">
                    


          x:login
                    


    </qname>
                    


</supported-processing-event> 
                  

Any portlet interested in logout event should specify the following in its portlet.xml.
The portlet's processEvent() method will be called when the user logs out.

<supported-processing-event>
                    


    <qname xmlns:x="urn:oasis:names:tc:wsrp:v2:types">
                    


          x:logout
                    


    </qname>
                    


</supported-processing-event>
                    


                  

This article describes the features that are included in the Portlet Container 2.1 software. The Portlet Container 2.1 software includes the following new features from the Java Portlet Specifications: JSR 286:

• Events
• Public render parameters
• Portlet filters
• Resource serving

This article has also provided sample applications for each of these features and shows how use the features in the portlets.

• Portlet Container 2.1 Release Notes
• Portlet Container 2.1 Installation Instructions
• Understanding the Portlet Container 1.0 Software and Deploying Portlets
• Java Specification Request (JSR) 286
• Portlet Container 1.0 Release Notes
• Portlet Container 1.0 Installation Instructions
• Testing Portlets Using Portlet Container — a screencast
• Developing Portlets with NetBeans Portal Pack 3.0 Beta — an article
• Introducing Java Portlet Specifications: JSR 168 and JSR 286 — an article
• Enterprise Class Portlet Container
• JSR 168 Portlet Specification
• Java EE SDK download page
• The Aquarium — a group blog
• Portal Post — a group blog
• Sun Java Application Platform Suite product page
• Information on Java Platform, Enterprise Edition 5 (Java EE 5)
• An Introduction to the Java EE 5 Platform — an article
• Java Application Platform SDK: Overview — an article
• Java EE 5 Tutorial
• GlassFish Application Server: Introduction — training course
• Sun Java System Application Server Platform Edition 9.0: Overview — training course
• Sun Java System Application Server Platform Edition 9.0 support
• Java EE Learning Path
• Sun Developer Expert Assistance