Navigational Parameters and Transient Properties

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

Attached are two separate proposals.  Navigational Parameters are an updated proposal to what we have been referring to as Public Parameters.  Transient properties is a new proposal for supporting consumer managed transient state.  At least weeks Interfaces call we decided to keep these two concepts separate, hence the 2 proposals.  Each will be the subject of discussion/resolution at the upcoming F2F.  These proposals can also be found in the Interfaces Documents repository:
Navigational_Parameters.html
Transient_Properties.html
      -Mike-

Title: Navigational Parameters

NavigationalParameters

Summary:

NavigationalParameters are public parameters a portlet exposes to augment/influence
elements of its opaque navigational state.  A portlet's navigational
state is one of the state management facilities provided by wsrp.  This
mechanism allows a portlet to run statelessly; the portlet's state is represented
by an opaque entity and offloaded to the consumer.  Furthermore, because
navigational state is explicitly designed to model bookmarking and other
like web operations; its expected that many consumers will offload this state
all the way back to the client by representing it in [future] request parameters.
 

Being opaque, the only entity that can impact navigational state is the portlet
itself.  However, there are a wide variety of use cases where the portlet
desires to allow external influences of this state.  Examples include
clients setting a value directly, the consumer computing a value, or another
portlet coordinating its value.  NavigationalParameters provides this
mechanism.

A NavigationalParameter defines a portlet input.  Like navigational
state, NavigationalParameters are passed on all request lifecyle calls [performBlockingInteraction,
handleEvents, getMarkup].  A NavigationalParameter's value augments
the portlet's navigational state.  In its simpliest form, this takes
the form of replace [being used instead of].  For example a portlet
might have a navigational state field holding a customer ID.  The portlet
may also define a navigational parameter customer ID.  If a navigational
parameter for customer ID is sent in the request, the portlet would use it
vs. the one stored in its navigational state.  Whether or if a portlet
decides that a navigational parameter value should actually update its navigational
state is entirely up to the portlet.  From the consumer's perspective
navigational parameters should always be resupplied when it wants the portlet
to be influenced by it.  It shoudl never expect/assume that the portlet
has retained this value in its navigational state or otherwise.

To facilitate coordination via  "auto-wiring' by the consumer between
multiple portlets navigational parameters are identified by QNames.  Consumers
should consider portlets having the same navigational parameter QName as
expressing an interest for each to recieve the same value when submitted.

Because we forsee navgiational parameters being used by portlets to facilate
coordination, it is also necessary to define how a portlet can specify a
value for a navigational parameter that the consumer sends.  These value
can be encoded either directly in the response from performBlockingInteraction
or handleEvents or toeknized within URLs written during getMarkup().

Detailed Descriptions:

PortletDescription
    [R] Handle           
 portletHandle
    [R] MarkupType         markupTypes[]
    [O] ID           
     groupID
    [O] LocalizedString    description
    [O] LocalizedString    shortTitle
    [O] LocalizedString    title
    [O] LocalizedString    displayName
    [O] LocalizedString    keywords[]
    [O] ID           
     portletID
    [O] QName           
  publishedEvents[]
    [O] QName           
  handledEvents[]
    [O] ModelDescription   navigationalParameterDescriptions
    [O] string            
userCategories[]
    [O] string            
userProfileItems[]
    [O] boolean           
usesMethodGet
    [O] boolean           
defaultMarkupSecure
    [O] boolean           
onlySecure
    [O] boolean           
userContextStoredInSession
    [O] boolean           
templatesStoredInSession
    [O] boolean           
hasUserSpecificState
    [O] boolean           
doesUrlTemplateProcessing
    [O] Extension          
extensions[]


navigationStateDescriptions: Descriptions for the items a Portlet
wishes to receive as navigationalParameters. While navigationalParameterDescriptions
reuse the PropertyDescription type, it is always a Consumer choice to supply
them on a particular invocation. When a Consumer does not supply a value
for a particular navgiationalParameter, the Portlet should defer to its navigational
state, some other retained state, or use a default value. As such, regardless
of the values in the PropertyDescription‘s capabilities field, navigationalParameters
are always modifiable and optional. While Consumer policy governs what navigationalparameters
are supplied to each invocation of a Portlet, Consumers SHOULD supply the
same value to Portlets which are related to distinct POP handles and provide
a navigationalParameterDescription referencing the same QName. The context
in which the Consumer is using Portlets related to the same POP handle will
determine whether or not such Portlets will share the same values for their
public parameters.


 RuntimeContext
    [R] string        userAuthentication
    [O] Key           portletInstanceKey
    [O] string        namespacePrefix
    [O] string        interactionFieldPrefix
    [O] Templates     templates
    [O] ID           
sessionID
    [O] Property      navigationalParameters[]
    [O] Extension     extensions[]


navigationalParameters: These are Consumer supplied data values used
to augment a Portlet's navigational state.  They are supplied to the
the Portlet on each invocation. The Portlet indicates the items it wishes
to receive in its portletDescription and the Consumer supplies whichever
of the requested items it chooses, with values taken from whatever source
it chooses. Examples include a zipcode item taken from the user’s profile,
but later updated based on information extracted from an event a Portlet
has generated. In general, Portlets do not store the navigational parameter
values in any portion of their state as the Consumer supplies values on each
invocation. Incorrect results will frequently result if a Portlet stores
supplied values within one of the types of state it manages. In the absence
of a Consumer supplied value for a navigational parameter the Portlet listed
in its portletDescription, the Portlet SHOULD defer to its navigational state,
some other retained state, or use a default value.


On portlets setting a value for navigational parameters:
[The following is copied from Rich's proposal sent in the following e-mail
[with ensuing discussion]:

 On URLs:
(2 issues) 
 1. Need to encode 3 pieces of information (request to set a PP, the PPname 
and the PPvalue) into 2 places (name=value) when using a querystring and deal
with the reduced set of characters allowed in the path portion ('=' is not
allowed). Templates also introduce an issue with how to encode multiple PPs
... preferably with the Template only having a single placeholder. 
 -Proposal: 
 1. All public parameters specified on a URL are concatenated in the form 
of "PPname1=PPvalue1&PPname2=PPvalue2". 
 2. The resulting string is URL encoded (changes '=' into %3D and '&' 
into %26) to make it valid in both the querystring and path portions of a
URL.
 3. This URL encoded string becomes the value for the wsrp-publicParameter 
URL parameter, regardless of whether template processing or Consumer URL rewriting
is in use. 
 
 2. How to encode complex PPvalues? I suggest serializing the PPvalue to XML
and URL encoding this XML. The Consumer would then receive the PP, recognize
it is of a complex type (based on PPname) and decode the PPvalue to get the
XML. 
 
 On Operation responses: 
 1. Return PP requests via a field much as newMode and newWindowState request 
updates to those aspects of Consumer managed state. Suggest this field be
of type QNamedStringArray, though it could be an array of NamedString if
we do not want to introduce a usage of a type from the 'extra' namespace.

Title: Transient Properties

Transient Properties

Definitions:

  Transient Property:  a piece of shared consumer managed state with 
a defined-persistent lifetime declared by the producer and supplied to that 
producer in all non-initialalization calls in its Markup port.  Such
properties are designed for and primarily used for coordinating between consumer
components.

Summary

  Transient properties:

• a piece of shared ... state: the property can be set/received by any constituent of the consumer including the declaring portlet.
  
• are consumer managed state:  the consumer maintains the property and supplies it to the producer at appropriate times.
• have a defined non-persistent lifetime:  lifetimes are defined by scope (names).  The following names are reserved/predefined: wsrp:consumerRequest, wsrp:consumerSession, and wsrp:consumerApplication. [To fit into our existing declarative model we will also need wsrp:persistent and wsrp:registration, though these don't pertain to transient properties; see below for details]
  
• are declared by the producer:  the basic declaration includes a name, type, suggested default,  and preferred scope.
• supplied to that producer on all non-initalization call in its Markup port: values for each property declared by that portlet and maintained by the consumer are sent on each invocation of PerformBlockingInteraction(), HandleEvents(), GetMarkup(), and GetResource().
• Such properties are designed for and primarily used for coordinating between consumer components.
  

  Scopes:

• wsrp:consumerRequest:  in this scope the property is maintained for the lifetime of the consumer request.  I.e. one pass through our 3-step protocol.  This enables data management within a single request lifecycle [something not currently doable in WSRP 1.0] .  Though this scope can be used for intra-lifecycle coordination its most likely used by the portlet itself to support/manage such a notion of scope in itself.  
• wsrp:consumerSession: in this scope the property is maintained for the lifetime as the consumers client/end-user session.
• wsrp:consumerApplication: in this scope the property is maintained for the lifetime that the consumer itself is active.

  How they work:

• TransientProperties are declared in PortletDescription [though described in ServiceDescription].
• The preferredScope signifies the portlet's desired scope.  Consumers are the (final) arbitor of scopes.  Its picks the scope based on its own policies influenced by the portlet's stated preferred scope.  It is allowed to move an existing property to a different scope, again based on its own policies as influenced by new references to the same property.
• The consumer uses the declaration to create/manage the property.  The property qname identifies the property.  Because transient properties are designed for coordination, Consumers are strongly encouraged to recognize identical name/type declarations from different portlets as declaring the same property as properties are commonly used for data coordination.  In such a case only one transient property is maintained and its value is shared between all declaring parties.  
  
• The consumer passes the property name, value, and current scope on each invocation of the PerformBlockingInteraction, HandleEvents, GetMarkup, and GetResource when that property has a non-null value.  When a property is out of scope it is has a null value.
• The producer uses the property values as it sees fit.  The producer recognizes the absence of a passed property as an indication that the properties value is null, or it is out of scope [these two things aer equivalent].
• The producer/portlet can set a property value in the response from a PerformBlockingInteraction and HandleEvents.

Details:

PropertyDescription:

> change to:
>     PropertyDescription
>      [R] QName        name
>      [R] QName        type
>        [O] string       preferredScope
>      [O] Property     default
>      [O] LocalizedString    label
>      [O] LocalizedString    hint
>      [O] string        capabilities[]
>      [O] Extension        extensions[]
>    
>  from:
>     PropertyDescription
>       [R] QName        name
>       [R] QName        type
>       [O] LocalizedString    label
>       [O] LocalizedString    hint
>       [O] string        capabilities[]
>       [O] Extension        extensions[]
>    
>  
 Discussion:
 I added the preferredScope and default fields into PropertyDsecription because
a ModelDescription must be used to define the set of transient properties. 
 The way we have defined ModelDescription requires everything be in PropertyDescription.
 These fields are optional.  The set of predefined scopes are:
 
> wsrp:consumerRequest:  duration of a single client/consumer 
> request
>  wsrp:consumerSession: duration of consumer's user session
>  wsrp:consumerApplication: duration of active consumer. 
>  wsrp:persistent: duration is persistent across consumer activations.
>  wsrp:registration: duration of this registration
>    
>  The default preferred scope value is based on the context of the description.
>  For registration properties its wsrp:registration [this is the only
> valid value].  For a portlet's properties its wsrp:persistent [again
> this is the only valid value].  In the case of transient properties its
> wsrp:consumerRequest.
>    
>

PortletDescription:

> change to:
>     PortletDescription
>      [R] Handle            
> portletHandle
>      [R] MarkupType        markupTypes[]
>      [O] ID            
>     groupID
>      [O] LocalizedString        
> description
>      [O] LocalizedString        
> shortTitle
>      [O] LocalizedString        
> title
>      [O] LocalizedString        
> displayName
>      [O] LocalizedString        
> keywords[]
>      [O] ID            
>     portletID
>      [O] QName            
> publishedEvents[]
>      [O] QName            
> handledEvents[]
>        [O] ModelDescription     transientPropertyDescriptions
>       [O] ModelDescription   navigationalParameterDescriptions
>      [O] string             
> userCategories[]
>      [O] string             
> userProfileItems[]
>      [O] boolean            
> usesMethodGet
>      [O] boolean            
> defaultMarkupSecure
>      [O] boolean            
> onlySecure
>      [O] boolean            
> userContextStoredInSession
>      [O] boolean            
> templatesStoredInSession
>      [O] boolean            
> hasUserSpecificState
>      [O] boolean            
> doesUrlTemplateProcessing
>      [O] Extension            
> extensions[]
>    
>  from:
>    
>     PortletDescription
>      [R] Handle            
> portletHandle
>      [R] MarkupType        markupTypes[]
>      [O] ID            
>     groupID
>      [O] LocalizedString        
> description
>      [O] LocalizedString        
> shortTitle
>      [O] LocalizedString        
> title
>      [O] LocalizedString        
> displayName
>      [O] LocalizedString        
> keywords[]
>      [O] ID            
>     portletID
>      [O] QName            
> publishedEvents[]
>      [O] QName            
> handledEvents[]
>        [O] ModelDescription   navigationalParameterDescriptions
>      [O] string             
> userCategories[]
>      [O] string             
> userProfileItems[]
>      [O] boolean            
> usesMethodGet
>      [O] boolean            
> defaultMarkupSecure
>      [O] boolean            
> onlySecure
>      [O] boolean            
> userContextStoredInSession
>      [O] boolean            
> templatesStoredInSession
>      [O] boolean            
> hasUserSpecificState
>      [O] boolean            
> doesUrlTemplateProcessing
>      [O] Extension            
> extensions[]
>    
 
 Property Types:
 
> change to:
>     Property
>      [R] QName    name
>      [O] string    xmlLang
>      [O] Object    value[]
>        [O] string    scope
>    
>  from:
>     Property
>      [R] QName    name
>      [O] string    xmlLang
>      [O] Object    value[]
>  
 Discussion:
 With the addition of transient properties there is now a need/interest in 
representing the [current] scope of a given property .  We require this 
field have a value wphen passing transient roperties otherwise its optional.

RuntimeContext:

> change to:
>    RuntimeContext
>      [R] string        userAuthentication
>      [O] Key        portletInstanceKey
>      [O] string         namespacePrefix
>      [O] string        interactionFieldPrefix
>      [O] Templates        templates
>      [O] ID            
> sessionID
>        [O] Property         
> transientProperties[]
>       [O] Property         navigationalParameters[]
>      [O] Extension        extensions[]
>    
>  from:
>     RuntimeContext
>      [R] string        userAuthentication
>      [O] Key        portletInstanceKey
>      [O] string         namespacePrefix
>      [O] string        interactionFieldPrefix
>      [O] Templates        templates
>      [O] ID            
> sessionID
>        [O] Property         navigationalParameters[]
>      [O] Extension        extensions[]
>    
>