Re: [wsrp][wsia][wsrp-wsia joint interfaces][Draft Spec 0.43]

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

I find I am having trouble understanding how different types of producers
fit with the draft API.  I think its likely I need a mental reorientation
so I can become aligned with the current perspective.  So you can
help me,  I have listed below the various APIs I "expect" for each
producer type.  Can you help explain how (or why not) this is reflected
in the draft?  I would also be interested in whether you think some
interface levels to reflect these classes would be useful.
   -Mike-

Type 1: This is the most minimal form of producer I can conceive of:  One that returns a markup fragment.  Information concerning what/how to use this producer are known/discovered elsewhere.
 

(Transient) Stateless:
fragment <- getFragment(consumerCtx, requestData);

(Transient) State:
sessionId <- createSession(consumerCtx);
fragment <- getFragment(consumerCtx, requestData, sessionId);

consumerCtx is information that identifies the consumer.  At its simplest level this allows a producer to log information on a per consumer basis.

requestData is all the information needed by the producer to generate the fragment.

In the stateful case, a createSession exists independent of getFragment so the producer can run in an environment where is can be called concurrently by the same consumer and not have to worry about race conditions associated with establishing the session.

Type 2: extends Type1 by adding the ability for the producer to separate its action handling (data processing) from rendering.
 

(Transient) Stateless:
actionResult <- doAction(consumerCtx, actionId, actionData);
fragment <- getFragment(consumerCtx, requestData);

(Transient) State:
sessionId <- createSession(consumerCtx);
actionResult <- doAction(consumerCtx, actionId, actionData, sessionId);
fragment <- getFragment(consumerCtx, requestData, sessionId);

Type 3:  extends Type 2 (though could also extend Type 1) by making the producer self describing.  (In Type 1 and 2 it is assumed the consumer learns about how to operate the producer (what information to send to getFragment)  elsewhere).
 

(Transient) Stateless:
description <- describe(consumerCtx);
actionResult <- doAction(consumerCtx, actionId, actionData);
fragment <- getFragment(consumerCtx, requestData);

(Transient) State:
description <- describe(consumerCtx);
sessionId <- createSession(consumerCtx);
actionResult <- doAction(consumerCtx, actionId, actionData, sessionId);
fragment <- getFragment(consumerCtx, requestData, sessionId);

Type 4: adds the notion of the consumer registering with the producer.  This is provided to give producers a well described point in time when they become known/usable by a specific consumer (instead of inferred from a a given call/side effect).  For simplicity this is depicted as being additive to Type 3 -- though it could be added at/to extend any type.

(Transient) Stateless:
description <- describe(consumerCtx);
description <- describe(regId);
regId <- register(consumerCtx);
actionResult <- doAction(regId, actionId, actionData);
fragment <- getFragment(regId, requestData);

(Transient) State:
description <- describe(consumerCtx);
description <- describe(regId);
regId <- register(consumerCtx);
sessionId <- createSession(regId);
actionResult <- doAction(regId, actionId, actionData, sessionId);
fragment <- getFragment(regId, requestData, sessionId);
 
 

The above seem to be the base API/model.  However in WSRP the producer
is a container for entities that handle actions and return fragments. 
For containers you can likewise describe models from simple to more complex
as I did above.

Type C1: This is the most minimal form of container producer I can conceive of:  One that returns a markup fragment.
 

(Transient) Stateless:
entityId <-createEntity(consumerCtx, parentEntityId);
entityId <- createEntity(consumerCtx, entityType);
fragment <- getFragment(consumerCtx, entityId, requestData);
deleteEntity(consumerCtx, entityId);

(Transient) State:
sessionId <- createSession(consumerCtx);
entityId <-createEntity(consumerCtx, parentEntityId, sessionId);
entityId <- createEntity(consumerCtx, entityType, sessionId);
getFragment(consumerCtx, entityId, requestData, sessionId);
deleteEntity(consumerCtx, entityId, sessionId);

createEntity has two forms.  When entityType is passed a new/default entity is created.  When parentEntityId is passed a new entity is created based on the values of the parent.  As we don't (yet) support a describe() method a negotiation can't occur between the producer and consumer to decide who manages the entity (persistent) data).  To be consistent with sessions (and generally arbitrary) I have the producer manage this -- hence there isn't a createEntity(consumerCtx, parentEntityId, entityDefaults).

session in this model are one session across all entities within a given consumerCtx on a consumer defined basis.  I.e. they decide when to call createSession.  I expect many consumers to adopt/support the http session model hence their usage would be all entities within a given consumerCtx on a per user basis.

On deleteEntity we need to discuss bulk/cascading deletes for performance purposes when a parent hierarchy exists.

Type C2: extends Type C1 by adding the ability for the producer to separate its action handling (data processing) from rendering
 

(Transient) Stateless:
entityId <-createEntity(consumerCtx, parentEntityId);
entityId <- createEntity(consumerCtx, entityType);
fragment <- getFragment(consumerCtx, entityId, requestData);
actionResult <- doAction(consumerCtx, entityId, actionId, actionData);
deleteEntity(consumerCtx, entityId);

(Transient) State:
sessionId <- createSession(consumerCtx);
entityId <-createEntity(consumerCtx, parentEntityId, sessionId);
entityId <- createEntity(consumerCtx, entityType, sessionId);
getFragment(consumerCtx, entityId, requestData, sessionId);
actionResult <- doAction(consumerCtx, entityId, actionId, actionData, sessionId);
deleteEntity(consumerCtx, entityId, sessionId);

Type C3:  extends Type C2 (though could also extend Type 1) by making the producer self describing.  (In Type C1 and C2 it is assumed the consumer learns about how to operate the producer (what information to send to getFragment)  elsewhere).
 

(Transient) Stateless:
description <- describe(consumerCtx);
entityId <-createEntity(consumerCtx, parentEntityId);
entityId <- createEntity(consumerCtx, entityType);
fragment <- getFragment(consumerCtx, entityId, requestData);
actionResult <- doAction(consumerCtx, entityId, actionId, actionData);
deleteEntity(consumerCtx, entityId);

(Transient) State:
description <- describe(consumerCtx);
sessionId <- createSession(consumerCtx);
entityId <-createEntity(consumerCtx, parentEntityId, sessionId);
entityId <- createEntity(consumerCtx, entityType, sessionId);
getFragment(consumerCtx, entityId, requestData, sessionId);
actionResult <- doAction(consumerCtx, entityId, actionId, actionData, sessionId);
deleteEntity(consumerCtx, entityId, sessionId);

Type 4: adds the notion of the consumer registering with the producer.  This is provided to give producers a well described point in time when they become known/usable by a specific consumer (instead of inferred from a a given call/side effect).  For simplicity this is depicted as being additive to Type 3 -- though it could be added at/to extend any type.
 

(Transient) Stateless:
description <- describe(consumerCtx);
description <- describe(regId);
regId <- register(regId);
entityId <-createEntity(regId, parentEntityId);
entityId <- createEntity(regId, entityType);
fragment <- getFragment(regId, entityId, requestData);
actionResult <- doAction(regId, entityId, actionId, actionData);
deleteEntity(regId, entityId);

(Transient) State:
description <- describe(consumerCtx);
description <- describe(regId);
regId <- register(consumerCtx);
sessionId <- createSession(regId);
entityId <-createEntity(regId, parentEntityId, sessionId);
entityId <- createEntity(regId, entityType, sessionId);
getFragment(regId, entityId, requestData, sessionId);
actionResult <- doAction(regId, entityId, actionId, actionData, sessionId);
deleteEntity(regId, entityId, sessionId);