[jsr362-experts:] New documents
- From: Martin Scott Nicklous <
- Subject: [jsr362-experts:] New documents
- Date: Mon, 12 Aug 2013 14:05:34 +0200
I added two new documents to our download collection -
JSR362Parameters-20130811.pdf - Describes parameter handling based on the
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 document.
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 parameter
handling document. However, the descriptions are held to an overview level.
My goal was to describe functionality that could be implemented either with
the portlet state proposal #4 or with the proposal #7. The areas where the
proposed new solution differs from the JSR 286 implementation are marked by
enclosing the JSR362-specific text in a blue-shaded box. Conversely, text
that is not in a blue-shaded box describes functionality that is unchanged
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 made
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 the
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 way
the methods are defined, I don't think we need that separation - if you set
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 the
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 clarity.
Anyway, to underscore that the documents belong together, I put them in a
separate folder, here:
I'm anxious to get your impressions ...