Portals

Portals are Web sites that are a starting point to information and applications on the Internet or an intranet. To aggregate and display diverse content dynamically, a portal server must provide a framework that breaks those content-providing portal components into pluggable portlets, as shown in Figure 1 below. Each portlet is responsible for providing specific information, and must perform tasks like accessing content (for example, from a Web site, database, or a Web service), and transforming the content so it can be efficiently rendered to the client. IBM WebSphere Portal for Multiplatforms Version 4.x provides a framework of services to make writing and managing portlets as easy as possible.

Back to top

Portlets

From a user's perspective, a portlet is a small window in the portal page that provides a specific service or information, such as a calendar or newsfeed. From an application development perspective, portlets are pluggable modules that are designed to run inside the portlet container of IBM WebSphere Portal Version 4.x.

Portlets can use the portal infrastructure to access user profile information, participate in window and action events, communicate with other portlets, access remote content, lookup credentials, and store persistent data. The Portlet API provides standard interfaces for these functions.

Back to top

Portlets and servlets

All portlets running on IBM WebSphere Portal Version 4.x inherit from the Abstract Portlet class, which is the central abstraction of the Portlet API. Portlets are a special type of servlet, with properties that let them easily plug into and run in the portal server. Portlets have various other features, and also some natural restrictions. Unlike servlets, portlets cannot send redirects or errors to browsers directly, forward requests, or write arbitrary markup to the output stream.

Generally, portlets are administered more dynamically than servlets. The following updates can be applied without having to restart the portal server:

• Portlet applications consisting of several portlets can be installed and removed dynamically using the portal administration user interface.
• The settings of a portlet can be changed on the fly by an administrator.

The portlet container relies on the J2EE architecture implemented by IBM WebSphere Application Server. This way, the portlet developer benefits in several ways:

• The Portlet API leverages the well-known Servlet API, extending it where necessary.
• Developers who know the Servlet API can instantly write portlets.
• Developers can use existing tools to develop portlets and JavaServer Pages (JSP) components.
• Portlets are part of the J2EE model, thus offering each developer a variety of options to combine J2EE compliant technologies.
• Developers can reuse simple existing servlets or JSP components with little or no effort.

Portlets are packaged in WAR files similar to J2EE Web applications and are deployed like servlets. Like other servlets, a portlet is defined to the application server using the Web application deployment descriptor (web.xml). This file defines the portlet's class file, the servlet mapping, and read-only initialization parameters.

In addition to the servlet descriptor, portlets must also provide a portlet deployment descriptor (portlet.xml) to define the portlet's capabilities to the portal server. This information includes configuration parameters specific to a particular portlet or portlet application, and general information that all portlets provide, such as the type of markup the portlet supports. The portal server uses this information to provide services for the portlet. For example, if a portlet registers its support for help and edit mode in the portlet deployment descriptor, the portal server will render icons to let the user access the portlet's help and edit pages.

Back to top

Portlet applications

Portlet applications provide the means to package a group of related portlets that share the same context. The context contains all resources, such as images, properties files, and classes. All portlets must be packaged as part of a portlet application.

Portlet applications provide no code on their own, but form a logical group of portlets. Besides this more logical gain, portlets of the same portlet application share their session and can also exchange messages.

Back to top

Web services

Web services let business applications communicate and cooperate over the Internet. Web services imply a paradigm shift compared to the way the Internet used to work. While traditional applications interacting with services in the Internet know those services deductively and need to be pointed to them manually, Web services let applications find Web services in a standardized directory structure and bind to the services with minimal human interaction. See Figure 2 for an illustration of the Web services concept.

Web services allow objects to be distributed across Web sites where clients can access them with the Internet. Global service registries are used to promote and discover distributed services. Consumers that need a particular kind of service can query the global service registry to find services that suit their needs. They can select one of the services, bind to that service, and use it for a certain period of time. Because service discovery and selection, in some cases, can be performed without human interaction, services can be switched very quickly. Automated service discovery also allows establishment of very robust networks of services. If there are multiple Web services that provide identical functions, consumers can easily switch to a back-up system when the currently used service fails.

The most important standards in this area are:

• Universal Description, Discovery, and Integration (UDDI) for registration and discovery of Web services
• Simple Object Access Protocol (SOAP) for communication between Web services
• The associated Web Services Description Language (WSDL) for formal description of Web service interfaces and bindings.

Back to top

Portlets and Web services

From a portal perspective, we can differentiate between two different kinds of Web services: the "traditional" data-oriented Web services and presentation-oriented, user-facing, interactive Web services.

Data-oriented Web services receive SOAP requests and return data objects encoded in XML documents in the SOAP response. The signatures of their SOAP operations, and the structure and semantics of the returned data, are service type-specific. It is the responsibility of the service consumer to process the received data in a service-specific manner and generate any required presentation, as shown in Figure 3. While this is a good approach for applications that require specific data and know how to consume and process this data, it is not appropriate for portals that need to quickly integrate content and applications from various different sources.

User-facing Web services include presentation as a part of the service itself. They don't just provide raw data to be processed and turned into a presentation by the consumer, but instead they themselves can produce markup fragments that can easily be aggregated by portals. User-facing Web services may also include user interaction. They are well suited for integration and use in portals, because they can be aggregated by portals and participate in user action processing in a generic way so that no service-specific presentation code is required on the consumer's side.

Data-oriented Web services used by portlets

Back to top

Example scenario

Now that we're done with all that theory, we'll explain how to develop portlets that can use data oriented Web services. The following sections use sample portlets step by step, and explain the corresponding concepts when necessary. In our example scenario, a portal provider wants to add a new feature to his portal -- a directory portlet that lets the user obtain information about an employee, such as the e-mail address or phone number. In our case, the portlet will use a data-oriented Web service to get the appropriate information. Figure 5 shows the scenario with a bit of detail.

Back to top

Developing the portlet application

The recommended design for programming portlets is the Model-View-Controller (MVC) pattern. Figure 6 below shows how this pattern is adjusted to our example. The portlet acts as the controller, the JSP components as the view, and the Web service provides the data of the model. When the first request to the portlet arrives, it is dispatched to the View.jsp, which contains a form that lets the user define the name of the person for which the directory should be queried. This view is rendered and the markup is sent back to the client. Users enter the name and when they click the search button, a second request is sent to the portal. This time, the portlet invokes the Web service proxy, passing the parameter values specified in the form. The proxy returns a data bean that is passed to the Result.jsp, which obtains the appropriate parameters from the bean and includes their values into the generated markup. This means that our portlet can be in two different states: in one state you can enter your search criteria, and in the other state the result is being displayed.

In contrast to the standard servlet scenario, an incoming request containing an action leads to two invocations of the portlet. At first, the actionPerformed method is invoked and thereafter the service method. To maintain the logical state of the portlet over subsequent requests to the portal, the following steps are performed:

• The portlet obtains a return URI from the portal framework that points back to the portlet and attaches an action to it.
• When the appropriate request arrives, this action is passed to the actionPerformed method of the portlet. All required operations can be performed and the state of the portlet is adjusted depending on the results. Then, the state and additional data is saved to the request or the session.
• This state is then being used during the service method to dispatch to the appropriate JSP component and to render the output.

Now that we've introduced the example scenario, and described the recommended pattern to program portlets, it's time to implement the example application. This task could be achieved with the help of different tools, but we decided to use IBM WebSphere Studio Application Developer (Application Developer), which integrates all of the required functions in one tool.

Back to top

Implementing portlets

This section describes how to implement portlets using Application Developer and the Portal Development Toolkit. Usually the development of portlets includes at least the following steps:

1. Implementing the portlet's class code and JSP components.
2. Packaging the resources to a WAR file, and creating of web.xml and portlet.xml descriptor files.
3. Deploying and testing the portlet application on the portal server.

Application Developer supports you in the first step, and in conjunction with the Portal Development Toolkit, it significantly reduces the effort to package the application and to create the needed XML descriptor files. The toolkit also provides the ability to automatically deploy the portlet application on a portal system, and to remotely test and debug it. However, in this article we focus on the description of the first two steps. See the Toolkit's documentation in Resources for more information.

The first step is the creation of a new portlet application, which can be done as follows:

1. Launch the portlet wizard by selecting New>Other>Portlet Development>Portlet Application Project.
2. Define the name of the application. Select CSS file only if you want to create a cascading stylesheet (in this case, we don't).
3. In the next panel,a number of default portlets are displayed. For a detailed description of the single portlets see the documentation. For our simple example we choose the Basic Portlet. Click Next.
4. This panel lets you edit the name of the portlet application and the portlet, as well as the class name of the portlet. Enter your preferred settings and click Finish to create the portlet application.

That's it. Now we have a ready-to-use portlet application, including the required XML descriptor files. If you want to edit these files, Application Developer provides a convenient wizard to do so.

		
<?xml version="1.0" encoding="UTF-8"?>
<definitions name="DirectoryAccessorService"
    targetNamespace="http://localhost:8080/WebService/wsdl/
       DirectoryAccessor-service.wsdl"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    
xmlns:binding="http://www.directoryaccessor.com/definitions/
       DirectoryAccessorRemoteInterface"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:tns="http://localhost:8080/WebService/wsdl/
       DirectoryAccessor-service.wsdl">
    <import
        location="http://localhost:8080/WebService/wsdl/
           DirectoryAccessor-binding.wsdl" 
namespace="http://www.directoryaccessor.com/definitions/
           DirectoryAccessorRemoteInterface"/>
    <service name="DirectoryAccessorService">
        <port binding="binding:DirectoryAccessorBinding" 
                name="DirectoryAccessorPort">
            <soap:address location="http://localhost:8080/WebService/
                servlet/rpcrouter"/>
        </port>
    </service>
</definitions>
       

Next, we need a proxy that accesses the Web service described earlier. The WSDL description of the service we want to use is shown in the example above. See Developing a Web service for a description of how such a Web service can be created using Application Developer.

Follow these steps to include a Web services client into the project:

1. Launch the Web service wizard by selecting New>Other>Web Service>Web Service Client.
2. Choose your portlet application project, making sure that only the Generate a proxy field is selected.
3. In the next panel, define the WSDL file location or an appropriate URL under which a WSDL definition file can be accessed. If you use the example Web service implementation, click Browse and select the WSDL description file located in the Web services project. Click Finish.

The following packages will be included in your project:

portlet

Created by the portlet development toolkit, and includes the WebServicePortlet and the WebServicePortletBean classes. The latter one is of no use and can be deleted.

mappings

Created by the Web service wizard, and contains the Sample_WebService_RecordBean.class, which represents the data bean returned by the Web service.

proxy.soap

Package that includes the proxy class.

The last tasks are connecting the single components and creating an additional JSP component.

Editing the WebServicePortlet class

To allow action handling, we have to extend the WebServicePortlet class whereby the class must implement the ActionListener interface (found in the package org.apache.jetspeed.portlet.event), and provide the actionPerformed method. This method is filled with the code that determines the type of the incoming action. If its name is "search," the Web services proxy is invoked, the returned bean is added as an attribute to the request, and the state attribute is set to "Display Results," as shown in the code sample below.

		
public void actionPerformed(ActionEvent event) throws PortletException {
	
     PortletRequest request=event.getRequest();        
     DefaultPortletAction action = (DefaultPortletAction) event.getAction();
          
     if (action.getName().equals("search")) 
     {
          	
      	String name=request.getParameter("name");
        Sample_webservice_RecordBeanContentType recordBean=null;
 	DirectoryAccessorProxy proxy=new DirectoryAccessorProxy();
 	try
 	{
 	  recordBean=proxy.getEmployeeRecord(name);
 	}
 	catch(Exception e) {throw new PortletException(e.getMessage());}
 	if(recordBean==null) 
 	   recordBean= new Sample_webservice_RecordBeanContentType();
 		  
        request.setAttribute("Result", recordBean);
 	request.setAttribute("State","DisplayResult");
 		    
     }
}

The doView method must be changed in order to dispatch to one of the two JSP components, depending on the value of the State attribute.

		
public void doView(PortletRequest request, PortletResponse response) 
    throws PortletException, IOException {
       String jspName="/jsp/View.jsp";
       String state=(String)request.getAttribute("State");
       if((state!=null) && (state.equals("DisplayResult")))
 	 jspName="/jsp/DisplayResult.jsp";
 		
       // Invoke the JSP to render   

       getPortletConfig().getContext().include(jspName, request, response);
}
       

Creating JSP pages

The Web page designer in Application Developer helps you easily create and execute JSP pages. It is up to you to design these pages. However, make sure you use the following fragments:

1. In each JSP page, add the following tag lib:

   <%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>

   
   
2. In the first JSP page, set the action field of the name form to:

   <portletAPI:createURI><portletAPI:URIAction name="search" /> </portletAPI:createURI>

   
   
3. In the DisplayResult JSP page, add:

   <%@ page import="mappings.Samples_webservice_RecordBeanContentType" %> <jsp:useBean id="Result" class="Samples_webservice_RecordBeanContentType" type="Samples_webservice_RecordBeanContentType" scope="request"/>

   
   

The View.jsp in our example is as follows:

		
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<%@ page contentType="text/html"%>
  
<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>
<HEAD>
<META name="GENERATOR" content="IBM WebSphere Studio">
</HEAD>
<P><BR>
</P>
<FORM method='POST' action='<portletAPI:createURI>
   <portletAPI:URIAction name="search" 
/></portletAPI:createURI>'>Enter the name of the employee:<BR>
<BR>
Name: <INPUT name='name'><BR>
<br>
     
      <INPUT type='submit' name='searchButton' value='Search'><br>
</FORM>
       

DisplayResult.jsp in our example is as follows:

		

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<%@ page contentType="text/html"%>
<HEAD>
<META name="GENERATOR" content="IBM WebSphere Studio">
</HEAD>
<P><BR>
</P>
<%@ page import="mappings.Sample_webservice_RecordBeanContentType" %>
<jsp:useBean id="Result" class="Sample_webservice_RecordBeanContentType" 
    scope="request"/>

<% if (Result.getName()!=null) { %>



<TABLE width=590 border=0>
  
        <TBODY>
        <TR>
          <TD align=middle bgColor=#b0c4de colSpan=2><B>DIRECTORY 
RECORD</B></TD> <TR>

        <TR bgColor=#cccccc>
          <TD>Name:</TD>
          <TD><B> <%= Result.getName()%> </B></TD></TR>
         
          // code displaying the other attributes is omitted here.
        
    </TBODY>
</TABLE>

<% } else { %>

  No Entry was found in the directory for the given name.

<%  } %>

Back to top

Developing a Web service

To give you the means to test the portlet application above, this section briefly describes the implementation of a Web service using Application Developer.

As when developing portlets, you can use different tools. We used Application Developer because it integrates every single tool you need to create Web services. You just have to implement the appropriate classes, and the service descriptors are then automatically created and the service is deployed on Application Developer's integrated WebSphere Application Server and ready to use. To begin:

1. Create a new Web project.
2. Implement the classes for the service.
3. Right-click on the project, choose New and then Other. The New panel appears. Select the Web services folder and click Web Service.
4. The Web Service panel lets you specify the following parameters:
   • Web Service Type: Choose Java Bean Web Service
   • Web Project: Lets you specify in which project the service should be created. If you followed the steps above, this field is automatically set.
   • Wizard defaults: Make sure that Start Web Service in Web Project is selected. The "Launch the UDDI Browser to publish this Web Service" option lets you publish the service into a UDDI registry from within Application Developer.
5. The next panel prompts you for the class or file that the Web service should be created for. The subsequent panels let you edit type mappings and bindings. For this example, use the default settings and click Finish.

Application Developer will automatically create the Web service and all wsdl description, and will publish the service to the server and start it for you.

We hope this article has shown how easy it can be to integrate data oriented Web services into a portal using IBM's WebSphere Studio Application Developer. The resources below provide great next steps for more information.

Resources

• Visit the IBM WebSphere Portal Server site, which includes the InfoCenter.
  
  
• Look at the Portal Server product documentation library to learn more about portlet development.
  
  
• Download a trial version of WebSphere Studio Application Developer.
  
  
• Download the IBM Portal Toolkit.
  
  
• You can get more information about Web services, as well as demos and downloads, on the developerWorks Web services zone.
  
  
• You'll find information for developers who use WebSphere products on WebSphere Developer Domain.
  
  
• For more information on Universal Description, Discovery and Integration of Web Services, see the UDDI Web site.
  
  
• For details on Simple Object Access Protocol, refer to the SOAP specification.
  
  
• For more on Web Services Description Language, see the WSDL specification.
  
  

About the authors

Juergen Schaeck is a Software Engineer at IBM Boeblingen Lab. Juergen holds a Master's degree from the University of Karlsruhe and currently works in WebSphere Portal Development. He is responsible for Business Process Integration and Dynamic UI Management in WebSphere Portal.

After finishing his studies at the top of the class at Staatliche Studienakademie Sachsen in Dresden, Germany in 1999, Peter Fischer has been working as a Software Engineer for IBM in the development lab in Boeblingen, Germany. He is currently working in WebSphere Portal Development as the technical team lead of the Web Services/Web Services for Remote Portlets (WSRP) team. He is responsible for the architecture and design of the WSRP implementation in WebSphere Portal Version 5 and the Apache Charon project. In his spare time, Peter likes to spend time with his girlfriend, go mountain biking, or work on one of his vintage cars. You can contact Peter at peter.fischer3@de.ibm.com.

Rate this article

Comments

Back to top

Table of contents

• Portals
• Portlets
• Portlets and servlets
• Portlet applications
• Web services
• Portlets and Web services
• Data-oriented Web services used by portlets
• Example scenario
• Developing the portlet application
• Implementing portlets
• Developing a Web service
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: WebSphere Portal Express
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Portal Express