[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]
Subject: [wsrp-interfaces] [wsrp-wsia]: Updated alternative API
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-Title: mike's interface(2) 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
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
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
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]
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
void endScope(ConsumerCtx ctx, Scope scope); // scope is application,
session, entity, or entitySession
.... [aka performAction, describe, setProperties, getProperties]
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
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
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
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.
Powered by eList eXpress LLC