[wsrp-interfaces] Re: [wsrp-wsia]: Updated alternative API

[Rich Thompson <richt2@us.ibm.com>]

Mike, your proposal raises a variety of questions it will be good to work
through as a group. A large one for me relates to proposing that the
Consumer generate the session key. I see several pros and cons:

Pros:
 - This become implicit session creation with predefined session sharing.
As such it minimizes roundtrips while enabling sharing.

Cons:
 - Pushes complexity related to (re)creation of shared sessions from
Consumer to Producer. I'm not objecting, but we need to explicitly
recognize this.
 - Sessions can be destroyed and recreated without Consumer knowledge. This
involves a major state change and the more advanced WSIA use cases
definitely have the Consumer interested in state changes. Having the design
hide such changes will cause major problems later.

Any thoughts on how the second con can be mitigated?


                                                                                                                     
                      Michael Freedman                                                                               
                      <Michael.Freedman@        To:       interfaces <wsrp-interfaces@lists.oasis-open.org>,         
                      oracle.com>                wsrp-wsia <wsrp-wsia@lists.oasis-open.org>                          
                                                cc:                                                                  
                      06/17/2002 04:16          Subject:  [wsrp-wsia]: Updated alternative API                       
                      PM                                                                                             
                                                                                                                     
                                                                                                                     



The following is an updated version (attached) of the counter-proposal
to draft 0.1.2 I sent last week.  The main changes are the session as
well as the entity references are created/sent by the consumer.  There
is also a new reference for an entity session -- the session
conversation with a specific entity.  Finally, I have simplified the
method signature defining a single ConsumerCtx parameter to hold all the
(potential) references.  There are still alot of details to put in here
so we have a consistent understanding but I though you would like an
early view.  While waiting for these details the key to looking at this
is to think in terms of the consumer vs. the producer.  This API doesn't
represent (many) abstractions as concrete objects in the producer.
Rather, most abstractions are seen as elements/scopes defined by the
consumer that are passed by reference to the producer.  The Producer is
thus freed to represent themselves internally anyway they want to --
merely needing to build a mechanism that maps from these references to
their implementation.
     -Mike-
The following is an updated version of the counter-proposal to draft 0.1.2
I sent last week.  The main changes are the session as well as the entity
references are created/sent by the consumer.  There is also a new reference
for an entity session -- the session conversation with a specific entity.
Finally, I have simplified the method signature defining a single
ConsumerCtx parameter to hold all the (potential) references.  There are
still alot of details to put in here so we have a consistent understanding
but I though you would like an early view.  While waiting for these details
the key to looking at this is to think in terms of the consumer vs. the
producer.  This API doesn't represent (many) abstractions as concrete
objects in the producer.  Rather, most abstractions are seen as
elements/scopes defined by the consumer that are passed by reference to the
producer.  The Producer is thus freed to represent themselves internally
anyway they want to -- merely needing to build a mechanism that maps from
these references to their implementation.


As background here are the terms and their defintions I am using:

      client = an end user


      consumer = an intemediary responsible for the aggregation and control
      of heterogeneous producer services, responsible for the interaction
      between
      the client and the producer services placed on the clients
      application interface.


      producer = a container of producer services.   the WSIA/WSRP
      compliant service.  As consumers are anticipated to be aggregators, a
      producer
      represents 1 or more entity types.


      producer service = the WSIA/WSRP compliant service ( aka. portlet )


      entity type = a specific identifyable consumable function of a
      producer.  Producers publish  its entity types to consumers.
      Consumers reference entity
      types to address its producer requests.


      entity = a consumers particular usage of an entity type.  Consumers
      are anticipated to be aggregators, including aggregating multiple
      distinct
      instances or producer's entity type.  The entity represents each of
      these uses.  From a producer perspective, the entity identifies a
      particular consumer
      usage.  Producers will typically use this ID as a key to per usage
      state.


      reference:  A reference is an ID passed from the consumer to the
      producer to identify something known to consumer but maintained by
      the producer.


      persistence reference:  A reference to persistent state managed by
      the producer.  Typically, a consumer will maintain a persistence
      reference for
      entities.


      conversation reference:  A conversation reference is an ID that
      represents a particular (type of) conversation between the consumer
      and the producer.
      There are 4 converstation IDs:  consumer to producer (application),
      thread of a consumer to a producer (session), consumer to an entity
      (entity), and
      thread of a consumer to an entity (entity session).


      application reference:  A conversation between a consumer and a
      producer.  This conversation spans all consumer runtime use and all
      producer
      entities of this consumer.  For convenience [in making this unique],
      this ID is derived from the consumerID created by the producer during

      regristration.


      session reference:  A subconversation within an application
      conversation between a consumer and a producer.  As such it is a
      shared scope between
      all entities within a given producer that a consumer chooses to group
      together.  This can be all the entities of the producer, a subset of
      entities, and
      even at the extreme one session per entity.  Typically, a
      consumer/producer sessions scope will be tied to a session maintained
      between the client and
      the consumer.


      entity reference:  A conversation between a consumer and a particular
      instance of an entity [type].


      entity session reference:  A conversation within a session with a
      particular instance of an entity [type]


  API:
      ConsumerRef registerConsumer(ConsumerProperties consumer);


      void updateConsumer(ConsumerCtx ctx, ConsumerRef consumer,
      ConsumerProperties consumerData);


      deregisterConsumer(ConsumerCtx, ctx, ConsumerRef consumer)


      PersistenceRef createPersistenceRef(ConsumerCtx ctx,
        PersistenceType type, PersistentProperty[] values);


      PersistenceRef destroyPersistenceRef(ConsumerCtx ctx,
        PersistenceRef ref, boolean cascade);


      FragmentResponse getFragment(ConsumerCtx ctx, FragmentRequestData
        parameters);


      void endScope(ConsumerCtx ctx, Scope scope); // scope is application,

         session, entity, or entitySession


      .... [aka performAction, describe, setProperties, getProperties]




Data:
Note:  we can break this into two or more (heirarchical) data objects if we
need/feel it works better in the API/


public class ConsumerCtx
  {
    private ConsumerRef consumerId;
    private UserIdentify user;
    private SessionRef sessionId;
    private EntityRef entityId;
    private String entityType;
    private EntitySessionRef entitySessionId;
    private PersistenceRef persistenceId; // passed if portlet maintains
data
    private PersistenceProperties persistenceData; // passed if consumer
does
    private PreambleData updateData;  // update the included session or
                   // persistent data before generating the fragment;
  }


  public class FragmentRequestData
  {
    private String charSet;
    private String markupType;
    private String locale;
    private Boolean secureClientCommunications;
    private Property[] headers;
    private Property[] parameters;
    private DeviceInfo clientDevice;
    private Mode producerMode;
  }


  public class FragmentResponse
  {
    Property[] responseProperties;
    String fragment;
    PersistentProperty[] values;
  }



Quick overview of usage:
The producer creates two types of IDs.  One to represent a registered
consumer and one to reference a persistent record it maintains (on request
by the consumer).  The later is not needed/used if the consumer manages the
producers persistent itself (or the producer does not support persistence).
The consumer ID is expected to be unique for all consumers of this
producer.  The consumer subsequently uses this ID (or one derived from it)
as the ConsumerRef in all subsequent calls to identify the caller and to
allow the producer to tie itself to this consumer.  The persistentRef is
passed to all calls where an entity is referenced.


A conversation might go like this:


Note:  In this example a session represents a per user conversation between
a consumer and a producer.  In this situation a SessionRef is sent by the
consumer to the producer for every call below where the consumer is running
within the context of a user.  I.e. a consumer can choose not to send
sessionRefs when it doesn't know/can't identify the user (aka the Public
user).  Question:  is not sending the sessionRef when there is no known
conetxt okay?  or do we force the consumer to always find/have a context?


Operation:  Portal locates and registers a portlet service.
Action:  Consumer calls registerConsumer() to register itself with the
service.  It also calls describe() to get entity information from the
producer.
Result:  Because this is the first call received by the producer since it
has started running, the producer initializes its application scope --
acquiring resources at the application level [It can choose to defer until
an operation needs application data].  Additionally, if a sessionRef is
passed, the producer may choose to [if it needs session data at this point]
to initialize sessionscope. The consumer receives a ConsumerRef from the
producer that it maintains persistently.


Operation:  As a consequence of registration, the portal creates an entity
instance for each entity type in its portlet repository (toolbox).
Action: Portal calls createPersistentRef() for each entity letting the
entity set its default values.
Result:  The consumer (portal) receives a persistent ref that it associates
with the instance it created in the toolbox.


Operation:  Portal developer customizes the portlets settings in the
toolbox.
Action:  Portal calls getFragment with an entityRef it manufactuers to
represent the toolbox instance, the persistenceRef it received from
createPersistenceRef,  mode of Edit -- plus of course the consumerRef,
sessionRef, and the entitySessionRef.
Result: Producer/portlet uses this information to present a screen to the
developer for customizing its settings.



Operation: End-user creates a portlet on a page from a templaet in the
toolbox.
Action:  Portal calls createPersistentRef() to create a new reference for
the page instance.  (The persistenceRef of the toolbox instance is passed
so the values can be inherited.)  After this completes, the Portal calls
getFragment() on passing the new persistenceRef, a new entityRef (for this
new instance), etc.
Result:  Producer/portlet uses this information to present its "show"
screen to the user.


     -Mike-