Comments on draft 16

[Michael Freedman <michael.freedman@oracle.com>]

Section 3.7: Types of Stateful Information:
It would be very useful to add a paragraph that informs the reader that 
we further distinguish between two forms of navigational and session 
state state (and enduring state for that matter).  State that is opaque 
to the consumer (and merely managed by it) and state that is exposed to 
the consumer which then has the opportunity to impact it .

Section 3.10: Consumer Mediated Coordination
Completely rewrite item 2) to make it clearer.  E.g.

State Distribution:  this mechanism allows Portlets to expose portions 
of its state which the Consumer can manipulate and/or transfer to other 
Portlets or Consumer constituents.  Each of the two types of state is 
represented; Navigational State and Session State.  (If appropriate at 
this point provide a summary of how each works -- however I currently 
think this is best held until later)

Section 5.1.11/5.1.12: Description for schemaLocation
It would be clearer if we added a sentence indicating this field is used 
when the schemaTypes isn't used/sufficient.

Section 5.1.15: PortletParameter
Why did you remove the second sentence?  I think it adds clarity to 
provide a reference to usage.
Likewise, I think we should add a sentence to "names" indicating that 
these cross-referenceable ids consumers can use to associate common 
portlet parameters in distinct portlets.

Section 5.1.16: PortletDescription
I dislike the name NavigationalPublicValueDescriptions.  I suggest 
either NavigationalParameterDecriptions or merely 
NavigationalStateDescriptions.  If we go with the later we might 
consider renaming SessionPropertyDescriptions to SessionStateDescriptions.

description of NavigationStateDescriptions:
rewrite for clarity. e.g.
This array describes the Portlet's public or exposed navigational state. 
For a more complete description of navigational state see section XXX.  
Each state values is uniquely defined by the identifier field within the 
description. The NavigationalStateDescriptions array MUST NOT contain 
two descriptions with the same name.
[More the rest of the wording related to how consumer's manage this to 
the decription in NavigationalState (NavigationalContext) structure.

description of SessionPropertyDescriptions:
Make similar to above including moving portion related to how consumer 
manages the session properties.

Section 6.1.1:  changedSessionProperties
Last sentence is incomplete (a cut/paste problem?)

Rename SessionContext to SessionResponse for better consistency?

Section 6.1.2: Session Params type
Rename to SessionContext for better consistency?

Expand the summary to clarify public model -- or do this elsewhere?

Section 6.1.12 NavigationalState type
Rename to NavigationalStateContext or merely NavigationalContext for 
better consistency?

Rename opaque field to opaqueValues for better consistency.
Other options for "publicValues": exposedValues, openValues, clearValues.

Expand the summary to clarify public model -- or do this elsewhere?


-Mike-