[jsr362-observers:] [jsr362-experts:] Re: New documents
- From: Martin Scott Nicklous <
- Subject: [jsr362-observers:] [jsr362-experts:] Re: New documents
- Date: Wed, 14 Aug 2013 14:55:50 +0200
- List-id: <jsr362-experts.portletspec3.java.net>
See comments inline ...
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.
> 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.
> * 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
> On Aug 12, 2013, at 8:05 AM, Martin Scott Nicklous
> > wrote:
> 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 ...