![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
A colleague of mine, who recently started to work with IBM ® WebSphere® Portal (hereafter called Portal), posed the question, "What's the best way to share functionality between portlets?" After a brief discussion to better understand what he was trying to accomplish, I suggested he consider using a portlet service. This, of course, led to further discussion concerning what a portlet service is and how it might be used in a Portal application. Portlet services are a natural extension to portlets and the next logical step in a discussion about designing portal applications. Part 3 of this portlet and UML series discusses how to design and model a sample portlet service, and outlines a portlet that uses this service.
This article continues the discussion in Part 1 and Part 2 of this series. Part 1 discussed how to use UML for modeling portlet designs. Part 2 extended the portlet design model, providing an in-depth discussion on modeling portal applications, and introduced additional topics of modeling portlet services, EJBs, and other coalesced objects within a portal application design.
With portlet services, you can develop common functionality to share between portlets within a portal. Portlets can instantiate these services via dynamic discovery by using a service factory. A service factory is an object designed to create or locate a service. The PortletService interface is available within your portlets via the PortletContext. The getPortletService() method looks up a factory for a given service and returns the result to the portlet. This approach provides the following advantages:
- A single object can encapsulate common logic within an application to be used throughout the portal
- You can separate business logic, helper classes, and access layers from View-Controller layers to provide a better level of abstraction
- A WebSphere portlet can provide a supported approach to sharing common functionality within the Portal framework.
A team can develop portlet services to be used within portal applications. Different vendors or remote teams can also provide portlet services. Since a portlet service consists of an interface and its implementation, along with a design upfront, and the corresponding method stubs, you can use a portlet service to develop a portlet around an incomplete service. Full integration of the entire application can occur at a later point in the development cycle. This article provides a sample portlet service and its implementation. The WebSphere Portal InfoCenter provides additional detailed information and sample code for building a portlet service and associated factories. Other objects, such as JSP Tag Libraries, can also access portlet services.
A portlet service can encapsulate almost anything that can be abstracted within the application layer. Services let developers design an abstraction layer to an LDAP or similar persistent store, or provide a consistent interface to a set of EJBs or domain objects. As mentioned earlier, third-party vendors can use portlet services to open new APIs to external applications, such as a content management or search application. This lets third-party vendors quickly provide simple yet powerful interfaces into their products. Numerous internal portlet services, for example, ContentAccessService and CredentialVaultService, are already available with WebSphere Portal 4.1.
With portlet services, you can provide a supported, well-known, and controlled access point to your methods for portlets, JSP tag libraries, and other objects. Portlet services also let a team develop standard access points between different architectural layers.
In JavaTM terms, a service class refers to a set of functional interfaces that are not stateful and offer thin interfaces. Portal provides an internal mechanism for creating and accessing service classes using factories. Currently, two default factories are packaged and installed with Portal. You can use these factories, which are part of the Java package, org.apache.jetspeed.portletcontainer.service, with your portlets. The factories are:
- PortletServiceDefaultFactory The default factory creates and returns a new instance of your service each time it is called.
- PortletServiceCacheFactory The cache factory returns the same instance of a portlet service each time it is called.
You can develop additional factories according to a specific need. For example, you might want to create a pool of services that can be cached and reused, instead of relying on the default factories that either return the same instance or create a new instance each time it is used. This article does not discuss in-depth how to develop service factories. For details on how to develop a service factory, refer to the complete example in the WebSphere Portal InfoCenter.
In this example, you will create a user management or self-care functionality within Portal. Portal provides a standard set of user management and self-care options. However, for many companies, the requirements of this functionality are far more complicated than what the out-of-the-box portlets can provide. Additionally, you might need to redesign the UI or information architecture so that it blends more easily with other parts of the application.
Figure 1 below shows a simple use case diagram that outlines basic requirements for a set of user management functionality. Besides these requirements, the security architecture for this sample application requires Tivoli® Access Manager as the security manager for the portal. This means that you need to design custom functionality, which can take advantage of the password rules that Tivoli Access Manager provides, along with other security methods that will be needed later.
Figure 1. Use case diagram
Begin by looking at the interface that you will use to define the portlet service. This interface can serve as a contract between the service developer and other team members who are developing portlets or other objects that use the service. Initially, the service will consist of two public methods:
- changePassword(UserObject user) This method lets you change a user's password. This method takes a user object as a parameter. The user object contains all of the information necessary to change the password.
- resetPassword(String userid) This method lets you reset a password that the user has forgotten. This method takes a user ID as a parameter. This information allows the method to lookup a user, reset the password, and then sends the new password to the e-mail on file for that particular user.
The interface is one of several files that create an entire service package. Additional files are needed:
- UserManagement interface The public methods that are accessible to a service consumer.
- UserManagementImpl The implementation of the service interface. This class implements the interface methods and any helper methods that are required.
- PortalUser A user object that is used by the service and other portlets to encapsulate user information.
- PortletServices.properties While this is not actually a file that you need to provide, you do need to edit the file to register your service. Information on this activity is provided below.
Figure 2 displays a visual example of what the service will look like once developed. Besides defining the already mentioned classes and methods, this diagram also includes information about what the other classes might look like. The diagram also includes private methods and user information within the user object:
Figure 2. Service class diagram
Listing 1 (this is also provided in the download ZIP file below) provides the code for creating the portlet service interface. This file, although simple, contains comments so that consumers of the service completely understand how each of the provided methods can be used.
Listing 1. Service interface
/**
* User Management Service Interface
**/
package com.ibm.wps.service.usermanagement.portletservice;
import com.ibm.wps.service.usermanagement.*;
/**
* The UserManagementService interface contains methods
* which allow user management functionality within the
* portal. User profile and password management.
*
* @author Joey Bernal
* @version 1.0
* @since version 0.0
*/
public interface UserManagementService {
/**
* <P>changePassword(PortalUser user)</P>
* <P>Change the users password.</P>
*
* @param PortalUser user
* @return PortalUser
* @exception none
*/
public PortalUser changePassword(PortalUser user);
/**
* <P>resetPassword(PortalUser user)</P>
* <P>Generate a new password and reset the current
* users password to the newly generated one. Also
* send an e-mail to the users e-mail address on file.</P>
*
* @param String userid
* @return boolean
* @exception none
*/
public Boolean resetPassword(String userid);
}
|
Next, you can start to implement the provided interface for the service. Initially, you can provide stubs for the methods, which will let other developers begin to develop immediately against a service. As more functionality is implemented, you can make and distribute updates.
The UserManagementServiceImpl class implements two interfaces: the one you just created, the UserManagementService interface, and the the PortletServiceProvider interface.
Listing 2. Service interface implementation
public class UserManagementServiceImpl implements
UserManagementService, PortletServiceProvider { |
Once the class is declared, private properties within the implementation are used to store Tivoli Access Manager connection information. The strings are initialized with property values necessary to connect to the Tivoli Access Manager host machine.
private static String PDADMIN_ID = "sec_master"; private static String PDADMIN_PWD = "wpsadmin"; private static String PROGRAM = "Portal User Management Service"; private static String PD_URL_LOCATION = "file:///C:/WebSphere/AppServer/java/jre/PdPerm.properties"; private static String PD_HOSTNAME = "wpsdev.ibm.com"; |
The download ZIP file below provides the complete code sample for this implementation (see Listing 2 of the download).
Considering a different approach to testing your portlet services
When using portlet services within Portal, consider the following during development:
When services change and need to be redeployed, you need to restart the portal so that the new service can be reloaded. The following is a simple trick that you can use to test most of the service within a development tool (for example, WebSphere Studio Application Developer, hereafter called Application Developer).
Notice that in Listing 2 above, the private string declarations are initialized with test values. Also, the code listing contains two init methods:
- The init() method that is used by the portlet service
- A class constructor that is commented out
If developing using Application Developer, you can uncomment the constructor header and comment out the init() method. This then lets you run and test the methods within Application Developer by using a test class before deploying to Portal. The test class is a simple throwaway that exercises each method and prints the results. When testing locally with Application Developer, you must also comment out the config.getParam calls that are used to read your service parameters. Using this approach, the service will run successfully because your values are initialized when you create the variables.
Understanding the PortalUser class
The PortalUser class is designed to be a global representation of a user within the portal. While some might consider this to be a lofty goal, this class does provide a convenient place to maintain a set of extended attributes about the user. Several designs approaches exist concerning how this type of object should be created and where it should reside. This is simply one approach. Generally, a portlet would create an instance of this bean and store it in the PortletSession. This lets the portlet maintain information about the user that it needs as interaction occurs.
A different portlet can use the PortalUser object when necessary. You can also cache and share the PortalUser object by extending the service to include proper logic. Depending on the complexity of the PortalUser object, you can extend the service to create instances when necessary, perhaps by using the builder pattern to populate the object from various data sources.
The implementation surrounding the PortalUser is fairly simple. It is a single bean that carries information and messages to different objects around the portal. Listing 3 in the download ZIP file below provides the complete code for implementing the PortalUser class.
You need to complete the following before deploying the portlet service to
Portal. Once the service is complete, you need to be package it into a JAR
file and place it under the
WebSphere\AppServer\lib\app directory, which
will be recognized by Portal. Also, in the
PortletServices.properties file, you must
define a service factory and any parameters that the service requires.
This file is located in the
WebSphere\PortalServer\app\wps.ear\wps.war\WEB-INF\conf
directory.
The properties setup consists of two parts. First, declare the service and its associated factory:
# -------- Setup the User Management Service and declare the necessary factory ------ com.ibm.wps.service.usermanagement.portletservice.UserManagement = com.ibm.wps.service.usermanagement.portletservice.UserManagementImpl com.ibm.wps.service.usermanagement.portletservice.UserManagementImpl.factory = org.apache.jetspeed.portletcontainer.service.PortletServiceCacheFactory |
Next, configure any parameters that the service needs so that the service can be deployed to different portals as necessary:
#-------- User Management Service Parameters -------------- com.ibm.wps.service.usermanagement.portletservice.UserManagementImpl.PD.ADMIN = sec_master com.ibm.wps.service.usermanagement.portletservice.UserManagementImpl.PD.PASSWORD = wpsadmin com.ibm.wps.service.usermanagement.portletservice.UserManagementImpl.PD.PROGRAM = Portal User Management Service com.ibm.wps.service.usermanagement.portletservice.UserManagementImpl.PD.PROPFILE = file:///C:/WebSphere/AppServer/Java/jre/PdPerm.properties com.ibm.wps.service.usermanagement.portletservice.UserManagementImpl.PD.HOSTNAME = wpsdev.ibm.com |
This example uses PortletServiceCacheFactory, one of the default factories available within Portal.
Now that you have designed the portlet service (and, for example, another team is off busily implementing the required functionality), you can start to design the consumer side of the sample, i.e., the portlet. The portlet follows a similar design as discussed in Part 1 and Part 2 of this series. One major difference is that you can now extend the utility class to take advantage of application logic within the service. Figure 3 outlines the class diagram for the portlet. This design uses standard classes for a portlet:
- The ChangePasswordHTMLController class
- The ChangePasswordUtility class
Figure 3 also illustrates how the portlet and service are integrated to provide a layered approach to supplying the required functionality.
Figure 3. Portlet class diagram
Since this is a relatively simple portlet, it requires only a single action handler (ACTION_CHANGE) to call the processPasswordChange() method within the utility class. The processPasswordChange creates a user bean and uses the service to perform the change password function and return a result. You can create a handle to the service by declaring and calling the service factory associated with the service. Because you defined the service to use the PortletServiceCacheFactory, then the portlet service registry will manage the service, and create only one instance of this service and pass out references to this single instance of the service. This is important in a multithreaded environment where many users might be hitting the service.
UserManagementService umService;
umService = (UserManagementService)
PortletServiceRegistryAccess.getPortletService
(com.ibm.wps.service.usermanagement.portletservice.
UserManagementService.class); |
When the service is available within the portlet, you can invoke any required methods as necessary:
newBean = umService.changePassword(bean); |
Listing 4 in the download ZIP file below provides a complete example of the processPasswordChange() method.
Moving beyond simple portlet design, this article moves forward towards building a multitiered application architecture. You can see that WebSphere Portal provides a well-defined, layered approach that lets applications move beyond the presentation layer and yet still take advantage of a framework design. As you familiarize yourself with this example, you will start to think of places in your own design where you can take full advantage of portlet services.
The code listings provided with this article include enough detail to recreate the sample outlined in this article. They also emphasize the user management service itself. There are many ways to implement the portlet as described above, and rather then force the user into a particular approach, you can drop the provided processChangePassword() method into any portlet design as needed. You might also find the provided service valuable as the changePassword() method is fully functional, and is a good example of how you can use Tivoli Access Manager to implement user management functionality.
One point that this article doesn't discuss in detail is that a portlet developer can develop using these portlet services without having to understand the underlying implementation of the service. This means that you can build the above sample using a database implementation for user management functionality, and then later switch to a Tivoli Access Manager type of implementation. This is one of the major benefits to using portlet services.
| Name | Size | Download method |
|---|---|---|
| Download file codelistings.zip | 0.003 MB | FTP |HTTP |
Information about download methods
-
Modeling
WebSphere Portal Portlets with UML -- Part 1
-
Modeling
WebSphere Portal Portlets with UML -- Part 2
-
WebSphere
Portal 4.1 Information Center
Anthony (Joey) Bernal is a Senior I/T Specialist IBM Business Consulting Services Industrial-HCS Practice. You can reach Joey at abernal@us.ibm.com.
Table of contents
Next steps from IBM
Tags
Use the slider bar to see more or fewer tags.
For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.
For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
