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>