Saturday, 9 August 2014

A Quick Portlet Tutorial




What is a Portlet?


"Portlets are web components--like servlets--specifically designed to be aggregated in the context of a composite page. Usually, many portlets are invoked to in the single request of a portal page. Each portlet produces a fragment of markup that is combined with the markup of other portlets, all within the portal page markup.

The Portlet specification defines a portlet as a "Java-technology-based web component, managed by a portlet container that processes requests and generates dynamic content.
Portlets are individual classes that process requests from a user and return content for display inside a portal.

A portlet is a class that implements the javax.portlet.Portlet interface and is packaged and deployed as a .war file inside of a portlet container.

Portlets provide some additional functionalities:

1.  Persistent storage for preferences: Portlets provide a PortletPreferences object for storing user preferences. These preferences are stored in a persistent data store, so they will be available across server restarts. As a developer, you don't have to worry about the actual implementation of how it is stored.

2.   Request processing: Portlets provide much more refined request handling. A portlet may get a request when user takes some action on it (a state called action phase), or because the user took action on some other portlet and the page needs to be refreshed. A portal server provides different callback methods for handling both situations.

3.  Portlet modes: Portlets use a concept of mode to indicate what user is doing. When using a mail application, you may be using it for reading, composing, or checking mail messages--this is the expected functionality of a mail application. Portlets normally provide this in VIEW mode. But there are other activities, like specifying a refresh time or (re-)setting the username and password. These activities allow the user to configure the behavior of the application, so they come under EDIT mode. Help functionality of the mail application comes under HELP mode.
If you think about it, you will find none of these represents new functionality. Instead, most of these are common business requirements. The only thing the portlet specification is doing is providing you one layer of abstraction, so that it will be useful for all stake holders end users, developers and administrators.
As a developer, I put all my business logic related to VIEW mode in a method called doView(), and I put business logic related to the configuration of my application in a doEdit() method, with help-related logic in a doHelp() method.
This makes it simple for an administrator to control access in the portlet application, because all he has to do is change access rights of the portlet to dictate what things a user is allowed to do. For example, a user of a mail application is supposed to specify his username and password in EDIT mode, so it makes sense for him to have access to EDIT mode.
But consider the case where I am the administrator of an intranet site and my company bought a third-party portlet application that displays news updates. This application allows a user to specify the URL from where it can retrieve updates. I want to use this application for displaying internal company news to users. Another requirement is that I don't want users to use this application for tracking any other news source. So as the administrator, I can specify the URL of an internal news update site for all users, and take out their edit privileges by changing the deployment descriptor of this portlet application.
Using portlets makes my website much more appealing to the end user because she will get a similar UI for all her portlet applications. If she wants to read help information about any of the applications, she can click the help button. She will also know that clicking on an edit button will take her to a configure screen for that application. Standardizing the user interface will make your portlet application more appealing.

4.   Window state: The window state determines how much space should be given to content generated by a portlet on a portal page. If you click on the maximize button, the portlet will take up the entire screen and it will become the only portlet that will be available to the user. In minimized state, the portlet will be displayed as only a title bar. As a developer, you should customize your content based on the space available to you.
5.  User information: Commonly, portlets provide content personalized to the user making the request. To do this effectively, they may require access to user attributes such as name, email, phone, etc. The Portlet API provides the concept of user attributes for this. A developer can access these attributes in a standard way, and it is the responsibility of the administrator to map these attributes to an actual user information repository (usually an LDAP server).



What is a Portal?


In order to understand what a portlet is, it is very necessary to understand what a portal is. According to the Portlet Specification, "a portal is a web application that commonly provides personalization, single sign on, content aggregation from different sources, and hosts the presentation layer of information systems. Aggregation is the act of integrating content from different sources within a web page."

Portal functionality can be divided into three main parts:

1.  Portlet container: A portlet container is very similar to a servlet container, in that every portlet is deployed inside a portlet container that controls the life cycle of the portlet and provides it with necessary resources and information about its environment. A portlet container is responsible for initializing and destroying portlets and also for passing user requests to it and collecting responses.

2.  Content aggregator: As defined in the Portlet Specification, one of the main jobs of a portal is to aggregate content generated by various portlet applications. We will talk more about this in the "How a Portal Page is Created" section.

3.   Common services: One of the main strengths of a portal server is the set of common services that it provides. Services are not part of the portlet specification, but commercial portal implementations provide a rich set of common services to distinguish themselves from their competitors. A few common services that you can hope to find in most implementations are: 

o   Single sign on: Allows you to get access to all other applications once you log into the portal server, meaning you don't have to log into every application separately. For example, once I log in to my intranet site, I should get access to my mail application, IM messaging application, and other intranet applications, without having to log into each of these applications separately.
A portal server will provide you with a secured credentials store. What you do is to go to the mail application and specify your user name and password once. This information will be stored in the credentials store in encrypted form. From the next time onwards, when you log into your intranet site, the portal server will read your credentials from the store and log into your mail server on your behalf. The same goes for other applications.

o  Personalization: The basic implementation of personalization service allows a user to customize her page in two ways. First, the user can decide what colors she wants for title bars and what icons she wants for controls. Second, the user can decide which portlets she wants on her page. For example, if I'm a big sports fan, I will probably replace the stock and news update portlets with a portlet that lets me track my favorite team.
There are also a few advanced commercial implementations of personalization services that allow you to decide which applications should be displayed to user based on criteria such as his income or interests. In this case, you can create some business rules like "Show the premium products portlet to any user with X amount of income" and "Show the discount deals portlet to users with Y amount of income."




Portlet Application


Portlet applications are standard J2EE web applications that include portlet classes and the portlet.xml portlet deployment descriptor.


Portlet Container


  • The lifecycle of a portlet is managed by the portlet container. A portlet container runs portlets and provides them with the required runtime environment. A portlet container contains portlets and manages their lifecycle. It also provides persistent storage for portlet preferences. A portlet container receives requests from the portal to execute requests on the portlets hosted by it.
  • A portlet container is not responsible for aggregating the content  produced by the portlets. It is the responsibility of the portal to handle the aggregation
  • A portal and a portlet container can be built together as a single component of an application suite or as two separate components of a portal application.
  • The portlet container is an extension of the servlet container. As such, a portlet container can be built on top of an existing servlet container or it may implement all the functionality of a servlet container. Regardless of how a portlet container is implemented, its runtime environment is assumed to support at least Servlet Specification 2.4.




Portal Page Creation


·        A client (e.g., a web browser) makes an HTTP request to the portal

·        The request is received by the portal

·        The portal determines if the request contains an action targeted to any of the portlets associated with the     portal page

·        If there is an action targeted to a portlet, the portal requests the portlet container to invoke the portlet to process the action.

·        A portal invokes portlets, through the portlet container, to obtain content fragments that can be included in the resulting portal page

·        The portal aggregates the output of the portlets in the portal page and sends the portal page back to the client




Elements of a Portal Page


  •  A portlet generates markup fragments.
  •  A portal may add a title, control buttons and other decorations to the   markup fragment generated by the portlet, this new fragment is called a portlet window.
  • Then the portal may aggregate portlet windows into a complete document, the portal page.



Portlet lifecycle


The Portlet interface is the main abstraction of the Portlet API. All portlets implement this interface either directly or, more commonly, by extending a class that implements the interface
The Portlet API includes a GenericPortlet class that implements the Portlet, EventPortlet and ResourceServingPortlet interface and provides default functionality. Developers should typically extend, directly or indirectly, the GenericPortlet class to implement their portlets.


1.     Init

      void init(PortletConfig config) throws PortletException
 
Called by the portlet container to indicate to a portlet that the portlet is being placed into service.
The portlet container calls the init method exactly once after instantiating the portlet. The init method must complete successfully before the portlet can receive any requests.
The portlet container cannot place the portlet into service if the init method
1.     Throws a PortletException
2.     Does not return within a time period defined by the portlet container.
Parameters:
config - a PortletConfig object containing the portlet's configuration and initialization parameters
Throws:
PortletException - if an exception has occurred that interferes with the portlet's normal operation.
UnavailableException - if the portlet cannot perform the initialization at this time.

2.     Render

       void render(RenderRequest request,RenderResponse response) 
                                throws PortletException, java.io.IOException
 
Called by the portlet container to allow the portlet to generate the content of the response based on its current state.
Parameters:
request - the render request
response - the render response
Throws:
PortletException - if the portlet has problems fulfilling the rendering request
UnavailableException - if the portlet is unavailable to perform render at this time
PortletSecurityException - if the portlet cannot fullfill this request because of security reasons
java.io.IOException - if the streaming causes an I/O problem


3.     processAction

       void processAction(ActionRequest request, ActionResponse response)
                   throws PortletException,java.io.IOException
 
Called by the portlet container to allow the portlet to process an action request. This method is called if the client request was originated by a URL created (by the portlet) with the RenderResponse.createActionURL() method.
Typically, in response to an action request, a portlet updates state based on the information sent in the action request parameters. In an action the portlet may:
·         issue a redirect
·         change its window state
·         change its portlet mode
·         modify its persistent state
·         set render parameters
A client request triggered by an action URL translates into one action request and many render requests, one per portlet in the portal page. The action processing must be finished before the render requests can be issued.
Parameters:
request - the action request
response - the action response
Throws:
PortletException - if the portlet has problems fulfilling the request
UnavailableException - if the portlet is unavailable to process the action at this time
PortletSecurityException - if the portlet cannot fullfill this request because of security reasons
java.io.IOException - if the streaming causes an I/O problem

4.     destroy

      void destroy()
 
Called by the portlet container to indicate to a portlet that the portlet is being taken out of service.
Before the portlet container calls the destroy method, it should allow any threads that are currently processing requests within the portlet object to complete execution. To avoid waiting forever, the portlet container can optionally wait for a predefined time before destroying the portlet object.
This method enables the portlet to do the following:
  
  •     Clean up any resources that it holds (for example, memory, file handles, threads)
  •     Make sure that any persistent state is synchronized with the portlet current state in memory.


Portlet Window



  •  A window state is an indicator of the amount of portal page space that will be assigned to the content generated by a portlet via the render method.
  •   The Portlet Specification defines three window states, NORMAL, MAXIMIZED and MINIMIZED. The WindowState class defines constants for these window states.
  •   The NORMAL window state indicates that a portlet may be sharing the page with other portlets. It may also indicate that the target device has limited display capabilities. Therefore, a portlet should restrict the size of its rendered output in this window state.
  • The MAXIMIZED window state is an indication that a portlet may be the only portlet being rendered in the portal page, or that the portlet has more space compared to other portlets in the portal page. A portlet may generate richer content when its window state is MAXIMIZED.
  • When a portlet is in MINIMIZED window state, the portlet should only render minimal output or no output at all.

By default, normal window state is displayed when portlet is called.

In this example, i have mentioned three window state. In process action method(called by edit mode) ,we can change portlet mode and window state.

Sample Code:

Portlet.xml
<portlet-app>
    <portlet>
        <portlet-name>ninethExample</portlet-name>
        <display-name xml:lang="en">ninethExample</display-name>
        <display-name>ninethExample</display-name>
        <portlet-class>com.anand.ninethexample.NinethExamplePortlet</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>
            <portlet-mode>edit</portlet-mode>
            <window-state>normal</window-state>
            <window-state>minimized</window-state>
            <window-state>maximized</window-state>
        </supports>
        <supported-locale>en</supported-locale>
        <portlet-info>
            <title>ninethExample</title>
            <short-title>ninethExample</short-title>
            <keywords>ninethExample</keywords>
        </portlet-info>
    </portlet>
    <default-namespace>http://ninethExample/</default-namespace>
</portlet-app>

NinethExamplePortlet 

package com.anand.ninethexample;
import java.io.*;
import javax.portlet.*;
public class NinethExamplePortlet extends GenericPortlet {
    public static final String JSP_FOLDER    = "/_ninethExample/jsp/";    // JSP folder name
    public static final String VIEW_JSP      = "NinethExamplePortletView";         // JSP file name to be rendered on the view mode
    public static final String EDIT_JSP      = "NinethExamplePortletEdit";         // JSP file name to be rendered on the edit mode
   
    public void init() throws PortletException{
        super.init();
    }
    public void doView(RenderRequest request, RenderResponse response) throws PortletException, IOException {
        // Set the MIME type for the render response
        response.setContentType(request.getResponseContentType());
        PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher(getJspFilePath(request, VIEW_JSP));
        rd.include(request,response);
    }

    public void doEdit(RenderRequest request, RenderResponse response) throws PortletException, IOException {
        // Set the MIME type for the render response
        response.setContentType(request.getResponseContentType());
        PortletRequestDispatcher rd = getPortletContext().getRequestDispatcher(getJspFilePath(request, EDIT_JSP));
        rd.include(request,response);
    }
   
    public void processAction(ActionRequest request, ActionResponse response) throws PortletException, java.io.IOException {
                response.setPortletMode(PortletMode.VIEW);
                response.setWindowState(WindowState.MAXIMIZED);
    }






Important Classes and Interface



Portlet (Interface)


 public Interface Portlet 


  The Portlet interface is used by the portlet container to invoke the portlets. Every portlet has to implement this interface, either by directly implementing it, or by using an existing class implementing the Portlet interface.
A portlet is a Java technology-based web component. It is managed by the portlet container and processes requests and generates dynamic content as response. Portlets are used by portals as pluggable user interface components.
The content generated by a portlet is called a fragment. A fragment is a piece of markup (e.g. HTML, XHTML, WML) adhering to certain rules and can be aggregated with other fragments into a complete document. The content of a portlet is normally aggregated with the content of other portlets into the portal page.
The portlet container instantiates portlets, manages their lifecycle and invoking them to process requests. The lifecycle consists of:
  • initializing the portlet using using the init method
  • request processsing
  • taking the portlet out of service using the destroy method
Request processing is divided into two types:
  • action requests handled through the processAction method, to perform actions targeted to the portlet
  • render requests handled through the render method, to perform the render operation

    

GenericPortlet (Abstract Class)


public abstract class GenericPortlet
extends java.lang.Object
implements Portlet, PortletConfig, EventPortlet, ResourceServingPortlet



The GenericPortlet class provides a default implementation for the Portlet interface.
It provides an abstract class to be subclassed to create portlets. A subclass of GenericPortlet should either use one of the following annotations:
  • @ProcessAction
  • @ProcessEvent
  • @RenderMode
or override at least one method, usually one of the following:
  • processAction, to handle action requests
  • doView, to handle render requests when in VIEW mode
  • doEdit, to handle render requests when in EDIT mode
  • doHelp, to handle render request when in HELP mode
  • init and destroy, to manage resources that are held for the life of the servlet
Normally there is no need to override the render or the doDispatch methods. Render handles render requests setting the title of the portlet in the response and invoking doDispatch. doDispatch dispatches the request to one of the doView, doEdit or doHelp method depending on the portlet mode indicated in the request.
Portlets typically run on multithreaded servers, so please note that a portlet must handle concurrent requests and be careful to synchronize access to shared resources. Shared resources include in-memory data such as instance or class variables and external objects such as files, database connections, and network connections.




 

PortletConfig (Interface)



public interface PortletConfig

The PortletConfig interface provides the portlet with its configuration. The configuration holds information about the portlet that is valid for all users. The configuration is retrieved from the portlet definition in the deployment descriptor. The portlet can only read the configuration data.

The configuration information contains the portlet name, the portlet initialization parameters, the portlet resource bundle and the portlet application context.

Method Summary
 java.util.Map<java.lang.String,java.lang.String[]>
getContainerRuntimeOptions()
          Returns the container runtime options and values for this portlet.
 java.lang.String
getDefaultNamespace()
          Returns the default namespace for events and public render parameters.
 java.lang.String
getInitParameter(java.lang.String name)
          Returns a String containing the value of the named initialization parameter, or null if the parameter does not exist.
 java.util.Enumeration<java.lang.String>
getInitParameterNames()
          Returns the names of the portlet initialization parameters as an Enumeration of String objects, or an empty Enumeration if the portlet has no initialization parameters.
 PortletContext
getPortletContext()
          Returns the PortletContext of the portlet application the portlet is in.
 java.lang.String
getPortletName()
          Returns the name of the portlet.
 java.util.Enumeration<javax.xml.namespace.QName>
getProcessingEventQNames()
          Returns the QNames of the processing events supported by the portlet as an Enumeration of QName objects, or an empty Enumeration if the portlet has not defined any processing events.
 java.util.Enumeration<java.lang.String>
getPublicRenderParameterNames()
          Returns the names of the public render parameters supported by the portlet as an Enumeration of String objects, or an empty Enumeration if the portlet has not defined public render parameters.
 java.util.Enumeration<javax.xml.namespace.QName>
getPublishingEventQNames()
          Returns the QNames of the publishing events supported by the portlet as an Enumeration of QName objects, or an empty Enumeration if the portlet has not defined any publishing events.
 java.util.ResourceBundle
getResourceBundle(java.util.Locale locale)
          Gets the resource bundle for the given locale based on the resource bundle defined in the deployment descriptor with resource-bundle tag or the inlined resources defined in the deployment descriptor.
 java.util.Enumeration<java.util.Locale>
getSupportedLocales()
          Returns the locales supported by the portlet as an Enumeration of Locale objects, or an empty Enumeration if the portlet has not defined any supported locales.





PortletContext (Interface)


public interface PortletContext
The PortletContext interface defines a portlet view of the portlet container. The PortletContext also makes resources available to the portlet. Using the context, a portlet can access the portlet log, and obtain URL references to resources.
There is one context per "portlet application" per Java Virtual Machine. (A "portlet application" is a collection of portlets, servlets, and content installed under a specific subset of the server URL namespace, such as /catalog. They are possibly installed via a .war file.) As a web application, a portlet application also has a servlet context. The portlet context leverages most of its functionality from the servlet context of the portlet application.
Attributes stored in the context are global for all users and all components in the portlet application.
In the case of a web application marked "distributed" in its deployment descriptor, there will be one context instance for each virtual machine. In this situation, the context cannot be used as a location to share global information (because the information is not truly global). Use an external resource, such as a database to achieve sharing on a global scope.

PortletPreferences (Interface)


public interface PortletPreferences
The PortletPreferences interface allows the portlet to store configuration data. It is not the purpose of this interface to replace general purpose databases.
There are two different types of preferences:
  • modifiable preferences - these preferences can be changed by the portlet in any standard portlet mode (EDIT, HELP, VIEW). Per default every preference is modifiable.
  • read-only preferences - these preferences cannot be changed by the portlet in any standard portlet mode, but may be changed by administrative modes. Preferences are read-only, if these are defined in the deployment descriptor with read-only set to true, or if the portlet container restricts write access.
Changes are persisted when the store method is called. The store method can only be invoked within the scope of a processAction call. Changes that are not persisted are discarded when the processAction or render method ends.

Method Summary
 java.util.Map<java.lang.String,
java.lang.String[]>
getMap()
          Returns a Map of the preferences.
 java.util.Enumeration<java.lang.String>
getNames()
          Returns all of the keys that have an associated value, or an empty Enumeration if no keys are available.
 java.lang.String
getValue(java.lang.String key, java.lang.String def)
          Returns the first String value associated with the specified key of this preference.
 java.lang.String[]
getValues(java.lang.String key, java.lang.String[] def)
          Returns the String array value associated with the specified key in this preference.
 boolean
isReadOnly(java.lang.String key)
          Returns true, if the value of this key is defined as read-only and thus cannot be modified by the user.
 void
reset(java.lang.String key)
          Resets or removes the value associated with the specified key.
 void
setValue(java.lang.String key, java.lang.String value)
          Associates the specified String value with the specified key in this preference.
 void
setValues(java.lang.String key, java.lang.String[] values)
          Associates the specified String array value with the specified key in this preference.
 void
store()
          Commits all changes made to the preferences via the set methods in the persistent store.




EventPortlet (Interface)


public interface EventPortlet
The EventPortlet interface allows portlets receiving events.
Events are part of the action processing and must be finished before the rendering phase can start. Portlets can receive events issued by other portlets or portlet container defined events.
Portlets should declare the events it would like to receive via the supported-processing-event tag and events published via the supported-publishing-event tag in the portlet deployment descriptor.
The event model is a loosely coupled model where the wiring between published and receiving events is done at the portal / portlet container level.

 

 

 ActionRequest (Interface)


public interface ActionRequest extends ClientDataRequest
The ActionRequest represents the request sent to the portlet to handle an action.
It extends the ClientDataRequest interface and provides action request information to portlets.
The portlet container creates an ActionRequest object and passes it as argument to the portlet's processAction method.

ActionResponse (Interface)


public interface ActionResponse extends StateAwareResponse
The ActionResponse interface represents the portlet response to an action request. It extends the StateAwareResponse interface to provide specific action response functionality to portlets.
The portlet container creates an ActionResponse object and passes it as argument to the portlet's processAction method.

 

RenderRequest (Interface)


public interface RenderRequest extends PortletRequest
The RenderRequest represents the request sent to the portlet to handle a render. It extends the PortletRequest interface to provide render request information to portlets.
The portlet container creates a RenderRequest object and passes it as argument to the portlet's render method.

 

RenderResponse (Interface)


public interface RenderResponse
extends MimeResponse
The RenderResponse defines an object to assist a portlet in sending a response to the portal. It extends the MimeResponse interface to provide specific render response functionality to portlets.
The portlet container creates a RenderResponse object and passes it as argument to the portlet's render method.

 

PortletURL (Interface)


public interface PortletURL extends BaseURL
The PortletURL interface represents a URL that reference the portlet itself.
A PortletURL is created through the RenderResponse or ResourceResponse. Parameters, a portlet mode, a window state and a security level can be added to PortletURL objects.
There are two types of PortletURLs:
  • Action URLs, they are created with createActionURL, and trigger an action request followed by a render request.
  • Render URLs, they are created with createRenderURL, and trigger a render request.
The string representation of a PortletURL does not need to be a valid URL at the time the portlet is generating its content. It may contain special tokens that will be converted to a valid URL, by the portal, before the content is returned to the client.

Method Summary
 PortletMode
getPortletMode()
          Returns the currently set portlet mode on this PortletURL.
 WindowState
getWindowState()
          Returns the currently set window state on this PortletURL.
 void
removePublicRenderParameter(java.lang.String name)
          Removes the specified public render parameter.
 void
setPortletMode(PortletMode portletMode)
          Indicates the portlet mode the portlet must be in, if this portlet URL triggers a request.
 void
setWindowState(WindowState windowState)
          Indicates the window state the portlet should be in, if this portlet URL triggers a request.

PortletRequestDispatcher (Interface)


public interface PortletRequestDispatcher
The PortletRequestDispatcher interface defines an object that receives requests from the client and sends them to the specified resources (such as a servlet, HTML file, or JSP file) on the server. The portlet container creates the PortletRequestDispatcher object, which is used as a wrapper around a server resource located at a particular path or given by a particular name.

Method Summary
 void
forward(PortletRequest request, PortletResponse response)
          Forwards a portlet request from a portlet to another resource (servlet, JSP file, or HTML file) on the server.
 void
include(PortletRequest request, PortletResponse response)
          Includes the content of a resource (servlet, JSP page, HTML file) in the response.
 void
include(RenderRequest request, RenderResponse response)
          Includes the content of a resource (servlet, JSP page, HTML file) in the response.


PortletSession (Interface)


public interface PortletSession
The PortletSession interface provides a way to identify a user across more than one request and to store transient information about that user.
A PortletSession is created per user client per portlet application.
A portlet can bind an object attribute into a PortletSession by name. The PortletSession interface defines two scopes for storing objects:
  • APPLICATION_SCOPE
  • PORTLET_SCOPE
All objects stored in the session using the APPLICATION_SCOPE must be available to all the portlets, servlets and JSPs that belongs to the same portlet application and that handles a request identified as being a part of the same session. Objects stored in the session using the PORTLET_SCOPE must be available to the portlet during requests for the same portlet window that the objects where stored from. Attributes stored in the PORTLET_SCOPE are not protected from other web components of the portlet application. They are just conveniently namespaced.
The portlet session is based on the HttpSession. Therefore all HttpSession listeners do apply to the portlet session and attributes set in the portlet session are visible in the HttpSession and vice versa.


Download pdf
Posted by

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)