Just to clarify -- some simple use cases:
wsrp:consumerRequest:
This scope allows a portlet to transmit state for the duration of a
request. It is most commonly used for portlet private data but can be
used for coordination. Having this scope allows one to implement JSR
168 set/getAttribute that spans the full lifecycle action, events,
render. Another use case is supporting request scoped managed beans in
a Faces bridge that relies on JSF to implement the portlet.
You are correct its not intended to maintain render state as such data
is lost on subsequent replays. However it is useful for caching
state/context that pertains to this lifecycle so it doesn't have to be
recomputed/regenerated. If coded carefully, you also get additional
benefit of state being removed automatically as it goes out of scope.
wsrp:consumerSession:
This scope allows a portlet to transmit data for the duration of the
consumer session. Its used/preferred when the portlet wants state
coordination to span > then a single page. I.e.
wsrp:navigationalState is commonly [though not restricted to] scope a
single "page"/aggregation in the consumer. This scope allows
coordination with any constituent accessed via the consumer session.
An example might be a set of portlets designed to run on more then 1
page that want to share a common customer Id or such to establish their
initial context.
wsrp:consumerApplication:
This scope sets a context for the entire consumer during its
activation. It allows one to set/coordinate a value for all users
within the current activation. I don't have any particular use case in
mind for this but note that web application models have found it useful
to model and figured we could/should include it for completeness. Yes,
the common usage is to define a shared resource, something that might
not pertain here, but who knows.
As for why the later are settable in a render link:
Yes, state changes most often occur as a result of direct
interaction/events, however representing this capability in a render
link allows us to handle other situations like initialization [when
only rendered but not interacted with], async changes on the producer
either chanegs to the producer itself [upgrade] or its data.
-Mike-
Stefan Hepper wrote:
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.
