8.3 Portlet development

In this section, we discuss the steps that you need to develop a portlet.

For the sample application, the portlets provide the content for every task.

8.3.1 Developing a portlet

This section provides the steps for developing a portlet. Basically, there are three things we must do. The first step is to create the .java class; the second step is to create the .jsp for the user to view the data and the last step is to create the deployment descriptor.

We are not covering the steps for installing the portlet in the WebSphere Portal Server; the assumption is that you already are familiar these steps. If you need more information, read the IBM WebSphere Portal 4.1 Handbook - Volume One , SG24-6883.

Portlet class

At this point, we can start developing the portlets. The portlet we develop here is the same that the sequence diagram represents in the previous section.

The method doView is activated when View Mode is active in the framework. This is a default mode for a portlet. When a portlet is in this mode, it is rendering data in its default display mode. This method will receive the request and generate a response.

The framework has the following other modes.

Edit Mode: this mode is active when the user clicks the edit icon displayed in the portlet's title bar. When a portlet is in edit mode, a dialog is displayed that lets the user customize the settings of the portlet.
Configure Mode: a portal administrator, during the manage portlets process, can invoke configuration of the portlet by selecting the Modify Parameters function. In this mode, the portlet displays a dialog that lets the administrator configure the portlet for the portal. These settings are global in nature, and typical settings for the portlet (the target back-end server URL, for example); they are not settings for a particular user.
Help Mode: this mode is made active when the user clicks the help icon displayed in the portlet's title bar. When a portlet is in help mode, help information for the user should be displayed. This help information should explain how the user customizes the portlet settings and how the portlet display is interpreted.

Example 8-1: Getting the request from the browser

 public void doView(PortletRequest req, PortletResponse res)throws PortletException, IOException {    //* get the user from request    User user = req.getUser();    req.setAttribute("userID", user.getUserID());    //* forward to page error if find some problem    if (req.getAttribute("errorMessage") == null)       getConfig().getContext().include(FORM_PAGE, req, res);    else       getConfig().getContext().include(ERROR_PAGE, req, res); }

In this code, the method doView gets the user information from the request and saves it in the user object. The user object is one instance of the user interface that contains methods for accessing attributes from the user, such as the user's full name or user ID.

In this case, the user ID is saved in the request. The method forwards to a JSP because we are using the MVC model and have no HTML code in the portlet class.

When the user posts the data, the container calls one event. Portlet events contain information about an event to which a portlet might need to respond. For example, when a user clicks a link or a button, it generates an action event. To receive notification of the event, the portlet must have an event listener implemented in the portlet itself. In the Portlet API, there are three types of events:

ActionEvents: generated when a HTTP request is received by the portlet container that is associated with an action, such as when the user clicks a link.
MessageEvents: generated when a portlet sends a message to another portlet.
WindowEvents: generated when the user changes the state of the portlet window.

The portlet container delivers all events to the respective event listeners (and thereby to the portlets) before generating the new content that the event requires. Should a listener, while processing the event, find that another event needs to be generated, that event will be queued by the portlet container and delivered at a point of time that is at the discretion of the portlet container. All that is guaranteed is that it will be delivered and that this will happen before the content generation phase.

The most common event is the ActionEvent. An ActionEvent is sent to the related portlet when an HTTP request is received that is associated with a PortletAction. PortletActions can be linked to URLs by using the PortletAPI. Normally, PortletActions are linked with HTTP references or buttons in HTML forms, enabling the portlet programmer to implement different processing paths for different user selections. The ActionEvent of the clicked link then carries the associated PortletAction back to the portlet which in turn is able to process different paths on behalf of the PortletAction.

We have one sample for the ActionEvent, below.

Example 8-2: Getting the ActionEvent

 public void actionPerformed(ActionEvent event) {    DefaultPortletAction action = (DefaultPortletAction)event.getAction();    PortletRequest req = event.getRequest();    if (action.getName().equals("save")) {       //* This action will call when the user want to save defect.       try {          //* Get the data from request          Long defectID = new Long(req.getParameter("txtDefectID"));          String comments = req.getParameter("txtComments");          //* Call one stateless bean to create one order to client          DefectServiceHome defectServiceHome =          (DefectServiceHome)ServiceLocator.getInstance().getHome("ejb/DefectSe          rvice");          DefectService defectService = defectServiceHome.create();          defectService.createOrder(defectID, comments);          //* Send one message jsp          req.setAttribute("appMessage", "Order Registered");       } catch (DefectNotFoundException dnfe) {          req.setAttribute("appMessage", dnfe.getMessage());       } catch (Exception e) {          e.printStackTrace(System.out);          req.setAttribute("errorMessage", e.getMessage());       }    } }

In the actionPerformed method, you will receive the event as an object. This object has one method to get the action. The input form sends this action name for portlet. When the technician fills the form and clicks the Submit button, the HTML sends one action (save) and starts the process.

This method will get the data from the request and will call one singleton Service Locator. This component centralizes distributed service object lookups and provides a centralized point of control. This class will return one EJBHome class. After that, the portlet will get one remote reference to start to call the business methods. If the business methods have an exception, the component will get the exception and write one message in the request.

JavaServer Pages for portlets

The next step in development is to create the component to show the data coming from the portlet class. The portal aggregator calls the portlet to render the data and the portlet responds with the stream of the response object.

The job to implement the interface becomes more difficult when the interface becomes more complex. It is necessary that one method for a portlet delegate rendering to another entity; the JSP is the entity which commonly does this job.

The WebSphere Portal Server has a portlet API to provide the class to support the use of JSP components in order to render portlet markup. Refer to the JSP code shown in Example 8-3.

Example 8-3: JSP interface code for the user type defect

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %> <jsp:useBean id="userID" class="java.lang.String" scope="request"/> <form name="<portletAPI:encodeNamespace value='frmMakeOrderJsp'/>" method="post" action="<portletAPI:createURI><portletAPI:URIAction name='save'/> </portletAPI:createURI>"> Technician ID:     <%= userID %> <BR> Select the Defect: <INPUT size="20" type="text" name="txtDefectID"><BR> Comments:          <TEXTAREA rows="2" cols="20" name="txtComments"></TEXTAREA><BR> <INPUT type="submit" name="ok" value="OK"> <INPUT type="reset" name="Clear" value="Clear"></P> </FORM>

In this code, the JSP receives one JavaBean that was created by the portlet. The portlet places the JavaBean in the portlet request scope. In this code, the name of the bean is userID.

The portlet call the portlet context method include() to invoke the JSP. You can see this call in Example 8-1 on page 169.

The JSP component uses the <jsp:useBean> tag to establish the reference to the bean and extract the data from the request. You can write the value from the bean in a traditional JSP way. This is a basic step necessary to get the data from portlet.

Another consideration is how to send the data to the portlet and call an action. This JSP has a custom tag know as portletAPI:URIAction name='save'. In this tag, you can define the name of the action. The URIAction works only if you define another tag, CreateURI.

The CreateURI is used to create an URI that points to the current portlet with the given parameters. You can pass a parameter or action in the URI by including URIParameter or URIAction between the createURI start and end tags.

The URIAction is used to add a default action to the URI of the createURI and createReturnURI tags. The portlet must provide an action listener to handle the event.

This action will activate and you can code one method to execute the operations compatible with this action.

Deployment descriptor for the portlet

The last step is to create the deployment descriptor file.

A collection of related portlets make up a portlet application and are packaged together in the Web archive (WAR) file. Portlets packaged together in a single .war file may share images, stylesheets, JSP components, and other kinds of resources. A .war file is a specially structured JAR file that includes a special XML descriptor called the Web application deployment descriptor .

The file name for the XML descriptor file is web.xml. This file is always stored in the WEB-INF directory of the WAR file.

Example 8-4: The web.xml file

 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd"> <web-app id="WebApp">     <display-name>PervasivePortal</display-name>     <servlet id="Servlet_1">         <servlet-name>PortSearchKm</servlet-name>         <display-name>PortSearchKm</display-name>         <servlet-class>com.ibm.itso.pervasive.PortSearchKm</servlet-class>         <init-param>             <param-name>listener.action</param-name>             <param-value>com.ibm.itso.pervasive.PortSearchKm</param-value>         </init-param>     </servlet>     <servlet-mapping id="ServletMapping_1">         <servlet-name>PortSearchKm</servlet-name>         <url-pattern>/PortSearchKm/*</url-pattern>     </servlet-mapping> </web-app>

In this example, we have the reference and mapping for only one portlet. If you have more portlets, you will have more entries. In a sample application, we have the complete version for the project. The portlet here is PortSearchKM (see this on the servlet-name tag) and the class name is com.ibm.itso.pervasive.PortSearchKm (see this on the servlet-class tag).

The Web application descriptor describes the portlets in the portlet application .war file to the application server as servlets. Each portlet is defined as a servlet, and the portlet application is synonymous with the definition of the Web application.

One important point is that when you have the action, you should define the listener action. You can have one class for the portlet and another class to receive the actions. In this case, the two classes are the same but if you want to change the action, you should change the class in the param-value class.

Look at the tags below:

 <param-name>listener.action</param-name>    <param-value>com.ibm.itso.pervasive.PortSearchKm</param-value>

In addition to the web.xml file in the portlet application's .war file, a .war file that contains a portlet application and associated portlets must also contain a portlet application descriptor. The portlet application descriptor file name is portlet.xml, and this file is also always stored in the WEB-INF directory of the .war file.

This document describes the portlet application, each portlet in the application and each portlet's title and capabilities. Refer to Example 8-5.

Example 8-5: The portlet.xml file

 <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE portlet-app-def PUBLIC "-//IBM//DTD Portlet Application 1.1//EN" "portlet_1.1.dtd"> <portlet-app-def>    <portlet-app uid="DCE:f3f5b310-f757-1201-0000-005d15cf6940:1" major-version="1" minor-version="0">    <portlet-app-name>PervasivePortal application</portlet-app-name>    <portlet id="Portlet_1" href="WEB-INF/web.xml#Servlet_1" major-version="1" minor-version="0">       <portlet-name>Search KM</portlet-name>       <cache>          <expires>0</expires>          <shared>NO</shared>       </cache>       <allows>         <maximized/>         <minimized/>       </allows>       <supports>          <markup name="html">              <view/>          </markup>       </supports>    </portlet> </portlet-app> <concrete-portlet-app uid="DCE:f3f5b310-f757-1201-0000-005d15cf6940:1.1"> <concrete-portlet href="#Portlet_1">     <portlet-name>ITSO Search Knowledge Managment portlet</portlet-name>     <default-locale>en</default-locale>     <language locale="en">         <title>Search Knowledge Management</title>         <title-short></title-short>         <description></description>         <keywords></keywords>     </language> </concrete-portlet> </concrete-portlet-app> </portlet-app-def>

In this file, you can find the link between the portlet (portlet.xml) and the servlet (web.xml). In this file, we can find a lot of interesting information such as whether the portlet can be maximized, or the name that the user can see to identify this portlet on the list of portlets, or what kind of device this portlet can be used.

The information about the device can be set in the markup tag.

Example 8-6: Tags to set portlet to HTML, WML and cHTML devices

 <supports>   <markup name="html">     <view/>   </markup>   <markup name="wml">     <view/>   </markup>   <markup name="chtml">     <view/>   </markup> </supports>

In Portal Administration, this information will be available when you install the portlet application.

Generating the portal deployable code

This step is really easy if you have some tool such as WebSphere Studio Application Developer with the Portal Toolkit.

The XML files, portlets and JSP files are inside the \WEB-INF folder. The portlet follows the same conventions as a J2EE specification. You should create one .war file to deploy portlets inside the WebSphere Portal Server.

Select Export WAR in WebSphere Studio Application Developer. You should see a window as shown in Figure 8-7 on page 176.

Figure 8-7: Generating the portlet .war file

You can choose the place that you want to generate the deploy file. For example, this could be C:\temp\PervasivePortal.war.

Now your portlet has finished delivering to WebSphere Portal Server. The Portal Administrator should import this in Portal Page Administration to finalize the process.

For more information about deploying the sample application in a runtime environment, refer to Chapter 12, "Technical scenario" on page 271.

8.3.2 User registry

The application exhibits a different behavior if the user logged in is a technician or a customer. The information about these two actors is stored in an LDAP directory. The product responsible for managing this data is IBM SecureWay Directory.

IBM SecureWay Directory is a Lightweight Directory Access Protocol (LDAP) directory that runs as a stand-alone daemon. It is based on a client/server model that provides client access to an LDAP server. IBM SecureWay Directory provides an easy way to maintain directory information in a central location for storage, updating, retrieval, and exchange.

IBM SecureWay Directory provides Secure Sockets Layer (SSL) V3 support, both for the directory server and client. SSL provides encryption of data and authentication using X.509v3 public-key certificates. The directory may be configured to run with or without SSL support. IBM SecureWay Directory also supports LDAP referrals, allowing directory operations to be redirected to another LDAP Directory server. Replication of the LDAP Directory is supported and allows for additional copies of the directory to be available for directory read operations, which increases performance and reliability when accessing directory information.

The suggested mapping for the structure to use the LDAP can be seen in Table 8-2 below.

Table 8-2: Structure of LDAP
Business Name	Class	Attribute
User Identification	inetOrgPerson	uid
Password	person	userPassword
First Name	inetOrgPerson	givenName
Last Name	person	sn

The next step is for the users to populate this structure. Of course, you can create your own users, but if you want to see an example, take a look at Example 8-7.

Example 8-7: Example for Technician

 dn: uid=tech1, cn=users, dc=itso, dc=ral, dc=ibm, dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: tech1 Technician givenName: tech1 sn: Technician uid: tech1 userPassword: password

You can customize this LDAP structure to save the information about the employee (Technician). We have one more example for another kind of user, the Customer. In this case, both structures are the same but in real conditions, the intranet and Internet profiles would be completely different.

Example 8-8: Example for Customer

 dn: uid=client1, cn=users, dc=itso, dc=ral, dc=ibm, dc=com objectclass: top objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: client1 Customer givenName: client1 sn: Customer uid: client1 userPassword: password

Now we have the users for the portal, but the next step is to separate the Technician and Customer. We can separate using groups in LDAP. We have been using the default definition group that is configured when you installed IBM SecureWay. This group has the information about the users who work with this application.

Example 8-9: Example for a group of users

 dn: cn=technician, cn=groups, dc=itso, dc=ral, dc=ibm, dc=com objectclass: groupOfUniqueNames description: Technician from ITSO Help Desk cn: technician uniquemember: uid:tech1, cn=users, dc=itso, dc=ral, dc=ibm, dc=com uniquemember: uid:tech2, cn=users, dc=itso, dc=ral, dc=ibm, dc=com uniquemember: uid:tech3, cn=users, dc=itso, dc=ral, dc=ibm, dc=com

If you want to test all scenarios with this application, you should have the Customer and Technician users as shown in Table 8-3.

Table 8-3: List of users to use the application
User Identification	Profile
client1	Customer
client2	Customer
tech1	Technician
tech2	Technician

8.3.3 Using Transcoding Technology

The Transcoding Technology comes as a feature of WebSphere Portal in WebSphere Everyplace Access.

If you log on as an administrator to WebSphere Portal on a WebSphere Everyplace Access installed machine, select the Portal Administration option from the menu, then select the Portal Settings tab and Global settings under it.

At the bottom of the page, you will find a check box, by which you can enable transcoding for the portlet content, as shown in Figure 8-8.

Figure 8-8: Enabling Transcoding Technology

This is a global setting for WebSphere Portal, and it is set to be enabled by default.

If you want to transcode your portlets, you have to configure the Transcoding Technology for the portlet. In order to do so, you have to select the Portlets tab, then Manage Portlets under it.

Select your portlet from the list of portlets, then select the Modify Parameters link. For example, select Welcome Portlet from the list.

A page will appear with the details and settings for the portlet; add a new parameter, type in FilterChain for the parameter, and Transcoding as the value, then click Add .

You should get the resulting window as shown in Figure 8-9.

Figure 8-9: Configuring Transcoding for a portlet

Once you have transcoding enabled using the FilterChain in WebSphere, you can access the portal application using a WAP phone or, in our case, an emulator. In this case, we accessed the http://< servername >/wps//portal site; first, we got the list of items from the Welcome portlet, then we looked at the World time to get the result as shown in Figure 8-10 on page 181.

Figure 8-10: Portlet results on a WAP phone

In the sample application, the Transcoding Technology enables the users to access Web content on pervasive devices, for example a wireless laptop, PDA, smartphone, interactive voice response system.