Re: [wsrp-wsia]: Updated alternative API

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

Rich,
    Thanks for the comments/questions.  On (2) I have been meaning to ask you about the WSIA use case that needs
the consumer to be aware that the producer session has timed-out.  I have some ideas on "solving" this with the
model I propose but could do a better job if I had a more thorough understanding of what is needed and why.  Can
you explain?
     -Mike-

Rich Thompson wrote:

> 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-
>
> ----------------------------------------------------------------
> To subscribe or unsubscribe from this elist use the subscription
> manager: <http://lists.oasis-open.org/ob/adm.pl>