specification of the portlet
Post on 30-May-2018
216 Views
Preview:
TRANSCRIPT
-
8/14/2019 Specification of the portlet
1/132
JavaTM Portlet Specification
Version 1.0
Send comments about this document to: jsr-168-comments@jcp.org
5
10
October 7, 2003
Alejandro Abdelnur (alejandro.abdelnur@sun.com)15
Stefan Hepper (sthepper@de.ibm.com)
-
8/14/2019 Specification of the portlet
2/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 2
Java(TM) Portlet Specification ("Specification") Version: 1.0Status: FCS Specification Lead: Sun Microsystems, Inc.("Specification Lead") Release: August 29, 2003
Copyright 2003 Sun Microsystems, Inc. All rights reserved.
NOTICE; LIMITED LICENSE GRANTS5
Specification Lead hereby grants you a fully-paid, non-exclusive,non-transferable, worldwide, limited license (without the rightto sublicense), under the Specification Lead's applicableintellectual property rights to view, download, use and reproducethe Specification only for the purpose of internal evaluation,10which shall be understood to include developing applicationsintended to run on an implementation of the Specificationprovided that such applications do not themselves implement anyportion(s) of the Specification.
Specification Lead also grants you a perpetual, non-exclusive,15worldwide, fully paid-up, royalty free, limited license (withoutthe right to sublicense) under any applicable copyrights orpatent rights it may have in the Specification to create and/ordistribute an Independent Implementation of the Specificationthat: (i) fully implements the Spec(s) including all its required20interfaces and functionality; (ii) does not modify, subset,superset or otherwise extend the Licensor Name Space, or includeany public or protected packages, classes, Java interfaces,fields or methods within the Licensor Name Space other than thoserequired/authorized by the Specification or Specifications being25implemented; and (iii) passes the TCK (including satisfying therequirements of the applicable TCK Users Guide) for suchSpecification. The foregoing license is expressly conditioned onyour not acting outside its scope. No license is grantedhereunder for any other purpose.30
You need not include limitations (i)-(iii) from the previousparagraph or any other particular "pass through" requirements inany license You grant concerning the use of your IndependentImplementation or products derived from it. However, except withrespect to implementations of the Specification (and products35derived from them) that satisfy limitations (i)-(iii) from theprevious paragraph, You may neither: (a) grant or otherwise passthrough to your licensees any licenses under Specification Lead'sapplicable intellectual property rights; nor (b) authorize yourlicensees to make any claims concerning their implementation's40compliance with the Spec in question.
For the purposes of this Agreement: "Independent Implementation"shall mean an implementation of the Specification that neitherderives from any of Specification Lead's source code or binarycode materials nor, except with an appropriate and separate45license from Specification Lead, includes any of SpecificationLead's source code or binary code materials; and "Licensor NameSpace" shall mean the public class or interface declarationswhose names begin with "java", "javax", "com.sun" or theirequivalents in any subsequent naming convention adopted by50Specification Lead through the Java Community Process, or anyrecognized successors or replacements thereof.
-
8/14/2019 Specification of the portlet
3/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 3
This Agreement will terminate immediately without notice fromSpecification Lead if you fail to comply with any materialprovision of or act outside the scope of the licenses grantedabove.
TRADEMARKS5
No right, title, or interest in or to any trademarks, servicemarks, or trade names of Sun or Sun's licensors, theSpecification Lead or the Specification Lead's licensors isgranted hereunder. Sun, Sun Microsystems, the Sun logo, Java,and the Java Coffee Cup logo are trademarks or registered10trademarks of Sun Microsystems, Inc. in the U.S. and othercountries.
DISCLAIMER OF WARRANTIES
THE SPECIFICATION IS PROVIDED "ASIS". Specification Lead MAKESNO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED,15INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT, THAT THE
CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE ORTHAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOTINFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR20OTHER RIGHTS. This document does not represent any commitment torelease or implement any portion of the Specification in anyproduct.
THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES ORTYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE25INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEWVERSIONS OF THE SPECIFICATION, IF ANY. Specification Lead MAYMAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THEPROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any useof such changes in the Specification will be governed by the30
then-current license for the applicable version of theSpecification.
LIMITATION OF LIABILITY
TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILLSpecification Lead OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES,35INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, ORFOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVEDAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OFLIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING,PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF40Specification Lead AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THEPOSSIBILITY OF SUCH DAMAGES.
You will indemnify, hold harmless, and defend Specification Leadand its licensors from any claims arising or resulting from: (i)your use of the Specification; (ii) the use or distribution of45your Java application, applet and/or clean room implementation;and/or (iii) any claims that later versions or releases of anySpecification furnished to you are incompatible with theSpecification provided to you under this license.
RESTRICTED RIGHTS LEGEND50
-
8/14/2019 Specification of the portlet
4/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 4
U.S. Government: If this Specification is being acquired by or onbehalf of the U.S. Government or by a U.S. Government primecontractor or subcontractor (at any tier), then the Government'srights in the Specification and accompanying documentation shallbe only as set forth in this license; this is in accordance with548 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense(DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-
DoD acquisitions).
REPORT
You may wish to report any ambiguities, inconsistencies or10inaccuracies you may find in connection with your use of theSpecification ("Feedback"). To the extent that you provideSpecification Lead with any Feedback, you hereby: (i) agree thatsuch Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Specification Lead a15perpetual, non-exclusive, worldwide, fully paid-up, irrevocablelicense, with the right to sublicense through multiple levels ofsublicensees, to incorporate, disclose, and use withoutlimitation the Feedback for any purpose related to the
Specification and future versions, implementations, and test20suites thereof.
(Form ID#011801)
-
8/14/2019 Specification of the portlet
5/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 5
Contents
JavaTM
Portlet Specification................................................................................................ 1
PLT.1 Preface...................................................................................................................... 9PLT.1.1 Additional Sources............................................................................................ 95
PLT.1.2 Who Should Read This Specification............................................................... 9
PLT.1.3 API Reference................................................................................................. 10PLT.1.4 Other Java Platform Specifications............................................................. 10
PLT.1.5 Other Important References ............................................................................ 10
PLT.1.6 Terminology.................................................................................................... 1110
PLT.1.7 Providing Feedback......................................................................................... 11PLT.1.8 Acknowledgements......................................................................................... 11
PLT.2 Overview................................................................................................................ 13
PLT.2.1 What is a Portal? ............................................................................................. 13PLT.2.2 What is a Portlet?............................................................................................ 1315
PLT.2.3 What is a Portlet Container? ........................................................................... 13
PLT.2.4 An Example..................................................................................................... 14PLT.2.5 Relationship with Java 2 Platform, Enterprise Edition ................................... 14
PLT.3 Relationship with the Servlet Specification........................................................... 15
PLT.3.1 Bridging from Portlets to Servlets/JSPs.......................................................... 1620
PLT.3.2 Relationship Between the Servlet Container and the Portlet Container ......... 17
PLT.4 Concepts................................................................................................................. 19PLT.4.1 Elements of a Portal Page ............................................................................... 19
PLT.4.2 Portal Page Creation........................................................................................ 20PLT.4.3 Portal Page Request Sequence........................................................................ 2025
PLT.5 The Portlet Interface............................................................................................... 21
PLT.5.1 Number of Portlet Instances............................................................................ 21PLT.5.2 Portlet Life Cycle............................................................................................ 21
PLT.5.2.1 Loading and Instantiation......................................................................... 22
PLT.5.2.2 Initialization ............................................................................................. 2230PLT.5.2.3 Portlet Window ........................................................................................ 23
PLT.5.2.4 Request Handling..................................................................................... 24
PLT.5.2.5 End of Service.......................................................................................... 28PLT.6 Portlet Config......................................................................................................... 29
PLT.6.1 Initialization Parameters ................................................................................. 2935
PLT.6.2 Portlet Resource Bundle.................................................................................. 29
PLT.7 Portlet URLs........................................................................................................... 31PLT.7.1 PortletURL...................................................................................................... 31
PLT.7.1.1 Including a Portlet Mode or a Window State........................................... 32
PLT.7.1.2 Portlet URL security................................................................................. 3340
-
8/14/2019 Specification of the portlet
6/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 6
PLT.8 Portlet Modes ......................................................................................................... 35PLT.8.1 VIEW Portlet Mode.................................................................................... 35PLT.8.2 EDIT Portlet Mode.................................................................................... 35PLT.8.3 HELP Portlet Mode.................................................................................... 36
PLT.8.4 Custom Portlet Modes..................................................................................... 365
PLT.8.5 GenericPortlet Render Handling..................................................................... 36PLT.8.6 Defining Portlet Modes Support ..................................................................... 37
PLT.9 Window States ....................................................................................................... 39PLT.9.1 NORMAL Window State ............................................................................. 39
PLT.9.2 MAXIMIZED Window State ...................................................................... 3910PLT.9.3 MINIMIZED Window State ...................................................................... 39PLT.9.4 Custom Window States................................................................................... 39
PLT.10 Portlet Context ..................................................................................................... 41
PLT.10.1 Scope of the Portlet Context ......................................................................... 41
PLT.10.2 Portlet Context functionality......................................................................... 4115PLT.10.3 Relationship with the Servlet Context .......................................................... 41
PLT.10.3.1 Correspondence between ServletContext and PortletContext methods. 42PLT.11 Portlet Requests.................................................................................................... 43PLT.11.1 PortletRequest Interface................................................................................ 43
PLT.11.1.1 Request Parameters ................................................................................ 4320
PLT.11.1.2 Extra Request Parameters....................................................................... 44PLT.11.1.3 Request Attributes.................................................................................. 44
PLT.11.1.4 Request Properties.................................................................................. 45
PLT.11.1.5 Request Context Path ............................................................................. 45
PLT.11.1.6 Security Attributes.................................................................................. 4525PLT.11.1.7 Response Content Types ........................................................................ 46
PLT.11.1.8 Internationalization ................................................................................ 46
PLT.11.1.9 Portlet Mode........................................................................................... 46PLT.11.1.10 Window State....................................................................................... 46
PLT.11.2 ActionRequest Interface................................................................................ 4730
PLT.11.2.1 Retrieving Uploaded Data...................................................................... 47PLT.11.3 RenderRequest Interface............................................................................... 48
PLT.11.4 Lifetime of the Request Objects.................................................................... 48
PLT.12 Portlet Responses ................................................................................................. 49
PLT.12.1 PortletResponse Interface ............................................................................. 4935PLT.12.1.1 Response Properties ............................................................................... 49
PLT.12.1.2 Encoding of URLs.................................................................................. 49
PLT.12.2 ActionResponse Interface ............................................................................. 50PLT.12.2.1 Redirections............................................................................................ 50
PLT.12.2.2 Portlet Modes and Window State Changes............................................ 5040
PLT.12.2.3 Render Parameters.................................................................................. 50PLT.12.3 RenderResponse Interface............................................................................. 51
PLT.12.3.1 Content Type.......................................................................................... 51
PLT.12.3.2 Output Stream and Writer Objects......................................................... 51PLT.12.3.3 Buffering ................................................................................................ 5245
PLT.12.3.4 Namespace encoding.............................................................................. 52
-
8/14/2019 Specification of the portlet
7/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 7
PLT.12.3.5 Portlet Title............................................................................................. 53
PLT.12.4 Lifetime of Response Objects....................................................................... 53PLT.13 Portal Context ...................................................................................................... 55
PLT.14 Portlet Preferences ............................................................................................... 57
PLT.14.1 PortletPreferences Interface .......................................................................... 575
PLT.14.2 Preference Attributes Scopes ........................................................................ 58PLT.14.3 Preference Attributes definition.................................................................... 58
PLT.14.3.1 Localizing Preference Attributes............................................................ 59PLT.14.4 Validating Preference values ........................................................................ 60
PLT.15 Sessions................................................................................................................ 6110
PLT.15.1 Creating a Session......................................................................................... 61PLT.15.2 Session Scope................................................................................................ 62
PLT.15.3 Binding Attributes into a Session.................................................................. 62
PLT.15.4 Relationship with the Web Application HttpSession.................................... 63
PLT.15.4.1 HttpSession Method Mapping................................................................ 6315PLT.15.5 Reserved HttpSession Attribute Names........................................................ 63
PLT.15.6 Session Timeouts .......................................................................................... 64PLT.15.7 Last Accessed Times..................................................................................... 64PLT.15.8 Important Session Semantics ........................................................................ 64
PLT.16 Dispatching Requests to Servlets and JSPs.......................................................... 6520
PLT.16.1 Obtaining a PortletRequestDispatcher .......................................................... 65PLT.16.1.1 Query Strings in Request Dispatcher Paths............................................ 65
PLT.16.2 Using a Request Dispatcher .......................................................................... 66
PLT.16.3 The Include Method...................................................................................... 66
PLT.16.3.1 Included Request Parameters ................................................................. 6625PLT.16.3.2 Included Request Attributes................................................................... 66
PLT.16.3.3 Request and Response objects for Included Servlets/JSPs .................... 67
PLT.16.3.4 Error Handling........................................................................................ 68PLT.17 User Information .................................................................................................. 69
PLT.17.1 Defining User Attributes............................................................................... 6930
PLT.17.2 Accessing User Attributes............................................................................. 70PLT.17.3 Important Note on User Information ............................................................ 70
PLT.18 Caching ................................................................................................................ 71
PLT.18.1 Expiration Cache........................................................................................... 71
PLT.19 Portlet Applications.............................................................................................. 7335PLT.19.1 Relationship with Web Applications ............................................................ 73
PLT.19.2 Relationship to PortletContext...................................................................... 73
PLT.19.3 Elements of a Portlet Application ................................................................. 73PLT.19.4 Directory Structure........................................................................................ 73
PLT.19.5 Portlet Application Classloader .................................................................... 7440
PLT.19.6 Portlet Application Archive File ................................................................... 74PLT.19.7 Portlet Application Deployment Descriptor ................................................. 74
PLT.19.8 Replacing a Portlet Application .................................................................... 74
PLT.19.9 Error Handling .............................................................................................. 74PLT.19.10 Portlet Application Environment ................................................................ 7445
PLT.20 Security ................................................................................................................ 75
-
8/14/2019 Specification of the portlet
8/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 8
PLT.20.1 Introduction................................................................................................... 75
PLT.20.2 Roles.............................................................................................................. 75PLT.20.3 Programmatic Security.................................................................................. 75
PLT.20.4 Specifying Security Constraints.................................................................... 76
PLT.20.5 Propagation of Security Identity in EJBTM
Calls .......................................... 775
PLT.21 Packaging and Deployment Descriptor................................................................ 79PLT.21.1 Portlet and Web Application Deployment Descriptor .................................. 79
PLT.21.2 Packaging ...................................................................................................... 79PLT.21.2.1 Example Directory Structure.................................................................. 80
PLT.21.2.2 Version Information ............................................................................... 8010
PLT.21.3 Portlet Deployment Descriptor Elements ..................................................... 80PLT.21.4 Rules for processing the Portlet Deployment Descriptor.............................. 80
PLT.21.5 Deployment Descriptor................................................................................. 81
PLT.21.6 Pictures of the structure of a Deployment Descriptor................................... 91
PLT.21.7 Uniqueness of Deployment Descriptor Values............................................. 9315PLT.21.8 Localization................................................................................................... 93
PLT.21.8.1 Localization of Deployment Descriptor Values..................................... 93PLT.21.8.2 Locales Supported by the Portlet ........................................................... 94PLT.21.9 Deployment Descriptor Example.................................................................. 94
PLT.21.10 Resource Bundles........................................................................................ 9520
PLT.21.11 Resource Bundle Example.......................................................................... 96PLT.22 Portlet Tag Library............................................................................................... 97
PLT.22.1 defineObjects Tag ......................................................................................... 97
PLT.22.2 actionURL Tag.............................................................................................. 98
PLT.22.3 renderURL Tag ............................................................................................. 9925PLT.22.4 namespace Tag............................................................................................ 100
PLT.22.5 param Tag ................................................................................................... 101
PLT.23 Technology Compatibility Kit Requirements .................................................... 103PLT.23.1 TCK Test Components................................................................................ 103
PLT.23.2 TCK Requirements ..................................................................................... 10430
PLT.23.2.1 Declarative configuration of the portal page for a TCK test................ 104PLT.23.2.2 Programmatic configuration of the portal page for a test..................... 106
PLT.23.2.3 Test Portlets Content............................................................................ 107
PLT.23.2.4 Test Cases that Require User Identity.................................................. 107
PLT.A Custom Portlet Modes......................................................................................... 10935PLT.B Markup Fragments............................................................................................... 113
PLT.C CSS Style Definitions.......................................................................................... 115
PLT.D User Information Attribute Names...................................................................... 119PLT.E Features Deferred to Future Releases.................................................................. 125
PLT.F TCK Assertions.................................................................................................... 12540
-
8/14/2019 Specification of the portlet
9/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 9
PLT.1
Preface
This document is the JavaTM
Portlet Specification, v1.0. The standard for the JavaTM
Portlet API is described here.5
PLT.1.1Additional Sources
The specification is intended to be a complete and clear explanation of Java portlets, butif questions remain the following may be consulted:
A reference implementation (RI) has been made available which provides abehavioral benchmark for this specification. Where the specification leaves10
implementation of a particular feature open to interpretation, implementators mayuse the reference implementation as a model of how to carry out the intention of
the specification
A Technology Compatibility Kit (TCK) has been provided for assessing whetherimplementations meet the compatibility requirements of the Java
TMPortlet API15
standard. The test results have normative value for resolving questions aboutwhether an implementation is standard
If further clarification is required, the working group for the JavaTM Portlet APIunder the Java Community Process should be consulted, and is the final arbiter of
such issues20
Comments and feedback are welcomed, and will be used to improve future versions.
PLT.1.2Who Should Read This Specification
The intended audience for this specification includes the following groups:
Portal server vendors that want to provide portlet engines that conform to this
standard25
Authoring tool developers that want to support web applications that conform tothis specification
Experienced portlet authors who want to understand the underlying mechanismsof portlet technology
-
8/14/2019 Specification of the portlet
10/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 10
We emphasize that this specification is not a users guide for portlet developers and is not
intended to be used as such.
PLT.1.3API Reference
An accompanying javadoc, includes the full specifications of classes, interfaces, and
method signatures.5
PLT.1.4Other Java Platform Specifications
The following Java API specifications are referenced throughout this specification:
Java 2 Platform, Enterprise Edition, v1.3 (J2EE)
Java Servlet, v2.3
JavaServer Pages, v1.2 (JSP)10
These specifications may be found at the Java 2 Platform Enterprise Edition website:http://java.sun.com/j2ee/.
PLT.1.5Other Important References
The following Internet specifications provide information relevant to the developmentand implementation of the Portlet API and standard portlet engines:15
RFC 1630 Uniform Resource Identifiers (URI)
RFC 1776 Tags for the Identification of Languages
RFC 1738 Uniform Resource Locators (URL)
RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax
RFC 1808 Relative Uniform Resource Locators20
RFC 1945 Hypertext Transfer Protocol (HTTP/1.0)
RFC 2045 MIME Part One: Format of Internet Message Bodies
RFC 2046 MIME Part Two: Media Types
RFC 2047 MIME Part Three: Message Header Extensions for non-ASCII text
RFC 2048 MIME Part Four: Registration Procedures25
RFC 2049 MIME Part Five: Conformance Criteria and Examples
RFC 2109 HTTP State Management Mechanism
RFC 2145 Use and Interpretation of HTTP Version Numbers
-
8/14/2019 Specification of the portlet
11/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 11
RFC 2616 Hypertext Transfer Protocol (HTTP/1.1)
RFC 2617 HTTP Authentication: Basic and Digest Authentication
ISO 639 Code for the representation of names of languages
ISO 3166 Code (Country) list
OASIS Web Services for Remote Portlets (WSRP)5
Online versions of these RFC and ISO documents are at:
http://www.rfc-editor.org/
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
http://www.chemie.fu-berlin.de/diverse/doc/ISO_3166.html
The World Wide Web Consortium (http://www.w3.org/) is a definitive source of10
HTTP related information affecting this specification and its implementations.
The WSRP Specification can be found in the OASIS web site(http://www.oasis-open.org/).
The Extensible Markup Language (XML) is used for the specification of the DeploymentDescriptors described in Chapter 13 of this specification. More information about XML15can be found at the following websites:
http://java.sun.com/xmlhttp://www.xml.org/
PLT.1.6Terminology
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD,20SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be
interpreted as described in [RFC2119].
PLT.1.7Providing Feedback
We welcome any and all feedback about this specification. Please e-mail your commentsto jsr-168-comments@sun.com.25
Please note that due to the volume of feedback that we receive, you will not normally
receive a reply from an engineer. However, each and every comment is read, evaluated,
and archived by the specification team.
PLT.1.8AcknowledgementsThe Portlet Specification is the result of the work of JSR168 Expert Group, Subbu30Allamaraju (BEA), Chris Braun (Novell), Don Chapman (SAS), Michael Freedman
(Oracle), Laurent Guiraud (SAP), Randal Hanford (Boeing), Andre Kramer (Citrix), Axel
Kratel (Borland), Danny Machak (TIBCO), Kris Meukens (EDS), Wes Mitchell(Broadvision), Takao Mohri (Fujitsu), Dean Moses (Vignette), Andrew Rickard (ATG),
-
8/14/2019 Specification of the portlet
12/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 12
William Seiger (Sybase), David Sean Taylor (Apache), Stefan Hepper (IBM) and
Alejandro Abdelnur (Sun).
We want to give special thanks to (as members of the Expert Group) Subbu Allamaraju,Henning Blohm, Chris Braun, Don Chapman, Adrian Fletcher, Michael Freedman,
Laurent Guiraud, Andre Kramer, Danny Machak, Wes Mitchell, Takao Mohri, Dean5
Moses, Peter Petersen, Andrew Rickard and David Sean Taylor for their contributions.
We would like to thank OASIS WSRP Technical Committee, JSR127 Java Server FacesExpert Group and JSR154 Servlet Specification Expert Group for their cooperation.
We would also like to thank all the people who have sent us feedback during the
Community Review and Public Review stages.10
Finally we would like to thank Maneesha Jain (Sun) and Stephan Hesmer (IBM) who led
the TCK and RI efforts.
-
8/14/2019 Specification of the portlet
13/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 13
PLT.2
Overview
PLT.2.1What is a Portal?
A portal is a web based application that commonly- provides personalization, singlesign on, content aggregation from different sources and hosts the presentation layer of5
Information Systems. Aggregation is the action of integrating content from different
sources within a web page. A portal may have sophisticated personalization features to
provide customized content to users. Portal pages may have different set of portletscreating content for different users.
PLT.2.2What is a Portlet?10
A portlet is a Java technology based web component, managed by a portlet container, thatprocesses requests and generates dynamic content. Portlets are used by portals as
pluggable user interface components that provide a presentation layer to Information
Systems.
The content generated by a portlet is also called a fragment. A fragment is a piece of15
markup (e.g. HTML, XHTML, WML) adhering to certain rules and can be aggregated
with other fragments to form a complete document. The content of a portlet is normallyaggregated with the content of other portlets to form the portal page. The lifecycle of a
portlet is managed by the portlet container.
Web clients interact with portlets via a request/response paradigm implemented by the20portal. Normally, users interact with content produced by portlets, for example by
following links or submitting forms, resulting in portlet actions being received by theportal, which are forwarded by it to the portlets targeted by the user's interactions.
The content generated by a portlet may vary from one user to another depending on the
user configuration for the portlet.25
PLT.2.3What is a Portlet C ontainer?
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 requestsfrom the portal to execute requests on the portlets hosted by it.30
-
8/14/2019 Specification of the portlet
14/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 14
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 anapplication suite or as two separate components of a portal application.
PLT.2.4An Example5
The following is a typical sequence of events, initiated when users access their portal
page:
A client (e.g., a web browser) after being authenticated makes an HTTP request tothe portal
The request is received by the portal10
The portal determines if the request contains an action targeted to any of theportlets associated with the portal page
Ifthere is an action targeted to a portlet, the portal requests the portlet container toinvoke the portlet to process the action
A portal invokes portlets, through the portlet container, to obtain content15fragments that can be included in the resulting portal page
The portal aggregates the output of the portlets in the portal page and sends theportal page back to the client
PLT.2.5Relationship with Java 2 Platform, Enterprise
Edition20
The Portlet API v1.0 is based on the Java 2 Platform, Enterprise Edition, v1.3. Portlet
containers and portlets meet the requirements, described in the J2EE Specification, forexecuting in a J2EE environment.
Due to the analogous functionality of servlets, concepts, names and behavior of the
portlet will be similar to the ones defined in the Servlet Specification 2.3 whenever25applicable.
-
8/14/2019 Specification of the portlet
15/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 15
PLT.3
Relationship with the Servlet Specification
The Servlet Specification v2.3 defines servlets as follows:
A servlet is a Java technology based web component, managed by a container, that
generates dynamic content. Like other Java-based components, servlets are platform5independent Java classes that are compiled to platform neutral bytecode that can be
loaded dynamically into and run by a Java enabled web server. Containers, sometimes
called servlet engines, are web server extensions that provide servlet functionality.Servlets interact with web clients via a request/response paradigm implemented by the
servlet container.10
Portlets share many similarities with servlets:
Portlets are Java technology based web components
Portlets are managed by a specialized container
Portlets generate dynamic content
Portlets lifecycle is managed by a container15
Portlets interact with web client via a request/response paradigm
Portlets differ in the following aspects from servlets:
Portlets only generate markup fragments, not complete documents. The Portalaggregates portlet markup fragments into a complete portal page
Portlets are not directly bound to a URL20
Web clients interact with portlets through a portal system
Portlets have a more refined request handling, action requests and render requests
Portlets have predefined portlet modes and window states that indicate thefunction the portlet is performing and the amount of real state in the portal page
Portlets can exist many times in a portal page25
-
8/14/2019 Specification of the portlet
16/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 16
Portlets have access to the following extra functionality not provided by servlets:
Portlets have means for accessing and storing persistent configuration andcustomization data
Portlets have access to user profile information
Portlets have URL rewriting functions for creating hyperlinks within their5content, which allow portal server agnostic creation of links and actions in page
fragments
Portlets can store transient data in the portlet session in two different scopes: theapplication-wide scope and the portlet private scope
Portlets do not have access to the following functionality provided by servlets:10
Setting the character set encoding of the response
Setting HTTP headers on the response
The URL of the client request to the portal
Because of these differences, the Expert Group has decided that portlets needs to be a
new component. Therefore, a portlet is not a servlet. This allows defining a clear15interface and behavior for portlets.
In order to reuse as much as possible of the existing servlet infrastructure, the Portlet
Specification leverages functionality provided by the Servlet Specification whereverpossible. This includes deployment, classloading, web applications, web application
lifecycle management, session management and request dispatching. Many concepts and20 parts of the Portlet API have been modeled after the Servlet API.
Portlets, servlets and JSPs are bundled in an extended web application called portlet
application. Portlets, servlets and JSPs within the same portlet application shareclassloader, application context and session.
PLT.3.1Bridging from Por tlets to Servlets/JSPs25
Portlets can leverage servlets, JSPs and JSP tag-libraries for generating content.
A portlet can call servlets and JSPs just like a servlet can invoke other servlets and JSPs
using a request dispatcher (see PLT.16 Dispatching Requests to Servlets and JSPsChapter). To enable a seamless integration between portlets and servlets the PortletSpecification leverages many of the servlet objects.30
-
8/14/2019 Specification of the portlet
17/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 17
When a servlet or JSP is called from within a portlet, the servlet request given to the
servlet or JSP is based on the portlet request and the servlet response given to the servletor JSP is based on the portlet response. For example:
Attributes set in the portlet request are available in the included servlet request
(see PLT.16 Dispatching Requests to Servlets and JSPs Chapter),5
The portlet and the included servlet or JSP share the same output stream (seePLT.16 Dispatching Requests to Servlets and JSPs Chapter).
Attributes set in the portlet session are accessible from the servlet session and viceversa (see PLT.15 Portlet Session Chapter).
PLT.3.2Relationship Betw een the Servlet Container and the10Portlet Container
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 Servlet Specification 2.3.15
-
8/14/2019 Specification of the portlet
18/132
-
8/14/2019 Specification of the portlet
19/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 19
PLT.4
Concepts
PLT.4.1Elements of a Port al Page
A portlet generates markup fragments. A portal normally adds a title, control buttons andother decorations to the markup fragment generated by the portlet, this new fragment is5
called a portlet window. Then the portal aggregates portlet windows into a complete
document, the portal page.
Figure 4-1 Elements of a Portal Page
M m E H
M m E H
M m E H
M m E H Portal page
Portlet fragment
Portlet window
Decorations and controls
10
-
8/14/2019 Specification of the portlet
20/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 20
A
B C
D
Portal Page
Portlet Windows
Portal
Server
Portlet A
Portlet B
Portlet C
Portlet D
Client Device
Portlet
Container
PLT.4.2Portal Page Creation
Portlets run within a portlet container. The portlet container receives the content
generated by the portlets. Typically, the portlet container hands the portlet content to a
portal. The portal server creates the portal page with the content generated by the portlets
and sends it to the client device (i.e. a browser) where it is displayed to the user.5
FIGURE 4-2 Portal Page Creation
10
PLT.4.3Portal Page Request Sequence15
Users access a portal by using a client device such as an HTML browser or aweb-enabled phone. Upon receiving the request, the portal determines the list of portlets
that need to be executed to satisfy the request. The portal, through the portlet container,
invokes the portlets. The portal creates the portal page with the fragments generated bythe portlets and the page is returned to the client where it is presented to the user.20
-
8/14/2019 Specification of the portlet
21/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 21
PLT.5
The Portlet Interface
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 theinterface.5
The Portlet API includes a GenericPortlet class that implements the Portlet interface
and provides default functionality. Developers should extend, directly or indirectly, theGenericPortlet class to implement their portlets.
PLT.5.1Number of Portlet Instances
The portlet definition sections in the deployment descriptor of a portlet application10control how the portlet container creates portlet instances.
For a portlet, not hosted in a distributed environment (the default), the portlet container
mustiinstantiate and use only one portlet object per portlet definition.
In the case where a portlet is deployed as part of a portlet application marked as
distributable, in the web.xml deployment descriptor, a portlet container may instantiate15
only one portlet object per portlet definition -in the deployment descriptor- per virtualmachine (VM).ii
PLT.5.2Portlet Life Cycle
A portlet is managed through a well defined life cycle that defines how it is loaded,instantiated and initialized, how it handles requests from clients, and how it is taken out20
of service. This life cycle of a portlet is expressed through the init, processAction,render and destroy methods of the Portlet interface.
-
8/14/2019 Specification of the portlet
22/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 22
PLT.5.2.1Loading and Instantiation
The portlet container is responsible for loading and instantiating portlets. The loading andinstantiation can occur when the portlet container starts the portlet application, or delayeduntil the portlet container determines the portlet is needed to service a request.
The portlet container must load the portlet class using the same ClassLoader the servlet5
container uses for the web application part of the portlet application.iii
After loading the
portlet classes, the portlet container instantiates them for use.
PLT.5.2.2Initialization
After the portlet object is instantiated, the portlet container must initialize the portlet
before invoking it to handle requests.iv Initialization is provided so that portlets can10
initialize costly resources (such as backend connections), and perform other one-time
activities. The portlet container must initialize the portlet object by calling the init methodof the Portlet interface with a unique (per portlet definition) object implementing the
PortletConfig interface. This configuration object provides access to the initialization
parameters and the ResourceBundle defined in the portlet definition in the deployment15descriptor. Refer to PLT.6 Portlet Config Chapter for information about the
PortletConfig interface. The configuration object also gives the portlet access to a
context object that describes the portlets runtime environment. Refer to PLT.10 Portlet
ContextChapter for information about the PortletContext interface.
PLT.5.2.2.1Error Conditions on Initialization20
During initialization, the portlet object may throw an UnavailableException or a
PortletException. In this case, the portlet container must not place the portlet object
into active service and it must release the portlet object.v
The destroy method must notbe called because the initialization is considered unsuccessful.vi
The portlet container may reattempt to instantiate and initialize the portlets at any time25
after a failure. The exception to this rule is when an UnavailableException indicates a
minimum time of unavailability. When this happens the portlet container must wait for
the specified time to pass before creating and initializing a new portlet object.vii
A RuntimeException thrown during initialization must be handled as aPortletException.viii30
-
8/14/2019 Specification of the portlet
23/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 23
PLT.5.2.2.2Tools Considerations
The triggering of static initialization methods when a tool loads and introspects a portlet
application is to be distinguished from the calling of the init method. Developers shouldnot assume that a portlet is in an active portlet container runtime until the init method of
the Portlet interface is called. For example, a portlet should not try to establish5connections to databases or Enterprise JavaBeans containers when static (class)initialization happens.
PLT.5.2.3Portlet Window
The portlet definition may include a set of preference attributes with their default values.
They are used to create preferences objects (see PLT.14 Portlet Preferences Chapter).10
At runtime, when serving requests, a portlet object is associated with a preferences
object. Normally, a portlet customizes its behavior and the content it produces based onthe attributes of the associated preference object. The portlet may read, modify and add
preference attributes.
By default, a preferences object is built using the initial preferences values defined in the15
portlet deployment descriptor. A portal/portlet-container implementation may provideadministrative means to create new preferences objects based on existing ones.
Portal/portlet-container created preferences objects may have their attributes further
customized.
When a portlet is placed in a portal page, a preferences object is also associated with it.20
The occurrence of a portlet and preferences-object in a portal page is called a portletwindow. The portal/portlet-container implementation manages this association.
A portal page may contain more than one portlet window that references the same portlet
and preferences-object.
Administration, management and configuration of preferences objects and creation of25portlet windows is left to the portal/portlet-container implementation. It is also left to the
implementation to provide advanced features, such as hierarchical management ofpreferences objects or cascading changes on preference attributes.
-
8/14/2019 Specification of the portlet
24/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 24
PLT.5.2.4Request Handling
After a portlet object is properly initialized, the portlet container may invoke the portletto handle client requests.
The Portlet interface defines two methods for handling requests, the processActionmethod and the render method.5
When a portal/portlet-container invokes the processAction method of a portlet, the
portlet request is referred to as an action request. When a portal/portlet-container invokes
the render method of a portlet, the portlet request is referred to as a render request.
Commonly, client requests are triggered by URLs created by portlets. These URLs arecalled portlet URLs. A portlet URL is targeted to a particular portlet. Portlet URLs may10
be of two types, action URLs or render URLs. Refer to PLT.7 Portlet URLs Chapter fordetails on portlet URLs.
Normally, a client request triggered by an action URL translates into one action requestand many render requests, one per portlet in the portal page. A client request triggered bya render URL translates into many render requests, one per portlet in the portal page.15
If the client request is triggered by an action URL, the portal/portlet-container must first
trigger the action request by invoking the processAction method of the targeted
portlet.ix
The portal/portlet-container must wait until the action request finishes. Then, theportal/portlet-container must trigger the render request by invoking the render method
for all the portlets in the portal page with the possible exception of portlets for which20
their content is being cached.x
The render requests may be executed sequentially or in
parallel without any guaranteed order.
If the client request is triggered by a render URL, the portal/portlet-container must invokethe render method for all the portlets in the portal page with the possible exception of
portlets for which their content is being cached.xi
The portal/portlet-container must not25invoke the processAction of any of the portlets in the portal page for that client request.
If a portlet has caching enabled, the portal/portlet-container may choose not to invoke therender method. The portal/portlet-container may instead use the portlets cached content.Refer to PLT.18 Caching Chapter for details on caching.
A portlet object placed into service by a portlet container may end up handling no request30
during its lifetime.
-
8/14/2019 Specification of the portlet
25/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 25
Figure 5-1 Request Handling Sequence
Portal/
Portlet Container
Portlet
AClient
Portlet
B
Client Request
Portlet
C
Portal Page
processAction()
The render requests
are triggered in no
specific order.
They may be fired
one after the other or
in parallel.
NOT DEFINED BY THE PORTLET SPECIFICATION
Fragment
Fragment
render()
render()
The action request
must finish before the
render requests start.
render()
Fragment
PLT.5.2.4.1Action Request
Typically, in response to an action request, a portlet updates state based on the5information sent in the action request parameters.
The processAction method of the Portlet interface receives two parameters,
ActionRequest and ActionResponse.
The ActionRequest object provides access to information such as the parameters of the
action request, the window state, the portlet mode, the portal context, the portlet session10
and the portlet preferences data.
While processing an action request, the portlet may instruct the portal/portlet-container toredirect the user to a specific URL. If the portlet issues a redirection, when the
processAction method concludes, the portal/portlet-container must send the redirectionback to the user agent
xiiand it must finalize the processing of the client request.15
A portlet may change its portlet mode and its window state during an action request. Thisis done using the ActionResponse object. The change of portlet mode must be effective
for the following render request the portlet receives. There are some exceptional
-
8/14/2019 Specification of the portlet
26/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 26
circumstances, such as changes of access control privileges, that could prevent the portlet
mode change from happening. The change of window state should be effective for thefollowing render request the portlet receives. The portlet should not assume that the
subsequent request will be in the window state set as the portal/portlet-container could
override the window state because of implementation dependencies between portlet5
modes and window states.
The portlet may also set, in the ActionResponse object, render parameters during the
processing of an action request. Refer to PLT.11.1.1 Request Parameters Section for
details on render parameters.
PLT.5.2.4.2Render Request10
Commonly, during a render request, portlets generate content based on their current state.
The render method of the Portlet interface receives two parameters, RenderRequest
and RenderResponse.
The RenderRequest object provides access to information such as the parameters of the
render request, the window state, the portlet mode, the portal context, the portlet session15and the portlet preferences data.
The portlet can produce content using the RenderResponse writer or it may delegate the
generation of content to a servlet or a JSP. Refer to PLT.16 Dispatching Requests toServlets and JSPs Chapter for details on this.
PLT.5.2.4.2.1GenericPortlet20
The GenericPortlet abstract class provides default functionality and convenience
methods for handling render requests.The render method in the GenericPortlet class sets the title specified in the portletdefinition in the deployment descriptor and invokes the doDispatch method.
The doDispatch method in the GenericPortlet class implements functionality to aid in25
the processing of requests based on the portlet mode the portlet is currently in (see PLT.8Portlet Modes Chapter). These methods are:
doView for handling VIEW requestsxiii
doEdit for handling EDIT requestsxiv
doHelp for handling HELP requestsxv30
Ifthe window state of the portlet (see PLT.9 Window States Chapter) is MINIMIZED, therender method of the GenericPortlet does not invoke any of the portlet moderendering methods.xvi
-
8/14/2019 Specification of the portlet
27/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 27
Typically, portlets will extend the GenericPortlet class directly or indirectly and they
will override the doView, doEdit, doHelp and getTitle methods instead of the render
and doDispatch methods.
PLT.5.2.4.3Multithreading Issues During Request Handling
The portlet container handles concurrent requests to the same portlet by concurrent5execution of the request handling methods on different threads. Portlet developers mustdesign their portlets to handle concurrent execution from multiple threads from within theprocessAction and render methods at any particular time.
PLT.5.2.4.4Exceptions During Request Handling
A portlet may throw either a PortletException, a PortletSecurityException or an10UnavailableException during the processing of a request.
A PortletException signals that an error has occurred during the processing of the
request and that the portlet container should take appropriate measures to clean up therequest. If a portlet throws an exception in the processAction method, all operations on
the ActionResponse must be ignored and the render method must not be invoked within15
the current client request.xvii
The portal/portlet-container should continue processing theother portlets visible in the portal page.
A PortletSecurityException indicates that the request has been aborted because the user
does not have sufficient rights. Upon receiving a PortletSecurityException, the portlet-
container should handle this exception in an appropriate manner.20
An UnavailableException signals that the portlet is unable to handle requests either
temporarily or permanently.
If a permanent unavailability is indicated by the UnavailableException, the portletcontainer must remove the portlet from service immediately, call the portlets destroy
method, and release the portlet object.xviii
A portlet that throws a permanent25UnavailableException must be considered unavailable until the portlet applicationcontaining the portlet is restarted.
When temporary unavailability is indicated by the UnavailableException, then the
portlet container may choose not to route any requests to the portlet during the time
period of the temporary unavailability.30
The portlet container may choose to ignore the distinction between a permanent and
temporary unavailability and treat all UnavailableExceptions as permanent, therebyremoving a portlet object that throws any UnavailableException from service.
A RuntimeException thrown during the request handling must be handled as aPortletException.xix35
-
8/14/2019 Specification of the portlet
28/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 28
When a portlet throws an exception, or when a portlet becomes unavailable, the
portal/portlet-container may include a proper error message in the portal page returned tothe user.
PLT.5.2.4.5Thread Safety
Implementations of the request and response objects are not guaranteed to be thread safe.5This means that they must only be used within the scope of the thread invoking theprocessAction and render methods.
To remain portable, portlet applications should not give references of the request andresponse objects to objects executing in other threads as the resulting behavior may be
non-deterministic.10
PLT.5.2.5End of Service
The portlet container is not required to keep a portlet loaded for any particular period of
time. A portlet object may be kept active in a portlet container for a period ofmilliseconds, for the lifetime of the portlet container (which could be a number of days,
months, or years), or any amount of time in between.15
When the portlet container determines that a portlet should be removed from service, it
calls the destroy method of the Portlet interface to allow the portlet to release anyresources it is using and save any persistent state. For example, the portlet container maydo this when it wants to conserve memory resources, or when it is being shut down.
Before the portlet container calls the destroy method, it should allow any threads that20
are currently processing requests within the portlet object to complete execution.To avoidwaiting forever, the portlet container can optionally wait for a predefined time before
destroying the portlet object.
Once the destroy method is called on a portlet object, the portlet container must not
route any requests to that portlet object.xx
If the portlet container needs to enable the25
portlet again, it must do so with a new portlet object, which is a new instance of theportlets class.xxi
If the portlet object throws a RuntimeException within the execution of the destroymethod the portlet container must consider the portlet object successfully destroyed.xxii
After the destroy method completes, the portlet container must release the portlet object30
so that it is eligible for garbage collection.xxiii
Portlet implementations should not use
finalizers.
-
8/14/2019 Specification of the portlet
29/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 29
PLT.6
Portlet Config
The PortletConfig object provides the portlet object with information to be used during
initialization. It also provides access to the portlet context and the resource bundle thatprovides title-bar resources.5
PLT.6.1Initialization Parameters
The getInitParameterNames and getInitParameter methods of the PortletConfig
interface return the initialization parameter names and values found in the portletdefinition in the deployment descriptor.
PLT.6.2Portlet Resource B undle10
Portlets may specify, in their deployment descriptor definition, some basic information
that can be used for the portlet title-bar and for the portals categorization of the portlet.The specification defines a few resource elements for these purposes, title, short-title and
keywords (see the PLT.21.10 Resource Bundles Section).
These resource elements can be directly included in the portlet definition in the15
deployment descriptor, or they can be placed in a resource bundle.
An example of a deployment descriptor defining portlet information inline could be:
...20
Stock Quote PortletStockfinance,stock market
...25
-
8/14/2019 Specification of the portlet
30/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 30
If the resources are defined in a resource bundle, the portlet must provide the name of the
resource bundle. An example of a deployment descriptor defining portlet information inresource bundles could be:
...5
com.foo.myApp.QuotePortlet...
If the portlet definition defines a resource bundle, the portlet-container must look up these
values in the ResourceBundle. If the root resource bundle does not contain the resources10
for these values and the values are defined inline, the portlet container must add the inlinevalues as resources of the root resource bundle.xxiv
If the portlet definition does not define a resource bundle and the information is defined
inline in the deployment descriptor, the portlet container must create a ResourceBundle
and populate it, with the inline values, using the keys defined in the PLT.21.10 Resource15
Bundles Section.xxv
The render method of the GenericPortlet uses the ResourceBundle object of thePortletConfig to retrieve the title of the portlet from the associated ResourceBundle or
the inline information in the portlet definition.
20
-
8/14/2019 Specification of the portlet
31/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 31
PLT.7
Portlet URLs
As part of its content, a portlet may need to create URLs that reference the portlet itself.
For example, when a user acts on a URL that references a portlet (i.e., by clicking a linkor submitting a form) the result is a new client request to the portal targeted to the portlet.5Those URLs are called portlet URLs.
PLT.7.1PortletURL
The Portlet API defines the PortletURL interface. Portlets must create portlet URLsusing PortletURL objects. A portlet creates PortletURL objects invoking the
createActionURL and the createRenderURL methods of the RenderResponse interface.10The createActionURL method creates action URLs. The createRenderURL methodcreates render URLs.
Because some portal/portlet-containers implementations may encode internal state as part
of the URL query string, portlet developers should not code forms using the HTTP GETmethod.15
A render URL is an optimization for a special type of action URLs. The portal/portlet-
container must not invoke the processAction method of the targeted portlet.xxvi
Theportal/portlet-container must ensure that all the parameters set when constructing the
render URL become render parameters of the subsequent render requests for the
portlet.xxvii
20
Render URLs should not be used for tasks that are not idempotent from the portlet
perspective. Error conditions, cache expirations and changes of external data may affectthe content generated by a portlet as result of a request triggered by a render URL.
Render URLs should not be used within forms as the portal/portlet-container may ignore
form parameters.25
Portlets can add application specific parameters to the PortletURL objects using thesetParameter and setParameters methods. A call to any of the setParameter
methods must replace any parameter with the same name previously set.xxviii
All the
parameters a portlet adds to a PortletURL object must be made available to the portlet asrequest parameters.xxix Portlet developers should note that the parameters of the current30render request are not carried over when creating a PortletURL.
-
8/14/2019 Specification of the portlet
32/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 32
The portlet-container must x-www-form-urlencoded encode parameter names and
values added to a PortletURL object.xxx
Portlet developers should not encode parameternames or values before adding them to a PortletURL object.
If a portal/portlet-container encodes additional information as parameters, it must encode
them properly to avoid collisions with the parameters set and used by the portlet.xxxi
5
Using the toString method, a portlet can obtain the string representation of thePortletURL for its inclusion in the portlet content.
An example of creating a portlet URI would be:
...PortletURL url = response.createRenderURL();10url.setParameter(customer,foo.com);url.setParameter(show,summary);writer.print(Summary);...
Portlet developers should be aware that the string representation of a PortletURL may not15
be a well formed URL but a special token at the time the portlet is generating its content.Portal servers often use a technique called URL rewriting that post-processes the content
resolving tokens into real URLs.
PLT.7.1.1Including a Portlet Mode or a Window State
A portlet URL can include a specific portlet mode (see PLT.8 Portlet Modes Chapter) or20
window state (see PLT.9 Window States Chapter). The PortletURL interface has thesetWindowState and setPortletMode methods for setting the portlet mode and windowstate in the portlet URL. For example:
...PortletURL url = response.createActionURL();25url.setParameter(paymentMethod,creditCardInProfile);url.setWindowState(WindowState.MAXIMIZED);writer.print();...
A portlet cannot create a portlet URL using a portlet mode that is not defined as30
supported by the portlet or that the user it is not allowed to use. The setPortletMode
methods must throw a PortletModeException in that situation.xxxii
. The change ofportlet mode must be effective for the request triggered by the portlet URL.xxxiii There are
some exceptional circumstances, such as changes access control privileges, that could
prevent the portlet mode change from happening.35
A portlet cannot create a portlet URL using a window state that is not supported by the
portlet container. The setWindowState method must throw a WindowStateException ifthat is the case.xxxiv The change of window state should be effective for the request
triggered by the portlet URL. The portlet should not assume that the request triggered by
the portlet URL will be in the window state set as the portal/portlet-container could40override the window state because of implementation dependencies between portlet
modes and window states.
-
8/14/2019 Specification of the portlet
33/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 33
PLT.7.1.2Portlet URL securit y
The setSecure method of the PortletURL interface allows a portlet to indicate if theportlet URL has to be a secure URL or not (i.e. HTTPS or HTTP). If the setSecure
method is not used, the portlet URL must be of the same security level of the current
request.
xxxv
5
-
8/14/2019 Specification of the portlet
34/132
-
8/14/2019 Specification of the portlet
35/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 35
PLT.8
Portlet Modes
A portlet mode indicates the function a portlet is performing. Normally, portlets perform
different tasks and create different content depending on the function they are currentlyperforming. A portlet mode advises the portlet what task it should perform and what5
content it should generate. When invoking a portlet, the portlet container provides the
current portlet mode to the portlet. Portlets can programmatically change their portletmode when processing an action request.
The Portlet Specification defines three portlet modes, VIEW, EDIT, and HELP. The
PortletMode class defines constants for these portlet modes.10
The availability of the portlet modes, for a portlet, may be restricted to specific user roles
by the portal. For example, anonymous users could be allowed to use the VIEW and HELP
portlet modes but only authenticated users could use the EDIT portlet mode.
PLT.8.1VIEW Portlet Mode
The expected functionality for a portlet in VIEW portlet mode is to generate markup15
reflecting the current state of the portlet. For example, the VIEW portlet mode of a portlet
may include one or more screens that the user can navigate and interact with, or it mayconsist of static content that does not require any user interaction.
Portlet developers should implement the VIEW portlet mode functionality by overriding
the doView method of the GenericPortlet class.20
Portlets must support the VIEW portlet mode.
PLT.8.2EDIT Portlet Mode
Within the EDIT portlet mode, a portlet should provide content and logic that lets a usercustomize the behavior of the portlet. The EDIT portlet mode may include one or more
screens among which users can navigate to enter their customization data.25
Typically, portlets in EDIT portlet mode will set or update portlet preferences. Refer to
PLT.14 Portlet Preferences Chapter for details on portlet preferences.
Portlet developers should implement the EDIT portlet mode functionality by overriding
the doEdit method of the GenericPortlet class.
Portlets are not required to support the EDIT portlet mode.30
-
8/14/2019 Specification of the portlet
36/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 36
PLT.8.3HELP Portlet Mode
When in HELP portlet mode, a portlet should provide help information about the portlet.
This help information could be a simple help screen explaining the entire portlet incoherent text or it could be context-sensitive help.
Portlet developers should implement the HELP portlet mode functionality by overriding5
the doHelp method of the GenericPortlet class.
Portlets are not required to support the HELP portlet mode.
PLT.8.4Custom Portlet M odes
Portal vendors may define custom portlet modes for vendor specific functionality.
Portlets can only use portlet modes that are defined by the portal. Portlets must define the10
custom portlet modes they intend to use in the deployment descriptor using the custom-portlet-mode
element. At deployment time, the custom portlet modes defined in thedeployment descriptors should be mapped to custom portlet modes supported by theportal implementation.
If a custom portlet mode defined in the deployment descriptor is not mapped to a custom15
portlet mode provided by the portal, portlets must not be invoked in that portlet mode.
For example, the deployment descriptor for a portlet application containing portlets that
support clipboard and config custom portlet modes would have the following definition:
...20
Creates content for Cut and Paste
clipboard
25
Provides administration functionsconfig
...30
The PLT.A Extended Portlet Modes appendix defines a list of portlet mode names and
their suggested utilization. Portals implementing these predefined custom portlet modes
could do an automatic mapping when custom portlet modes with those names are definedin the deployment descriptor.35
PLT.8.5GenericPortlet Render Handling
The GenericPortlet class implementation of the render method dispatches requests
to the doView, doEdit or doHelp method depending on the portlet mode indicated in the
request using the doDispatch method.xxxvi
If the portlet provides support for customportlet modes, the portlet should override the doDispatch method of the40GenericPortlet.
-
8/14/2019 Specification of the portlet
37/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 37
PLT.8.6Defining Portlet M odes Support
Portlets must describe within their definition, in the deployment descriptor, the portlet
modes they can handle for each markup type they support. As all portlets must support
the VIEW portlet mode, VIEW does not have to be indicated.xxxvii
The portlet must not be
invoked in a portlet mode that has not been declared as supported for a given markup5 type.xxxviii
The following example shows a snippet of the portlet modes a portlet defines as
supporting in its deployment descriptor definition:
...10
text/htmledithelp...15
text/vnd.wap.wmlhelp...20
...
For HTML markup, this portlet supports the EDIT and HELP portlet modes in addition to
the required VIEW portlet mode. For WML markup, it supports the VIEW and HELP portletmodes.25
The portlet container must ignore all references to custom portlet modes that are not
supported by the portal implementation, or that have no mapping to portlet modes
supported by the portal.xxxix
-
8/14/2019 Specification of the portlet
38/132
-
8/14/2019 Specification of the portlet
39/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 39
PLT.9
Window States
A window state is an indicator of the amount of portal page space that will be assigned to
the content generated by a portlet. When invoking a portlet, the portlet-container providesthe current window state to the portlet. The portlet may use the window state to decide5
how much information it should render. Portlets can programmatically change theirwindow state when processing an action request.
The Portlet Specification defines three window states, NORMAL, MAXIMIZED and
MINIMIZED. The WindowState class defines constants for these window states.
PLT.9.1NORMAL Window State10
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.
PLT.9.2MAXIMIZED Window State
The MAXIMIZED window state is an indication that a portlet may be the only portlet being15
rendered in the portal page, or that the portlet has more space compared to other portletsin the portal page. A portlet may generate richer content when its window state isMAXIMIZED.
PLT.9.3MINIMIZED Window State
When a portlet is in MINIMIZED window state, the portlet should only render minimal20output or no output at all.
PLT.9.4Custom Window States
Portal vendors may define custom window states.
Portlets can only use window states that are defined by the portal. Portlets must define the
custom window states they intend to use in the deployment descriptor using the custom-25window-state element. At deployment time, the custom window states defined in thedeployment descriptors should be mapped to custom window states supported by the
portal implementation.
-
8/14/2019 Specification of the portlet
40/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 40
If a custom window state defined in the deployment descriptor is not mapped to a custom
window state provided by the portal, portlets must not be invoked in that window state.xl
For example, the deployment descriptor for a portlet application containing portlets thatuse a custom half_page window state would have the following definition:
5 ...
Occupies 50% of the portal pagehalf_page
10...
-
8/14/2019 Specification of the portlet
41/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 41
PLT.10
Portlet Context
The PortletContext interface defines a portlets view of the portlet application within
which the portlet is running. Using the PortletContext object, a portlet can log events,obtain portlet application resources, and set and store attributes that other portlets and5servlets in the portlet application can access.
PLT.10.1Scope of the Portle t Context
There is one instance of the PortletContext interface associated with each portletapplication deployed into a portlet container.xli In cases where the container is distributed
over many virtual machines, a portlet application will have an instance of the10PortletContext interface for each VM.
xlii
PLT.10.2Portlet Context fu nctionality
Through the PortletContext interface, it is possible to access context initialization
parameters, retrieve and store context attributes, obtain static resources from the portlet
application and obtain a request dispatcher to include servlets and JSPs.15
PLT.10.3Relationship with the Servlet Context
A portlet application is an extended web application. As a web application, a portletapplication also has a servlet context. The portlet context leverages most of its
functionality from the servlet context of the portlet application.
The context-wide initialization parameters are the same as initialization parameters of the20
servlet context and the context attributes are shared with the servlet context. Therefore,they must be defined in the web application deployment descriptor (the web.xml file).
The initialization parameters accessible through the PortletContext must be the samethat are accessible through the ServletContext of the portlet application.
xliii
Context attributes set using the PortletContext must be stored in the ServletContext25of the portlet application. A direct consequence of this is that data stored in the
ServletContext by servlets or JSPs is accessible to portlets through thePortletContext and vice versa.
xliv
The PortletContext must offer access to the same set of resources theServletContext exposes.
xlv30
-
8/14/2019 Specification of the portlet
42/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 42
The PortletContext must handle the same temporary working directory the
ServletContext handles. It must be accessible as a context attribute using the sameconstant defined in the Servlet Specification 2.3 SVR 3 Servlet Context Chapter,
javax.servlet.context.tempdir.xlvi
The portlet context must follow the same
behavior and functionality that the servlet context has for virtual hosting and reloading5
considerations. (see Servlet Specification 2.3 SVR 3 Servlet ContextChapter)
xlvii
:
PLT.10.3.1Correspondence be tween ServletContext andPortletContext methods
The following methods of the PortletContext should provide the same functionality as
the methods of the ServletContext of similar name: getAttribute,10getAttributeNames, getInitParameter, getInitParameterNames, getMimeType,getRealPath, getResource, getResourcePaths, getResourceAsStream, log,
removeAttribute and setAttribute.
-
8/14/2019 Specification of the portlet
43/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 43
PLT.11
Portlet Requests
The request objects encapsulate all information about the client request, parameters,
request content data, portlet mode, window state, etc. A request object is passed toprocessAction and render methods of the portlet.5
PLT.11.1PortletRequest Interface
The PortletRequest interface defines the common functionality for the ActionRequest
and RenderRequest interfaces.
PLT.11.1.1Request Parameters
If a portlet receives a request from a client request targeted to the portlet itself, the10
parameters must be the string parameters encoded in the URL (added when creating the
PortletURL) and the string parameters sent by the client to the portlet as part of the client
request.xlviii
The parameters the request object returns must be "x-www-form-
urlencoded" decoded.xlix
The portlet-container must not propagate parameters received in an action request to15
subsequent render requests of the portlet.l
If a portlet wants to do that, it can use renderURLs or it must use the setRenderParameter or setRenderParameters methods ofthe ActionResponse object within the processAction call.
If a portlet receives a render request that is the result of a client request targeted to
another portlet in the portal page, the parameters must be the same parameters as of the20
previous render request.li
If a portlet receives a render request following an action request as part of the same client
request, the parameters received with render request must be the render parameters setduring the action request.lii
Commonly, portals provide controls to change the portlet mode and the window state of25portlets. The URLs these controls use are generated by the portal. Client requests
triggered by those URLs must be treated as render URLs and the existing renderparameters must be preserved.liii
A portlet must not see any parameter targeted to other portlets. liv
-
8/14/2019 Specification of the portlet
44/132
JavaTM Portlet Specification, version 1.0 (10/07/2003) 44
The parameters are stored as a set of name-value pairs. Multiple parameter values can
exist for any given parameter name. The following methods of the PortletRequest
interface are available to access parameters:
getParameter
getParameterNames5 getParameterValues getParameterMap
The getParameterValues method returns an array of String objects containing all the
parameter values associated with a parameter name. The value returned from thegetParameter method must be the first value in the array of String objects returned by10
getParameterValueslv. If there is a single parameter value associated with a parameter
name the method returns must return an array of size one containing the parameter
value.lvi
. The getParameterMap method must return an unmodifiable Map object. If therequest does not have any parameter, the getParameterMap must return an empty Map
object.15
PLT.11.1.2Extra Request Para metersThe portal/portlet-container implementation may add extra parameters to portlet URLs tohelp the portal/portlet-container route and process client requests.
Extra parameters used by the portal/portlet-container must be invisible to the portlets
receiving the request. lvii It is the responsibility of the portal/portlet-container to properly20
encode these extra parameters to avoid name collisions with parameters the portlets
define.
Parameter names beginning with the javax.portlet. prefix are reserved fordefinition by this specification for use by portal/portlet-container implementations.
top related