Portlet Development Guide
Working with the Portlet API 1.1
Java Server Pages in Portlets
Portlet Design Guidelines
Security and Single Sign On
First Edition
April 2, 2002
Authors:
Stephan Hesmer
Peter Fischer
Ted Buckner
Ingo Schuster
Pervasive Computing Development
1. Abstract .............................................................................................................................. 5
2. Overview............................................................................................................................. 6
2.1. Portlets and the Servlet API.................................................................................... 6
2.2. Portlet deployment descriptor................................................................................. 8
2.3. Portlet Concepts ....................................................................................................... 9
2.4. Portlet Applications................................................................................................ 10
2.4.1. Concrete Portlet Application............................................................................ 11
2.5. Portlet modes .......................................................................................................... 11
2.6. Portlet states............................................................................................................ 12
2.7. Examples in this document - the Bookmark Portlet ........................................... 12
3. Portlet API - Basic elements ........................................................................................... 14
3.1. Portlet ...................................................................................................................... 14
3.1.1. getLastModified()............................................................................................. 15
3.1.2. PortletAdapter .................................................................................................. 15
3.1.3. Example............................................................................................................ 15
3.2. Core Objects ........................................................................................................... 17
3.2.1. PortletRequest .................................................................................................. 17
3.2.2. PortletResponse................................................................................................ 19
3.2.3. PortletSession ................................................................................................... 20
3.2.4. Example............................................................................................................ 20
3.3. Listeners .................................................................................................................. 22
3.3.1. PortletSessionListener...................................................................................... 22
3.3.2. PortletPageListener .......................................................................................... 23
3.3.3. PortletTitleListener........................................................................................... 23
3.3.4. Complete Lifecycle .......................................................................................... 24
3.3.5. Example............................................................................................................ 24
3.4. Configuration Objects............................................................................................ 26
3.4.1. PortletConfig .................................................................................................... 26
3.4.2. PortletSettings .................................................................................................. 27
3.4.3. PortletApplicationSettings ............................................................................... 27
3.4.4. PortletData........................................................................................................ 28
3.4.5. Example............................................................................................................ 28
3.5. Miscellaneous Objects............................................................................................ 30
3.5.1. PortletContext................................................................................................... 30
3.5.2. PortletWindow ................................................................................................. 32
3.5.3. User .................................................................................................................. 32
3.5.4. Example............................................................................................................ 32
3.6. The scope of the portlet objects............................................................................. 34
4. Java Server Pages............................................................................................................ 35
4.1. Portlet API Tags ..................................................................................................... 35
4.1.1. if ....................................................................................................................... 35
4.1.2. log..................................................................................................................... 36
2
4.1.3. text.................................................................................................................... 36
4.1.4. dataLoop........................................................................................................... 36
4.1.5. dataAttribute..................................................................................................... 37
4.1.6. settingsLoop ..................................................................................................... 37
4.1.7. settingsAttribute ............................................................................................... 38
4.1.8. CreateReturnURI.............................................................................................. 38
4.1.9. createURI ......................................................................................................... 39
4.1.10. URIParameter................................................................................................... 39
4.1.11. URIAction ........................................................................................................ 39
4.1.12. encodeNamespace ............................................................................................ 40
4.1.13. init..................................................................................................................... 40
4.1.14. encodeURI (deprecated)................................................................................... 41
4.2. The example using a JSP ....................................................................................... 41
4.3. Reserved Parameter Names .................................................................................. 43
5. Portlet API - Advanced elements .................................................................................... 44
5.1. Portlet events .......................................................................................................... 44
5.1.1. Action events.................................................................................................... 44
5.1.2. Window events................................................................................................. 46
5.1.3. Message events................................................................................................. 46
5.2. PortletSettingsAttributesListener......................................................................... 47
5.3. PortletApplicationSettingsAttributesListener..................................................... 47
5.4. Portlet Caching....................................................................................................... 47
5.5. Portlet Services ....................................................................................................... 48
5.5.1. Writing a portlet service................................................................................... 48
5.5.2. ContentAccessService...................................................................................... 51
6. Deployment Descriptors .................................................................................................. 52
6.1. Web application deployment descriptor .............................................................. 52
6.2. Portlet deployment descriptor............................................................................... 52
6.3. Relationship between the deployment descriptors.............................................. 57
6.4. Guidelines for portlet application UIDs ............................................................... 57
7. Portlet development issues .............................................................................................. 59
7.1. Compiling and testing portlets .............................................................................. 59
7.1.1. Setting up a portlet development environment ................................................ 59
7.1.2. Compiling Java source ..................................................................................... 59
7.1.3. Creating the deployment descriptors................................................................ 60
7.1.4. Setting up the WAR file directory structure..................................................... 60
7.2. Portlet creation guidelines ..................................................................................... 62
7.2.1. No instance and class variables........................................................................ 62
7.2.2. Storing data ...................................................................................................... 62
7.2.3. Performance issues........................................................................................... 63
7.2.4. Guidelines for markup...................................................................................... 64
7.3. Namespaces/Javascript .......................................................................................... 64
7.4. Multi-markup support........................................................................................... 65
3
7.5. Multi-language support ......................................................................................... 65
8. Extended WPS PortletServices ....................................................................................... 66
8.1. Persistent Backend Connections ........................................................................... 66
8.1.1. Persistent Backend Connections concept......................................................... 66
8.1.2. Using the PersistentConnection object............................................................. 66
8.1.3. Persistent Backend Connections Service in a cluster....................................... 67
8.1.4. Usage example ................................................................................................. 67
8.2. Credential Vault ..................................................................................................... 68
8.2.1. Credential Vault organization .......................................................................... 68
8.2.2. Vault Segments ................................................................................................ 68
8.2.3. Credential slots................................................................................................. 69
8.2.4. Credentials objects ........................................................................................... 69
8.2.5. Credential Vault usage scenarios ..................................................................... 71
8.2.6. Methods of the CredentialVaultService ........................................................... 73
8.2.7. Programming Example..................................................................................... 77
8.2.8. Using JAAS to retrieve the user’s credentials.................................................. 78
9. References........................................................................................................................ 83
Figures
Figure 1: View of a portlet on the application server and portal server ...................... 8
Figure 2: Manifestations of a portlet in the portal server............................................ 9
Figure 3: Portlet application ..................................................................................... 11
Figure 4: Use of servlet ID in the portlet deployment descriptor .............................. 57
Figure 5: Vault segments and vault implementations .............................................. 69
4
1. Abstract
The purpose of this document is to show how to develop a portlet using the Portlet
API, introducing concepts of the Portlet API along the way. Elements of the Portlet
API are described with the help of an example that progresses from a simple portlet
with no output to a complex portlet application with more advanced features. Portlet
development for the WebSphere Portal environment is also described.
5
