OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

wsrp-interfaces message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: [wsrp-interfaces] [Fwd: Preliminary review of updated spec]


As promised in this mornings conference call, the following was an
e-mail I sent to Rich last week offering up some ideas for reorganizing
the parameters.  Hidden within this is a suggestion that sessionIDs can
be managed opaquely by the producer as part of the [opaque] entity
state.

As Rich said this morning, he will be using this feedback as well as
others that come in along with his own ideas to work up a new draft.
    -Mike-
--- Begin Message --- Rich,
    Good job getting this updated so quickly.  I think this captures where we left things last week.  As our focus was on capturing the function/concepts rather then refining the definitions I think we have work to do to transform this into a (final) clean API/protocol.  I have included my ideas/comments below as a second draft of the API.  I propose we publish the API as discussed last week as reflected in your document as it starts things where we left off.  Once posted I will send out my proposed refinements and we can begin discussions.  Let me know if this is acceptable or whether you want to incorporate any of this sooner. In any case, I am interested in feedback from all of you concerning these refinements.
   -Mike-

Mike's refinements:
 

Methods:

/**
 *  Unchanged from your specification although I assume we will
 *  flesh out the ConsumerData as its too sparse right now.
 */
[ConsumerHandle] registerConsumer(
        ConsumerData consumer);

/**
 *  No longer returns a ConsumerHandle.  Why do we need to allow
 *  a producer to change this?  It seems to complicate the
 *  implementation and protocol.
 */
void modifyConsumer(
        ConsumerHandle consumer,
        ConsumerData consumerData);

/**
 *  Moved to separate detroy/release methods as each seemed to
 *  require a different signature.  In this case there is no return
 *  value.  Assume success unless an expcetion/fault is thrown.
 */
void deregisterConsumer(
        ConsumerHandle consumer);

/**
 *  All the rest of the methods operate on entities.  All
 *  these methods [except release/destroy] take the same
 *  three initial arguments: ConsumerContext, EntityContext,
 *  and EntityHandle.
 *  Entities run within two contexts supplied by the consumer.  The
 *  ConsumerContext identifies pertinent consumer state for the
 *  entity to run properly.  The EntityContext identities pertinent
 *  entity state managed by the consumer. The EntityHandle
 *  identifies the entity.
 */
 

/**
 *  Creates a new entity based on the existing entity passed in.
 *  EntityContext is passed so the new entity can duplicate
 *  [runtime] state from the existing if it so desires.  Both
 *  a new entity and a new context is returned (for that entity).
 */
[EntityHandle, EntityContext] createEntity(
         ConsumerContext context,
         EntityContext entityContext,
         EntityHandle entity,
         EntityProperty[] values);
/**
 *  Removed modifyEntity -- it seemed redundant with setProperty.
 */

/**
 *  Allows one to destroy a set of entities.  It wasn't clear why
 *  a consumer cares if this succeeds or not -- it seems easier
 *  if the consumer can merely assume all went well.  If we need
 *  to pass back a list of entities actually deleted I would
 *  strongly encourage this only include a [sub]set of the entities
 *  passed in the array.  I don't think the consumer should have to
 *  learn/deal with sideeffects -- other entities that get
 *  destroyed.
 */
void destroyEntities(
         ConsumerContext context,
         EntityHandle[] entities);
 

/**
 * A couple of differences here.  There are no
 * "interactionParameters".  These are merely the request
 * parameters in the RequestData.  Also, the action can not
 * only return a new context, but also a new entityMode.  JSR168
 * says an entity can change its window state/entity mode in
 * a blocking action or attempt a change in a non-blocking one.
 */
[EntityMode, EntityContext] performAction(
         ConsumerContext context,
         EntityContext entityContext,
         EntityHandle entity,
         Action action,
         RequestData request);

/**
 *  getMarkup looks like performAction.  Major difference
 *  is that since getMarkup is never called because of a
 *  direct user action -- always indirectly -- it doesn't
 *  receive any request parameters.
 *
 *  Note:
 *  ResponseProperties contains among other things new window
 *  state/portlet mode as JSR 168 says the entity can request
 *  such a change.
 */
[Markup, ResponseProperties, EntityContext] getMarkup(
         ConsumerContext context,
         EntityContext entityContext,
         EntityHandle entity,
         RequestContext request,
         ResponseContext response);

[EntityContext] setProperty(
         ConsumerContext context,
         EntityContext entityContext,
         EntityHandle entity,
         Property[] properties);

[Property[], EntityContext] getProperty(
         ConsumerContext context,
         EntityContext entityContext,
         EntityHandle entity,
         String[] names);
 

Data:

/**
 *  ConsumerContext represents information about the consumer
 *  the producer [may] needs to run properly.  Currently this
 *  is the ConsumerHandler (from registerConsumer), the
 *  UserIdentity, and a SessionGroup.  The consumerHandler
 *  identifies the consumer.  The UserIdentity identifies the
 *  user on whose behalf the consumer is making the request. The
 *  SessionGroup identifies a consumer defined session namespace
 *  for this request.  This is needed so concurrent entities
 *  establishing new sessions can attach to a shared session
 *  prior to their return.
 */

  ConsumerContext {
    ConsumerHandle consumer;
    UserIdentify user;
    String sessionGroup;
  }

/**
 *  EntityContext allows an entity to return state to be managed
 *  by the consumer and returned on subsequent calls.  In one usage
 *  pattern it allows an entity to be stateless.  In another it
 *  allows an entity to reacquire locally maintained state.  I.e.
 *  the entity is free to either store its state in this context
 *  or references to its state.  The explicit notion of session
 *  discussed during the F2F is subsumed by this.  Entities wishing
 *  to use sessions merely place its sessionId in the entityState
 *  field.
 *
 *  Currently, there are two fields that hold state.  First is
 *  entityState.  This holds entity opaque state.  It corresponds
 *  to markupParams from the F2F (also includes sessionId). The
 *  second is entityProperties.  These include the transparent
 *  properties/state.  We still need to decide if we want these
 *  at all (in this draft) and if we do if the opaque state can
 *  be represented within here.
 *
 *  Because this is a connectionless protocol, the consumer needs
 *  to know how long this state must be maintained for (when not
 *  in use) before it can release it.  The expires field defines
 *  this (in seconds? minutes?)
 *
 */
  EntityContext {
    // indicates whether any of the values in the fields below
    // have changed -- when passed to a producer modified will
    // only be true if the consumer has modified the entityProps.
    // When returned from producer, consumer uses to determine
    // if it needs to update the state it is maintaining.
    boolean modified;

    // how long before this context expires if not used?
    // do we need different expires for the two fields?
    int expires;

    // can we collapse these two into one field
    String entityState;  // opaque parameters
    Property[] entityProperties; // transparent properties
  }

 /**
  * RequestContext contains the information about this request.
  */
  RequestContext {
    // contains useragent and other device info
    DeviceInfo clientDevice;

    // charset of parameters in this request
    private String charSet;

    // mode and window states -- also a boolean indicating if
    // allows entity to modify
    private Mode entityMode;

    // request parameters -- null for getMarkup
    Property[] parameters;

    // additional values passed by consumer (aka things that
    // are passed in headers, consumer URLs so entity can
    // rewrite directly, vendor extension data, etc.)
    Property[] consumerData;

    boolean isClientCommunicationsSecure;
  }

 /**
  * ResponseContext describes the consumers expectation of the
  * response.
  */
  ResponseContext
  {
    String charSet; // preferred charset of response
    String locale; // preferred locale of response
    String[] markupTypes; // list of valid content types
  } --- End Message ---



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC