Portlet basic tutorial

Understanding portlets

A Web portal can be defined as a specialized Website that aggregates content and services from diverse sources and presents them in a single unified format to its users. The front pages of Yahoo and Google, which you can customize to present the information you're most interested in, are perfect examples of Web portals. Web portals are also commonly used within organizations, where they're known as corporate intranet portals. Typically, a Web portal is built using specialized software called a portal server.

The Portlet 2.0 specification, established by JSR-286, defines a standardized Web component called a portlet. In simple terms, a portlet is a piece of dynamic functionality that can be plugged into any compliant portal server. The portal server can run multiple portlets simultaneously to create a portal page. Figure 1 illustrates a simple portal page.

The portal page aggregates output from multiple portlets, with each portlet's content being confined to its own section of the page, called a portlet window. The portal adds decorations and controls to those windows, which are used for the operations supported by the portal -- such as minimizing or maximizing the windows.

The portlet container and portlet lifecycle

Like most Java EE components, portlets have a well-defined lifecycle and require a specialized runtime; for a portlet, this runtime is called a portlet container. This container, which is one of the key components of the portal server, is responsible for the execution and management of the lifecycle of all the portlets in the portal.
Table 1 offers a closer look at a portlet's lifecycle. A portlet is defined by a javax.portlet.Portlet interface. This interface defines the four lifecycle methods of a portlet: init(), processAction(), render(), and destroy(). In addition, a portlet can also implement two optional lifecycle methods, processEvent() and serveResource(), defined by the interfaces javax.portlet.EventPortlet and javax.portlet.ResourceServingPortlet, respectively. Table 1 summarizes these methods.

Table 1. Portlet lifecycle methods

Lifecycle method	Type	Interface	Description
init()	Mandatory	javax.portlet.Portlet	Invoked by the container when the portlet is put into service.
render()	Mandatory	javax.portlet.Portlet	Invoked by the container to generate the content of the portlet.
processAction()	Mandatory	javax.portlet.Portlet	Invoked by the container in response to a user action on this portlet.
destroy()	Mandatory	javax.portlet.Portlet	Invoked by the container when the portlet is pulled out of service.
processEvent()	Optional	javax.portlet.EventPortlet	Invoked by the container to process the occurrence of a specific event.
serverResource()	Optional	javax.portlet.ResourceServingPortlet	Invoked by the container if the portlet needs to generate any dynamic content.

From servlets to portlets

The portlet specification borrows several paradigms from the Java Servlet spec, making it very easy for a servlet developer to transition into portlet development. For example, portlets have a PortletSession similar to a servlet's HttpSession. The portlet specification also defines PortletConfig, PortletContext, PortletFilter, and other objects that are conceptually comparable to their servlet counterparts. Portlets are also typically coded by extending an abstract superclass called the GenericPortlet (akin to the HttpServlet).

The Hello World portlet

To better understand how portlets work in practice, you'll implement a simple Hello World portlet. The HelloWorldPortlet shown in Listing 1 extends the javax.portlet.GenericPortlet base class. Among other things, this base class provides an implementation for all of a portlet's mandatory lifecycle methods. As a result, you need only override the specific methods that you're interested in. The example overrides the render() method, which is responsible for generating the portlet's content. It also implements the optional ResourceServingPortlet interface.

Listing 1. HelloWorldPortlet

public class HelloWorldPortlet extends GenericPortlet implements ResourceServingPortlet{

    public void render(RenderRequest request, RenderResponse response)

        throws PortletException, IOException{

                response.setContentType("text/html");

                response.getWriter().write("<p>Hello Portlet 2.0 World</p><br/>");

          response.getWriter().write("<a onClick=\"window.open('"+response.createResourceURL()+"',

                           'mywindow','width=400,height=200');return  false;\">Click Me</a>");

               

    }

    public void serveResource(ResourceRequest request, ResourceResponse response)

        throws PortletException, IOException{

       

        response.setContentType("text/html");

        response.getWriter().write("Output From Serve Resource");

       

       

    }

}

Because a portlet is an extended component of a Web application, it is packaged as a WAR file. Each WAR file corresponds to one portlet application, and each portlet application can contain multiple portlets. Also, in addition to a regular web.xml file, this WAR file requires a new kind of descriptor, called the portlet deployment descriptor, with the filename portlet.xml. All portlets and portlet-related settings are defined in this file. Listing 2 contains the portlet.xml file for the sample application.

Listing 2. portlet.xml for HelloWorldPortlet

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

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

 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\">

   <portlet>

       <portlet-name>HelloWorldPortlet</portlet-name>

           <portlet-class>examples.example1.HelloWorldPortlet</portlet-class>

           <supports>

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

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

           <portlet-mode>edit</portlet-mode>

           <portlet-mode>help</portlet-mode>

           </supports>

           <portlet-info>

               <title>Hello World Portlet</title>               

           </portlet-info>

       </portlet>

</portlet-app>

Event request handling

In Portlet 1.0, there were two types of request: action and render. All action requests would be handled by portlets first, and only after that would render requests kick in. Event requests in Portlet 2.0 fall between these two request types. In Portlet 2.0, after all the action requests have been completed, event requests kick in, and when event requests and response requests have been completed, render requests kick in. Figure 1 illustrates the sequence.

Defining events

To define an event, you would have to declare it in portlet.xml, as shown in Listing 1.

Listing 1. Defining an event

<event-definition>

      <qname xmlns:mycomp='http://www.mycomp.com/jsr286'>mycomp:AppEvent</qname>

      <value-type>com.mycomp.portal.jsr286.WrapperEvent</value-type>

</event-definition>

The <event-definition> tag is a sibling of the <portlet> tag. Listing 1 defines an event named mycomp:AppEvent, where mycomp refers to the namespace and AppEvent is the local name. Its type is defined by the <value-type> tag. Here, the type is a custom Java class; it could have also been a primitive type or any standard class defined in the JAXB 2.0 specification (except java.lang.Object). These event definitions require you to use qname to uniquely identify the event. You can define multiple events in portlet.xml.
The next step is to add the events to specific portlets, which are either going to publish (generate) an event or process (consume) an event. You add this information to portlet.xml as well. You would define the publishing of an event using the <supported-publishing-event> tag, as in Listing 2.

Listing 2. Publishing an event

<portlet>

....

<supported-publishing-event>

         <qname xmlns:mycomp='http://www.mycomp.com/jsr286'>mycomp:AppEvent</qname>

</supported-publishing-event>

....

</portlet>

And you would define the processing of an event using the <supported-processing-event> tag, as in Listing 3.

Listing 3. Processing an event

<portlet>

....

<supported-processing-event>

         <qname xmlns:mycomp='http://www.mycomp.com/jsr286'>mycomp:AppEvent</qname>

</supported-processing-event>

....

</portlet>

Each portlet definition can have both publishing and processing tags, and you could define multiple events within each portlet definition. Apart from these event definitions, your portlet.xml would look exactly as it would under the Portlet 1.0 spec.
Take a look at the portlet.xml files for the sample applications. jsrsample's portlet.xml file has event definition, publishing event, and processing event tags, as its portlets create and consume events. jsrsample2's portlet.xml contains only definition and processing event tags, as the portlet in this application only consumes events.