Re: [wsrp-interfaces] Transient properties

[Stefan Hepper <sthepper@hursley.ibm.com>]

Hi Mike,
could you provide some use cases for these different scopes?

- why would you need a pre client request scope? Isn't that violating 
the MVC pattern where the render should be replayable?

- what is the use case for the consumer session scope? Why would we 
allow to change the consumer session state with a render link?

- same for application scope, why can you modify it with a render link?

Stefan


Michael Freedman wrote:
> 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-
> 
> ------------------------------------------------------------------------
> 
> 
>     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.
>