[jsr362-observers:] [jsr362-experts:] Re: New documents
- From: Neil Griffin <
- Subject: [jsr362-observers:] [jsr362-experts:] Re: New documents
- Date: Tue, 20 Aug 2013 09:30:44 -0400
- List-id: <jsr362-experts.portletspec3.java.net>
On Aug 14, 2013, at 8:55 AM, Martin Scott Nicklous
> Hi Neil,
> See comments inline ...
> Neil Griffin
> wrote on 13.08.2013 16:16:55:
>> From: Neil Griffin
>> Date: 13.08.13 16:17
>> Subject: [jsr362-experts:] Re: New documents
>> Hi Scott,
>> Regarding things common to Variant#4 and Variant#7:
>> * At first I thought that that the ViewState interface (formerly
>> PortletState) was an improvement, but now I think that it is too
>> much of a fine distinction because of overloaded terminology. Julien
>> recently mentioned that "state" is a very overloaded term. But
>> "view" is also an overloaded term that refers to
>> javax.portlet.PortletMode.VIEW and also the current "View" of MVC.
>> Would not the "View"State interface apply to EDIT and HELP modes as
>> well? In addition, the term ViewState is already used by JSF with
>> the "javax.faces.ViewState" parameter.
>> If you would like to keep with the ViewState interface, then I
>> would suggest a name like "PortletDisplay" that doesn't have
>> overloaded terminology.
> The purpose of the ViewState interface is to pull the method definitions
> that handle portlet mode & window state into a single location in order to
> help consistency. I called it ViewState because Julien suggested the term
> in a mailing list post. I am open to using a different name if we come up
> with a better one.
I just send a message to my colleagues, asking them if they like the name
"ViewState" or to offer alternative names. I'll get back to you with results
when I hear back.
>> Regarding Variant#7:
>> * On page 5, the description of RenderRequest reads:
>> "getRenderParameters returns the portlet render parameters as they
>> were last set during
>> Action Phase or Event Phase processing, but including updated values
>> of any public
>> render parameters modified by other portlets."
>> Did you mean to write "including" and not "but including"?
> Maybe I was splitting hairs with the wording a bit - I wanted to make sure
> readers would understand that the public render parameters could be
> updated, and not think that the portlet render parameters (public &
> private) would be set exactly as they were during the last Action or Event
> Phase for the portlet. I was trying to place emphasis on the idea that the
> public render parameters could be updated. Maybe it's a Germanism that
> crept into my language.
> Anyway, I can take out the "but" if that makes it clearer.
>> * On page 5, there is a note at the bottom that reads:
>> "Note: The API enforces a strict separation between the action and
>> render parameters
>> and between the resource and render parameters. No methods for retrieving
>> combined action & render or resource & render parameters is provided."
>> You also have the following statement for BaseURL and PortletRequest:
>> "Deprecated: JSR 286 parameter methods"
>> Just wanted to point out to everyone on the EG that a main
>> difference with Variant#7 is that PortletParameters is a
>> "composition" object that is returned by new methods like
>> getRenderParameters(), getActionParameters(), etc.. (rather than an
>> interface that is implemented by PortletRequest and BaseURL)
>> This means that methods like BaseURL.getParameterMap() and
>> PortletRequest.getParameterMap() would be deprecated.
>> * If PortletParameters is a composition object then I think that
>> the method names should probably be shortened:
>> PortletParameters.get(String name);
>> MutablePortletParameters.set(String name, String value);
>> MutablePortletParameters.set(String name, String values);
>> PortletParameters.isPublic(String name);
>> PortletParameters.isPrivate(String name);
> Yes, in #7 PortletParameters is a composition object.
> Shortening the method names seems like a good idea.
Thanks, also here is another possibility for shortened names:
>> * JSF Portlet Bridges would need to implement ExternalContext
>> parameter methods according to the current portlet phase:
> I interpret this as being more of a "fyi" comment rather than a "todo" type
> of comment, correct?
> Or do you see something in #7 that would make it difficult to implement the
JSR 329 specifies what these methods are supposed to return in a portlet
environment. For example, here are the requirements for
"This Map must be composed from the set of parameters available via the
javax.portlet.PortletRequest methods getParameter() and getParameterNames()
plus any additional parameter names encoded in the (query string) of the
This later situation primarily occurs when using a default viewId provided
So the requirements of JSR 329 are very much tied to the existing Portlet 2.0
API. In fact the Bridge TCK calls methods like
PortletRequest.getParameterNames() (which we are proposing to deprecate) in
order to verify that bridge implementations are fulfilling the requirements.
>> On Aug 12, 2013, at 8:05 AM, Martin Scott Nicklous
>> I added two new documents to our download collection -
>> JSR362Parameters-20130811.pdf - Describes parameter handling based on
>> assumption that the API proposals in the Portlet State document are
>> PortletState-20130811.pdf - Fundamentally the same as the
>> PortletState-20130806.pdf document from last week, but updated to address
>> inconsistencies that came up when writing the parameter handling
>> The changes were all in Proposal #6 from the older document, so I renamed
>> Proposal #6 to Proposal #7 in the new document to be able to discern
>> between the two.
>> The JSR362 parameter handling document is derived from the JSR286
>> handling document. However, the descriptions are held to an overview
>> My goal was to describe functionality that could be implemented either
>> the portlet state proposal #4 or with the proposal #7. The areas where
>> proposed new solution differs from the JSR 286 implementation are marked
>> enclosing the JSR362-specific text in a blue-shaded box. Conversely, text
>> that is not in a blue-shaded box describes functionality that is
>> compared to JSR 286.
>> While writing this document, I noticed that I was not using terms in a
>> consistent manner, so I added a glossary where at least an attempt is
>> to define the terms precisely. I then went back through and tried pretty
>> hard to be consistent over the two documents in the use of terms such as
>> "portlet render parameters".
>> Note that there is one major conceptual difference between proposals #4 &
>> Proposal #4 provides pretty much the same parameter handling APIs that we
>> are used to with JSR 286. They bring with them the same semantic problems
>> that JSR 286 has of mixing the several concepts of render parameters,
>> action parameters, resource parameters, and public render parameters all
>> together and making them available through the same methods. You have to
>> use the the context you are running in (for example, resource phase
>> execution, or whatever) in order to interpret the parameters.
>> Proposal #7 enforces a strict separation between the portlet render
>> parameters that control rendering and resource serving on one hand, and
>> action parameters and the resource parameters that provide additional
>> information for a single request on the other hand. It doesn't enforce a
>> separation between private and public render parameters, although it does
>> provide a test as to whether a parameter is public or private. But the
>> the methods are defined, I don't think we need that separation - if you
>> a portlet render parameter, it's set, and if you remove one, it's gone.
>> There is no implicit special handling for public render parameters. And
>> new methods can coexist with the old ones to aid in migration to the
>> version 3 model.
>> My personal feeling is that #7 improves separation of concerns and
>> Anyway, to underscore that the documents belong together, I put them in a
>> separate folder, here:
>> I'm anxious to get your impressions ...