Data oriented use case

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

Well I finally have an early draft pulling together some of my thoughts. 
 Its attached.  If possible please review before tomorrow's concall as 
we may spend some time discussing it.
       -Mike-

Title: Data oriented use case

A data-oriented coordination use case:

Most of the current discussion in the Coordination subcomittee has focused
on inter-portlet coordination; the ability for one portlet to communicate
changes and affect another.  A different style of coordination focuses
on the end user or the consumer being the instigator of coordination and/or
changes.  This document lays out a basic use case to illustrate this
alternative coordination style.

Imagine a portal page that contains a weather portlet, a restaurant locator
portlet, and a tv guide portlet.  Each of these portlets is designed
to be sensitive to a postal [zip] code.  The weather portlet shows the
current weather and a near term forecast for a given postal code. The restaurant
locator portlet shows a list of rated restaurants [within a given food style]
with links to reviews within a radius defined by a postal code.  And
finally the tv guide portlet lists todays prime time broadcasts for the locale
definded by the postal code.  The page designer wants to implement 1
or more of the following behaviors:

1. Portlet on page establishes page context:
   A mechanism for the end user to set the current postal code for this page from within the page itself.  I.e. a fourth portlet that allows the end user to fill in a field with the new postal code.  Submitting this value causes all portlets on the page to acquire this information so they can render using the new context.
2. End-user/client establishes page context:
   A mechanism for the end user to set the current current postal code for this page in the request they send to receive the page.  I.e. The postal code can be included in the request parameters of the page so an end user can generate an explicit request or use a bookmark.  Note: This use case doesn't require the postal code context portlet described in (1).  I.e. it allows for consumers to provide this behavior without using an intermediary portlet to drive the context change.  
3. Profile information used by consumer to establish context:
   The consumer pulls the postal code from the user profile and passes it as a basis of the context.
4. The consumer's page mechanism provides a facility for setting this context:
   The consumer uses a "default" postal code set up by the page designer for this page.
   
5. A consumer's page link establishes this context:
   The consumer provides a page link from the users home page to this page.  This link contains the postal code context appropriate for the current user [not important how the consumer comes to know this value, merely that it includes it in a page link so it will be used as the context.  I.e. its similar to (2).

Solving the use cases with events:
Here is a possible solution to each of these use cases using our currently
defined event mechanism (to illustrate the most complicated cases I assume
that none of the portlets were designed/had preknowledge of the other portlets]:

1. Portlet on page establishes page context:
   This may be the most natural fit for our eventing mechanism.  The submit button on the postal code portlet fires a BlockingInteraction.  In this BlockingInteraction, the postal code portlet first sets the new code in its navigational state and then fires a PCP.PostalCodeChanged event including the new postal code in the payload of the event.  The consumer's page mechanism has provided a design facility for wiring generated events to consumable events.  In this case each of the three recipient portlets has a distinct [self] defined event [thePortletsNamespace.PostalCodeChanged].  Each of these events takes a payload of a single parameter, the new postal code.  The page designer has wired the PCP.PostalCodeChanged event to each of these three portlets consumable events.  When PCP.PostalCodeChanged fires [on the return of the PerformBlockingInteraction], each of these three portlets receives their respective mapped events with the new postal codes.  Each updates its navigational state and returns.  No new events are generated.  Finally, the page renders.  As the new postal code has been stored in the navigational state of each portlet, we get the desired behavior.
2. End-user/client establishes page context:
   This use case requires a facility that allows the end-user/client to pass the new postal code context in an URL parameter.  As its difficult for an end user to address a particular portlet within a page since multi instances of the same portlet can exist on a page I assume here that the consumer provides a page mechanism that allows a page developer to define a "page parameter" and then map this page parameter to portlet inputs.  The a default value is preset for the "page parameter" when its defined by the page developer.  This is the value used if a page request doesn't contain a new [override] value in the request URL.  For example I [the page developer] would define a page parameter for postal code and preset/default this value to 94065 [the corporate headquarters postal code].  A user wishing to set this parameter to 94025 would merely add the postal_code parameter into the query string with the new value.
   
   To implement this using events I assume that the consumer's page parameter mechanism maps the page parameter to a specific portlet event.  In this case the postal_code parameter woudl be mapped to each of the portlet's PostalCodeChanged event with the postal code carried as the payload.  In the situation that the postal code is passed by the end-user as part of the query string the consumer/page would construct and send the appropriate events with the new postal code to each of the portlets.  Each portlet would update its navigational state in its event handler which would be used in subsequent renders to render the right context. In the situation that no postal code is passed in the URL the page [parameter] mechanism would have to detect whether this a postal code event has been already been sent [from a previous access] and the navigational state/portlet session state is still in context so it would know not to generate a new event with the "default" value or whether to post the event.  In the later case it works as if the user had sent the postal code except the value is the page designers default.
   
   
3. Profile establishes page context
   This works in the same way that handling the default value in (2) does except the value is read from the users profile vs. is managed by the page directly.  Most notably, the page/consumer has to determine whether this value has previously been sent and still in context [via navigational state or session] vs. needs to be sent.  I.e. for performance reasons we don't send the event every time.
   
   
4. The consumer's page mechanism provides a facility for setting this context:
   This was covered in (2) above.
   
   
5. A consumer's page link establishes this context:
   This is similar to the situation where the end user passes the new value in the query string.  The only difference is that this value/URL is constructed by the consumer in one of its page representations. 

On the surface, at least, it appears that our event mechanism is sufficient
to cover these use cases.  However there is some inefficiencies/awkwardness:

1. To avoid excessive eventing [i.e. per redisplay] a number of scenarios above requires the consumer must correctly determine if a default/looked up value should be posted or whether its safe to assume that the portlet state generated as a result of a previous posting is still valid.
2. Setting the state via an event uses two roundtrips.  [Though this is somewhat ameliorated if we allow the producer to optimize and return a rendering from the event handler though it should be noted that in the case the value is passed in a request parameter (1), (2), and (5) many consumers will redirect after eventing to clear the request [parameters] so subsequent redisplays don't cause the eventing to fire again.
3. When the page supports the type of page parameter mapping discussed above, users are exposed to the familiar value as data parameters in an URL and event mapping.  I.e. they must think about mapping URL parameters to events and event payloads.  

An alternative to the above [for discussion] is to allow portlets to declare
"public" render parameters.  I.e. additional parameters that consumers
can send when making a portlet render request to qualify the rendition.  Consumers
would still [likely] need to support a notion of page parameters to avoid
the per instance namign problem.  I.e. the page parameter becomes the
page's public render parameter and this is mapped by the page to the portlet's
public render parameter.  Supporting this type of mechanism overcomes
some of the inefficienies/awkwardness cited above.  Namely,

1. Because this value is passed as part of the render context and therefore is not retained by the portlet in its internal render state the consumer no longer has to track whether it should generate an event to set the current/initial value vs. merely rely on the producer to render from state it set up from a previous eventing.  I.e. the consumer always passes what it considers the current value vs. determining that current value is known and hence it can skip generating the event.
2. Because this is part of the render context it never requires two round trips as no eventing is involved [for page parameters].
3. Users see a single model: page parameters are mapped to portlet parameters.

Note:  For this last discussion I am still assuming that scenario (1)
a portlet driving other portlets would continue to work via eventing.  The
one difference is that a consumer would have the ability to map the payload
of an event to portlet render parameters in addition to mapping to portlet
consumable events.