Re: [wsrp-wsia] [I#179] requestParameter semantics unclear

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

Yes, it looks like we have lost some clarity when we added the ability for
actions to return markup.  However, I don't think this requires we separate
query string and form (post) parameters into separate fields.  As a review, here
is my understanding of what we have been trying to model:

We distinguish between 2 types of state parameters passed to a portlet.  One
type is called navigational state.  The other is interaction state.
Navigational state is the state passed by the consumer to the producer that
allows it to render [over and over again].  I.e. its the "bookmarkable" state
carried by the consumer [and possibly the client].  Interaction state is the
"transient" state utilized in actions to affect change.  I.e. in a simplified
view:
      A blocking action receives interaction parameters and returns navigational
state.  This navigational state is passed to the subsequent getMarkup (and
follow-on rerenders), but the interaction parameters are not.
      A non-blocking action receives interaction parameters but isn't allowed to
alter navigational state.  The navigational state passed to the subsequent
getMarkup is the one encoded in the non-blocking action request.  Like the
blocking action, the interaction parameters aren't passed along to the
Getmarkup.
      GetMarkup should only receive navigational state.  Like a non-blocking
action it can't alter/return new navigational state.

Currently, URLs written by the portlet into its markup contain 2 types of
parameters.  Navigational state is encoded by placing such state in the value of
the special parameter "wsrp-navigationalState".  Interaction state is encoded as
extra query string parameters -- i.e. any query string parameters not reserved
by wsrp.  In addition if the URL is the action of a form, the form parameters
are also considered interaction state.

Though I know the bulk of this discussion thread has concerned itself with
[whether or not] to distinguish between interaction state encoded in the query
string vs. as form parameters I think we should really be focusing on properly
distinguishing between navigational state and interaction state.  For example:
    a) Why do we allow a blocking action URL to explicitly carry the
navigational state since a blocking action is now required to return new
navigational state if it wants any?
    b) Why do we allow a render URL to carry extra parameters not in its
navigational state?

A "pure" model based on my descriptions above might work something like this:

A blocking action only encodes interaction parameters -- any previous
navigational state that needs to be passed to the action is represented in
predefined interaction parameters.  If we keep to the current model, these
interaction parameters are signified in the rendered URL as query string
parameters whose names aren't from the reserved list.  Alternatively we could
simplify things and use a interactionState token [ala navigationalState].  The
benefit of doing this alternative is that any portlet specific parameters in the
URLs query string MUST be namespaced while this can be avoided if we hold these
parameters using a reserved name.

When the blocking action is called it receives the parameters in its
InteractionParams data structure.  I.e. though it receives a MarkupParms
structure [so it can render if it wants to], the navigational state in this
structure is NIL [pending the return from the blocking action].  Likewise, as
getMarkup only receives navigational state the current field requestParameters
is removed.  To hold this information in InteractionParams I propose we expand
the structure to hold both binary data and form data.  A field would be added to
distinguish the type of interaction parameters are passed.  When form data, I
would propose all parameters be collapsed into a single parameter array though
we can continue discussing the merits of differentiating between those in the
query string and those in the posted form.

The blocking action processes the action based on the passed parameters and
returns new navigational state [if needed] and if optimized the actual markup.
We leave it up to the portlet/action to properly encode/model this new
navigational state to its optimized getMarkup call.

A non-blocking action encodes both interaction parameters and navigational
state.  The interaction parameters are used during the non-blocking action.  The
navigational state is the predefined state used for the subsequent getMarkups
[as no new navigational state can be returned].  When the non-blocking action is
called it receives the interaction parameters in the InteractionParams data
structure as described above.  In addition it receives the navigational state in
the MarkupParams structure.

Finally, the render [getMarkup] only deals with navigational state.  Thus only
navigational state can be represented in generated render URLs.  Likewise
getMarkup only receives the MarkupParams structure.

        -Mike-