Portlet
1.0 Errata – May 11, 2005
Please
send feedback to jsr-168-comments@jcp.org
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[]
15.
Preferences Validator
16.
Typo Correction
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.
Issue
15
Preferences
Validator
The
specification does not indicate that Preference values cannot be
changed within the Validator object when the validate method is
invoked.
Resolution
PLT.14.4
Validating Preferences Values
[This
section supplements section PLT.14.4 on page 60 in the Portlet
1.0 specification, add the text to line 26]
Portlet
preferences cannot be modified when they are being validated by a
PreferencesValidator object. If the store method is invoked within
the scope of the PreferenceValidator's validate method invocation, an
IllegalStateException must be thrown.
Issue 16
Typo
correction
An
additional typo correction to those indicated in Issue 8.
Resolution
PLT.8.4 Custom
Portlet Modes
[This
section replaces example on page 36, <name> is replaced
with <portlet-mode>]
Portlet
preferences cannot be modified when they are being validated by a
PreferencesValidator object. If the store method is invoked within
the scope of the PreferenceValidator's validate method invocation, an
IllegalStateException must be thrown.
<portlet-app>
...
<custom-portlet-mode>
<description>Creates
content for Cut and Paste</description>
<portlet-mode>clipboard</portlet-mode>
</custom-portlet-mode>
<custom-portlet-mode>
<description>Provides
administration functions</description>
<portlet-mode>config</portlet-mode>
</custom-portlet-mode>
...
</portlet-app>