Transient properties

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

Attached is a proposal for supporting transient properties.  You may 
recall that in mid-August we decided to make one last push to see if we 
could define transient properties in 2.0 vs relying on public parameters 
[and needing to retrofit in 3.0].  Please review and comment asap as 
there isn't much time to refine this before needing to make the go/no go 
decision for 2.0.   
   -Mike-

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 (required feature
in 2.0).

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:navigationalState, 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, minimum required scope, 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().
• (required feature in 2.0):  Consumers must support transient properties with at least wsrp:consumerRequest and  wsrp:navigationalState. 

 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:navigationalState: in this aintscope the property is maintained for the same duration as the consumer maintains the portlets' navigationalState.  This enables the coordination at the same level as navigational state is being maintained.  Its introduced  not only because its  reasonable to tie this coordination lifetime to the same lifetime as something that already exists [navigationalState], but also because it should be easy for consumers to do so.
• 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 requiredScope field must come from the set of scopes consumers are required to support [consumerRequest and navigationalState].  The preferredScope field may name any scope including a custom scope.  The requiredScope field must be of equal or lesser scope then the preferredScope.   Note: do we think that WSRP 1.0 adequately defines/requires the ntion of consumerSession scope?  If so we can add this to the list of required scopes.
• The consumer uses the declaration to create/manage the property.  The property qname identifies the property.  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 is free to choose any scope equal to or higher then the scope specified in requiredScope.  The consumer is free to move the property to a different scope at any time as long as it doesn't violate the stated minimums. This later is provided so that when portlets get added to a page at runtime, the consumer can upscope an existing transient property it wants to share.
  
• 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].
• The producer/portlet can set a property value in the response from a PerformBlockingInteraction and HandleEvents and by encoding the action of setting the property in a renderURL.

Details:

PropertyDescription:

> change to:
>    PropertyDescription
>     [R] QName        name
>     [R] QName        type
>       [O] string       preferredScope
>     [O] string       requiredScope
>     [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, requiredScope, 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:navigationalState: duration of navigationalState in this consumer
> 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/required 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] 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     publicParameterDescriptions
> -- removed
>     [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[]
>   
Discussion:
publicParameters were merely transient properties at wsrp:navigationalState.
 To add transientProperties we merely replace the publicParameterDescriptions
field with a transientPropertyDescriptions field.


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 when passing transient properties 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] Extension        extensions[]
>   
> from:
>    RuntimeContext
>     [R] string        userAuthentication
>     [O] Key        portletInstanceKey
>     [O] string         namespacePrefix
>     [O] string        interactionFieldPrefix
>     [O] Templates        templates
>     [O] ID           
> sessionID
>       [O] Property        
> publicParameters[]
>     [O] Extension        extensions[]
>   
Discussion:
Again, to pass transientProperties to performBlockingInteraction, handleEvents,
getMarkup, and getResource, we merely replace the publicParameters field
with a transientProperties field.