Session Properties were removed from wd18 as the consensus was that they did not offer a clean enough model to warrant including in v2. It was also pointed out that nearly equivalent functionality could be done simply be leveraging the event model. This proposal seeks to capture what had been in this feature and recast it either as an extension or a well-defined mapping to events.

Session Properties

The Session Property model extends the portlet session by declaring to the Consumer a portion of the items the Portlet stores in its portlet session. The Consumer is informed when the value for any of these items changes (including instantiation and removal) and is able to set the value for these items.

1. Distinct Property notifications

In this variant of the proposal, a variety of WSRP types are extended to transport the session property values and metadata between the Producer and Consumer. The relevant ExtensionDescription is:

<ExtensionDescription> 
  <name>wsrp:sessionProperty</name>
  <parts>
    <type>wsrp:PropertyDescription</type>
    <schemaLocation>...</schemaLocation>
    <extendedTypes>PortletDescription</extendedTypes>
  </parts>
  <parts>
    <type>wsrp:Property</type>
    <schemaLocation>...</schemaLocation>
    <extendedTypes>SessionContext</extendedTypes>
    <extendedTypes>SessionParams</extendedTypes>
  </parts>
  <description xml:lang="en" resourceName="wsrp:sessionPropertyDescription">
    <value>This extension allows Portlets to expose items from 
           their portlet session, whose values the Consumer can 
           then coordinate with other Portlets.
    </value>
  </description>
</ExtensionDescription>

Semantics
Portlets inform Consumers that certain items are available for it to coordinate with other Portlets by describing those items using the PropertyDescription structure. An array of these can appear as extensions to the PortletDescription structure. Regardless of what is set within the capabilities field of these descriptions, sessionProperties are always optional as it is a Consumer decision whether or not to coordinate a particular sessionProperty with other Portlets.

Consumers can supply a new value for a sessionProperty by including a Property matching the name as an extension of the SessionParams structure. If a Property is so named without a value being supplied, the Consumer is indicating a desire to clear that property.

Portlets indicate which of their sessionProperties changed value (including by being added to the session) as a result of processing a request by returning those items as extensions to the SessionContext structure. If a Property is included without a value being supplied, the Portlet is indicating the property's value was cleared (possibly by the property being removed).

Since the SessionContext structure can be returned in a GetMarkupResponse, special care has to taken to handle any returned sessionProperties in a manner that keeps the set of Portlets synchronized in the manner expected by the End-User. The Consumer MUST retain these updates for distribution to other Portlets on the next user interaction.

Issues/Resolution

Synchronizing new participants (due to new wiring, new sessionID, InvalidSessionFault or InvalidCookieFault).
Is there significant enough value to require Consumer maintain updates between subsequent pass through the 3-phase lifecycle?

2. Mapping to events

In this variant of the proposal, WSRP events are leveraged to transport the session property values between the Producer and Consumer. The Consumer is not informed the events transport session property values and treats them in the same manner as any other events.

Semantics
The portlet declares support for events matching the QName of each session property they are sharing. A read-only property is declared only in the publishedEvents field of the PortletDescription while read-write properties are declared in both the publishedEvents and handledEvents fields.

Issues/Resolution

Synchronizing new participants (due to new wiring, new sessionID, InvalidSessionFault or InvalidCookieFault).
Possible resolutions:
- wsrp:modifiedCoordinationContext event: Consumer generated event sent to all portlets already in the Consumer-defined coordination context. Examples of such a modification include establishing additional event wiring and a Portlet involved in the event wiring establishing a new session. Portlets would generate whatever events they desire to assist the new participant(s) to become aware of what state the other portlets are rendering for the End-User (e.g. initialization events, shared session properties). The Consumer should only distribute the returned events to the new participant(s) and may filter the set of returned events to remove duplicates.
  - MF: As there is no formal concept of Session Properties here -- there are merely some events that happen to have the semantic concerning such state, how does the consumer know that this event should be raised? I.e. why send this event if the circumstance doesn't exist?
    RT: Perhaps using a defined event (wsrp:sessionPropertyChanged) to carry updates would introduce the concept of session properties within the spec as well as making it known to the Consumer when such properties are being distributed. The Portlet's metadata would then need to describe its public session properties (See #4 below).
Delayed distribution of session properties changed in getMarkup.
Possible resolutions:
- Add a flag to GetMarkupResponse indicating queue of events exist at the Producer (could be for async reasons as well) and a Consumer-generated event that is just a ping.
  - Interfaces SC: The semantics of requesting the ping event would need to explicitly state that requesting the ping does not guarantee the next invocation will be handleEvents with the ping event. In other words, it is a request of the Consumer and not a demand for a particular response.
- Strengthen the language discouraging the changing of session state during getMarkup.

[Subbu] In theory the resolutions might solve the issues, but the number of roundtrips involved would likely discourage consumers from implementing this approach.

3. Consumer hosted Shared Session

In this variant of the proposal, the Consumer hosts a shared session. Portlets declare their shared session properties and Consumer map these to either private or shared portions of the session. A variety of WSRP types are extended to transport the session property values and metadata between the Producer and Consumer. The relevant ExtensionDescription is:

<ExtensionDescription> 
  <name>wsrp:sessionProperty</name>
  <parts>
    <type>wsrp:PropertyDescription</type>
    <schemaLocation>...</schemaLocation>
    <extendedTypes>PortletDescription</extendedTypes>
  </parts>
  <parts>
    <type>wsrp:Property</type>
    <schemaLocation>...</schemaLocation>
    <extendedTypes>SessionContext</extendedTypes>
    <extendedTypes>SessionParams</extendedTypes>
  </parts>
  <description xml:lang="en" resourceName="wsrp:sessionPropertyDescription">
    <value>This extension allows Portlets to expose items from 
           their portlet session, whose values the Consumer can 
           then coordinate with other Portlets.
    </value>
  </description>
</ExtensionDescription>

Semantics
Portlets inform Consumers that certain items will use the Consumer-hosted shared session and are available for coordination with other Portlets by describing those items using the PropertyDescription structure. An array of these can appear as extensions to the PortletDescription structure. The Consumer decides which of these items are coordinated with other portlets by choosing to map them into either private or shared portions of a session. The Consumer sends all shared session properties which have a value on each request receiving a SessionParams structure. Portlets/Producers do not maintain a copy of these values as they are resupplied on each request.

Portlets can supply new values for their shared sessionProperties by returning those items as extensions to the SessionContext structure. If a Property is included without a value being supplied, the Portlet is requesting the property be removed from the shared session. Portlets may return sessionProperties which were not described in their PortletDescription (these are called dynamic session properties), but it is less likely these dynamic session properties will be participate in state-oriented coordination with other Portlets. Consumer are required to resupply to the Portlet any dynamic session properties in the same manner as it supplies the session properties declared in the PortletDescription.

Issues/Resolution

Partial distribution of session properties which are changed in GetMarkupResponse.
Is there enough value to require Consumer support (with attendant open-ended impacts on memory usage)? If Consumers aren't required to support the shared session, would any portlet developers use it?

[Subbu] If the feature is not guaranteed to work consistently, it is less likely to get implemented and used. Given that memory is cheaper than network roundtrips, I don't see how shared session properties would perform without requiring consumer to host a shared session.

[Subbu] We could also let consumers to send only those session properties that it considers dirty.

4. Leverage a defined set of events

In this variant of the proposal, WSRP events are leveraged to transport the session property values between the Producer and Consumer. The specification defines an event for carrying changed values and metadata informing the Consumer of the Portlet's publicly accessible session properties.

Semantics
The specification defines a wsrp:sessionPropertyChanged event with the fields:

[R] QName propertyName
[O] QName propertyType
[O] URI schemaLocation
[O] EventPayload payload

A missing payload has the semantic meaning that the property has been cleared (including removed). The purpose of the propertyType and schemaLocation fields is to assist anyone who receives the event in deserializing it appropriately while the propertyName field carries both the identity and semantics of the property.

The portlet's metadata carries an array of PropertyDescription structures to describe the session properties it is exposing to the Consumer. While the usage field in each description carries information regarding Consumer access (e.g. wsrp:nonmodifiable), it is an error to specify a usage value of wsrp:required.

The specification defines a wsrp:modifiedCoordinationContext event with no defined fields, but an open content model. This is a Consumer generated event which is sent to all portlets already in a Consumer-defined coordination context when membership in that context changes. Examples of such modifications include establishing additional event wiring and a Portlet involved in the event wiring establishing a new session. Upon receiving this event, Portlets generate whatever events they desire to assist the new participant(s) to become aware of what coordinated state is being rendered for the End-User (e.g. initialization events, shared session properties), including a wsrp:sessionPropertyChanged event for each publicly exposed session property which currently has a value. The Consumer should only distribute the returned events to the new participant(s) and may filter the set of returned events to remove duplicates.

Some of the technologies leveraged to implement a WSRP Producer will allow Portlets to modify their session properties while processing a getMarkup request. There is no means for the Producer to return events in a GetMarkupResponse and these will therefore need to be queued for transmission to the Consumer in the response to the next performBlockingInteraction or handleEvents request. To enable Portlets to indicate this situation (or any others which cause of queueing of events on the Producer), a optional requestPing field (boolean with a default value of false) is added to GetMarkupResponse and its semantics defined to be the Portlet requesting the Consumer send it a wsrp:ping event on its next pass through the protocol's three phase lifecycle. For various reasons, the Consumer might delay the actual sending of the wsrp:ping event and any dependency a Portlet has on receiving the event as the next invocation after requesting it is an error.

The specification defines a wsrp:ping event with no defined fields, but an open content model. This is a Consumer generated event which is sent to Portlets to allow any relevant or deferred event processing (including returning queued events).

Issues/Resolution

[Stefan] In order to make this really work the events for participants of a coordination context need to be guaranteed. The participants of a coordination context must be able to rely on getting a modifiedCoordinationContext or ping event as otherwise the session semantic will be broken and the user experience will not be the one of a shared session.
[Rich] I can read several variants into your comments:
1. For the distributed session concept to work, the Consumer has to reliably distribute the wsrp:sessionPropertyChanged events to the Portlets within the coordination context it is defining. While this is true, I'm not sure the spec would need to explicit comment on it as it is the Consumer who both determines the breadth and quality of the coordination context.
2. Since Producers could be queueing events, reliability is needed on the requestPing actually generating a wsrp:ping event at some point. While I think this is generally true, I'm not sure we can make this a hard requirement on the Consumer as the next user action could easily be closing their browser (or jumping to a different page, etc).
Possible resolutions: