Portlet 1.0 Errata - July 20, 2004
The following is
a list of clarifications and corrections to the Portlet 1.0 final specification
(dated October 27th, 2003).
Issues were prompted
by questions from vendors, implementors and end-users. All issues will
be incorporated into the Portlet 1.1 specification.
The errata starts
with a brief list of all issues. Each issue is then described in more
detail and a resolution is given. All references are to the Portlet
1.0 final specification.
All Issues
1. Render Parameter
2. Supported-Locale Format
3. Version Information Format
4. Preferences Validator Instance
5. Preferences setValue Method
6. encodeURL Method
7. iframe Tag
8. Typos Correction
9. PortletURL Parameters
10. Request Attribute
11. PortletURL
12. Servlet Lookup
13. Exception Handling During processAction
14. String[]
Detailed Issues
Issue 1
Render Parameters
Portlet
specification states that the render parameters must be the same parameters
as of the previous render request. While most of the time this is true, there
may be cases where the render parameters are different.
Resolution
PLT.11.1.1 Request
Parameters
[This section
replaces line 20 -21 on page 43 in the Portlet 1.0 specification]
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 should
be the same parameters as of the previous render request from this client.
Issue 2
Supported Locale Format
Portlet
specification requires the portlet to declare the locales it is going to
support at run-time using the <supported-locale> element in the deployment
descriptor. The specification however does not mention the format of the
locale.
Resolution
PLT.21.8.2 Locales
Supported by the Portlet
[This section
supplements section PLT.21.8.2 on page 94 in the Portlet 1.0
specification, add the text]
The
supported locales declared in the deployment descriptor should follow the
lang_COUNTRY_variant format as defined by
RFC 1766
.
Issue 3
Version Information Format
Portlet
specification recommends that Implementation-* attributes in META-INF/MANIFEST.MF
should be used to define the version information. The specification does
not mention the format of the version information.
Resolution
PLT.21.2.2 Version
Information
[This section
supplements section PLT.21.2.2 on page 80 in the Portlet 1.0
specification, add the text]
The
version information should follow the format defined by the
Java Product Versioning Specification
Issue 4
Preferences Validator Instance
Portlet
specification states that if a portlet definition includes a validator, the
portlet container must create a single validator instance per portlet definition.
If the application is a distributed application, the portlet container must
create an instance per VM. In the case of distributed application,
the wording is incorrect, the specification should state the the portlet
container must create an instance of the validator per portlet definition
per VM.
Resolution
PLT.14.4 Validating
Preference Values
[This section
replaces line 18-19 on page 60 in the Portlet 1.0 specification,
the change is in bold]
If the application
is a distributed application, the portlet container must create an instance
of the validator per portlet definition per VM.
Issue 5
Preferences setValue Method
Portlet
specification states that the Preferences setValue method sets a single value
into the preferences attribute. Though implied, the specification does not
state the behavior of setValue when setValues method has already been called
with multiple values. It does not clearly state whether the single value
replaces the existing set of values or the single value is added to the existing
set of values.
Resolution
PLT.14.1 PortletPreferences
Interface
[This section
supplements section PLT.14.1 on page 57 in the Portlet 1.0 specification,
add the text]
If setValues method
has been called with multiple values. The subsequent setValue method overwrites
all existing values replacing them with the new single value.
Issue 6
encodeURL Method
Portlet
specification defines the encodeURL method, however it doesn't caution the
developer that the returned URL may not be a well formed URL.
Resolution
PLT.12.1.2 Encoding
of URLs
[This section
supplements section PLT.12.1.2 on page 49 in the Portlet 1.0
specification, add the text]
Portlet developer
should be aware that the returned url may not be a well formed URL but
a special token at the time the portlet is generating its content.
Issue 7
iframe Tag
Portlet
specification forbids portlet to generate HTML fragment using iframe tag.
Further discussion leads to the conclusion that iframe tag can be used,
though it must be used with caution.
Resolution
PLT.B Markup Fragments
[This section
replaces line 9-10 on page 113 in the Portlet 1.0 specification,
iframe is removed from the list of must not use tags and extra caution
is listed]
Portlets generating
HTML fragments must not use the following tags: base, body, frame, frameset,
head, html and title. iframe tag can be used, however it must be used with
caution. The usage of the iframe tag should not break the portal paradigm.
Issue 8
Typos Corrections
There are
a number of typos in the specification. The following shows the corrections.
Resolution
PLT.1.5 Other Important
References
[This section
replaces line 17 on page 10 in the Portlet 1.0 specification,
1776 is replaced with 1766]
RFC 1766 Tags for
the Identification of Languages.
PLT.18.1 Expiration
Cache
[This section
replaces line 23-25 on page 71 in the Portlet 1.0 specification,
PortletResponse is replaced with RenderResponse]
A portlet that has
defined an expiration cache in its portlet definition may programmatically
alter the expiration time by setting a property in the RenderResponse
object using the EXPIRATION_CACHE constant defined in the RenderResponse
interface.
PLT.20.3 Programmatic
Security
[This section
replaces example on page 76 in the Portlet 1.0 specification, </manager>
is replaced with </role-link>]
<security-role-ref
>
<role-name>FOO</role-name>
<role-link>manager</role-link>
</security-role-ref>
PLT.20.4 Specifying
Security Constraints
[This section
replaces example on page 77 in the Portlet 1.0 specification, the
extra "/" is removed]
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
PLT.A.1 About Portlet
Mode
[This section
replaces line 37-39 on page 111 in the Portlet 1.0 specification,
<name> is replaced with <portlet-mode>]
<custom-portlet-mode>
<portlet-mode>about</portlet-mode>
</custom-portlet-mode>
Issue 9
PortletURL Parameters
Though the specification
states that the portlet must not see parameters targeted to other portlets
which implies that the portlet parameters are per portlet, it may be clearer
to state it's not neccessary to namespace or encode the parameters
Resolution
PLT.11.1.1 Request
Parameters
[This section
supplements section PLT.11.1.1 Request Parameters on page 43 in
the Portlet 1.0 specification, add the text]
The portlet must
not see parameters targeted to other portlets. Portlet should not namespace
or encode URL parameters or form parameters.
Issue 10
Request Attribute
The specification states
that request attributes are objects associated with a portlet during a single
portlet request. While not stated explicitly, the intent of the spec is that
portlet developers can not assume that attributes are shared between action
and render requests.
Resolution
PLT.11.1.3 Request
Attributes
[This section
supplements section PLT.11.1.3 Request Attributes on page 44 in
the Portlet 1.0 specification, add the text]
Request attributes
are objects associated with a portlet during a single portlet request. Portlet
can not assume that attributes are shared between action and render requests.
Issue 11
Portlet URL
Whereas the specification
states what happens when mode and state are not set for the Portlet URL tag,
the specification does not mention what happens when mode and state are not
set for the Portlet URL. We need to add the same text to the Portlet URL
section.
Resolution
PLT.7.1.1 Including
a Portlet Mode or Window State
[This section
supplements section PLT.7.1.1 Including a Portlet Mode or Window
State on page 32 in the Portlet 1.0 specification, add the text]
If the portlet mode
is not set for a URL, it must stay the same as the mode of the current request.
If the window state is not set for a URL, it should stay the same as the
window state of the current request.
Issue 12
Servlet Lookup
The specification doesn't
indicate how the path is resolved to a servlet when using the request dispatcher.
Resolution
PLT.16.3 The Include
Method
[This section
supplements section PLT.16.3 The Include Method on page 66 in the
Portlet 1.0 specification, add the text]
The lookup of the servlet
given a path is done according to the servlet path matching rule defined
in SRV.11 section of the servlet specification.
Issue 13
Exception Handling During processAction
The specification states
that 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
within the current client request. The specification needs not to mandate
that the render method must not be invoked within the current client request.
Resolution
[This section
replaces line 14-16 on page 27 in the Portlet 1.0 specification,
"render method must not be invoked within the current client request" is
removed]
If a portlet throws
an exception in the processAction method, all operations on the ActionResponse
must be ignored.
Issue 14
String[]
For those method parameters
that take String[], the specification fails to state that the portlet container
must make a copy of the String[]. Similarly the specification fails to state
when Map which contain String[] as values is returned, the portlet container
must ensure changes to the String[] will not affect the portlet container.
Resolution
For those method parameters
or return values that take String[] or Map with values that are String[],
the portlet container must make copies of the String[] such that modification
to the String[] by the portlet after the method call will not affect the
function of the portlet container.