[wsrp-wsia] WSRP proposed changes to better support JSR 168

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

Folks,
   Attached is a document put together by the JSR 168 Expert Group that
details the suggested changes we are requesting WSRP make/consider.  The
document tries to explain the desired function as well as provides
concrete proposals for representing this function in WSRP.  As the first
focus of the WSRP F2F next week is to discuss JSR 168 related issues
please try and familiarize yourself with this information prior to
Monday.  We will work from this document during these discussions.
     -Mike-

Title: WSRP modifications for JSR 168

The following is a proposal submitted by
the JSR 168 Expert Group for modifications it would like to see WSRP make
to facilitate carrying JSR 168 semantics in the remote case.  The
modifications are segmented into three sections.  The first section
defines semantics that WSRP must accomodate if JSR 168 is to use the WSRP
protocol to support remote JSR 168 portlet containers/portlets.  The
second section defines semantics that could otherwise be carried via the
WSRP extensions mechanism but the JSR 168 expert group finds real value
in having them carried explicitly.  The third section contains recommendations
for WSRP mechanisms to make it easier to implement JSR 168 containers,
make it easier for such implementations to fully interoperate, or allow
for more scalable and higher performing implementations.

Section 1: JSR 168 requires support for the following

• WSRP Issue #122: Mismatch with JSR168 definition of Action

As the issue describes, JSR 168 models 2 types of actions: blocking and non-blocking.  Currently, WSRP only models blocking actions.  A blocking action is an operation that occurs atomically; no concurrent requests that are derived by the consumer's aggregator for a particular client request are executed during a blocking action.  A blocking action gives the entity the safety of updating state that impacts other entities/portlets.  A non-blocking action is an operation that doesn't have this safety net.  A consumer is free to communicate with other entities/portlets during a non-blocking action.  Non-blocking actions are useful therefore where updating state only impacts the current entity.  The benefit of non-blocking actions is greater throughput and scalability.  To enhance this improvement JSR 168, further optimizes its notion of non-blocking actions by allowing the action to return markup.

We suggest two alternatives for WSRP to consider and choose between:

1) Support non-blocking actions by extending the semantics of performInteraction()
2) Support non-blocking action by adding a new method specifically to support the non-blocking case.

1) Support non-blocking actions by extending the semantics of performInteraction()

performInteraction [and associated function] would have to be modified in a number of ways to support non-blocking semantics.
1. Action URLs written into markup would have to indicate whether they are blocking or non-blocking.  I.e. wsia:urlType would have to be extended to included both a value called Action and a value called BlockingAction.   The first would signify a non-blocking action while the second would signify a blocking one.
2. If the action is a non-blocking action then the consumer MUST ignore the navigationalState, newWindowState, newMode, and redirectURL return values in InteractionResponse.  Producers SHOULD set these return values to null.  In any subsequent rendering [before another action] the consumer MUST pass the same navigationalState, window state, and mode as it passed to the non-blocking action.
3. performInteraction would have to be "optimized" to allow an entity to return markup directly.  This would take the form of performInteraction [optionally] returning an additional value, namely the MarkupResponse.
4. All other behavior/function of performInteraction would remain as defined and apply to both blocking and non-blocking actions.


2) Support non-blocking action by adding a new method specifically to support the non-blocking case.

Alternatively, WSRP could model non-blocking actions in a distinct method.  For this case we suggest the following signature:
NonBlockingInteractionResponse = performNonBlockingInteraction(refHandle, registrationContext,
   entityContext, userContext, markupParams, interactionParams)

where NonBlockingInteractionResponse contains the following:

NonBlockingInteractionResponse
   [O] RefHandleContext  refHandleContext
   [O] MarkupResponse    markupResponse
   [O] EntityResponse    entityResponse
   [O] Exetnsion[]       extensions

Basically, the same as option (1) above but with the unneeded fields explicitly excluded vs. defined as ignored.
 

The rest of the performInteractions semantics would come across/be defined for the performNonBlockingInteraction operation.  In addition the new urlTypes defined above would also have to be introduced.


Whether or not suggestion (1) or suggestion (2) is accepted, we suggest that it will be useful for consumers to be told whether or not this entity changes state in non-blocking actions.  This allows the consumer to handle the [rare] case in which it is maintaining two distinct references to the same entity in the same aggregatable unit [page].  Having such information allows the consumer to either choose to not allow this situation to occur by preventing such a page design or if the situation is allowed to block the other references to the same entity or merely do nothing and accept the temporary inconsistency between the two renditions.  To accomplish this we suggest the following  meta data field be added to EntityDescription, hasNonblockingStateChanges.  This field is a boolean.  A value of true indicates that the entity uses nonblocking actions and that entity state may change during such an action.  A value of false indicates either the entity doesn't use nonblocking actions or no entity state changes occur within them.

 
• WSRP Issue #???: Define a CSS prefix that is WSRP neutral

Like WSRP developers, JSR 168 portlet developers need CSS tags that allow them to generate markup with a consumer consistent style.  However, JSR 168 requires this prefix not be remote specific (i.e. wsia-).  We suggest using a neutral prefix.  As this has been discussed previously and no universally acceptable prefix has been found we suggest sticking with the last expressed acceptable tag: portlet- unless WSRP finds a more acceptable name.
• WSRP Issue #125: Clone entity/entity management

JSR 168 doesn't describe that the operation wherein an entity state changes fails may be retried.  This seems to be the semantics defined when the entityStateChange flag is set to 'FAULT'.  If this is the case, JSR 168 needs a mechanism for the consumer to recognize it can't handle the 'FAULT' case and therefore guarantee it will never receive such a flag.  We suggest adding a boolean field called supportsStateChangeFaulting to EntityDescription [entity meta data].  If the value is true or otherwise not indicated the entity can support the 'FAULT' semantics.  If the value is false it indicates the entity doesn't support 'FAULT'.  In this situations consumers MUST only send either the 'OK' or the 'CLONE' values.

Section 2: JSR 168 requested support

As stated in the summary, the following define information JSR 168 requires
be delivered via WSRP however because of WSRPs extensibility system need
not be carried explicitly.  I.e. they can be carried as extensions. 
We prefer these be adopted/voted on as a whole vs. piecemeal as there is
only value to us if all are carried explicitly [because we don't have to
define "standard" extensions].

• WSRP Issue 132: Supporting JSR 168 valid window states and modes function.

JSR 168 defines that the portlet container MUST be able to tell the portlet whether or not a particular window state or mode is currently valid within the context of the given request.  In addition, JSR 168 demands that portlets be prevented from referencing such invalid states/modes in its responses.  To satisfy this requirement, the portlet container must know the set of valid window states and modes on a per request basis.  To support this in WSRP, we suggest adding two String array fields to the MarkupParams structure called allowableWindowStates and allowablePortletModes. These arrays would define which window states and modes the current requester can transition to.  Note:  these values are passed to both performInteraction and getMarkup.

In addition, we suggest WSRP also consider adding a similar optimization as was added for userProfile information, namely entity meta data that indicates these values are store in the entity session.  Specifically, it is suggested that a boolean field called allowableStatesAndModesStoredInSession be added to the EntityDescription structure.  A value of true would indicate a consumer could choose not to send these values on each request once an entity session is established.  A value of false, or if the value is otherwise excluded, means the information MUST be sent on every request.

 

• WSRP Issue: 123: Portlet Modes per Markup

JSR 168 allows a portlet developer to express (via deployment descriptor meta data) the portlet modes that are valid for a given mime-type.  For example, a portlet may indicate it supports EDIT mode for html devices but not WML [phone] devices.  This information is provided so the consumer portal can better manage the actions/decorations it displays along with the portlet.  For example, the portal could choose not to display an Edit action on the WML device.  We request WSRP modify its entity description to pass this information by changing the modes and windowStates fields to carry this information as follows:
       Modes[] modes
       WindowStates[] windowStates

where Modes is defined as:
       String   markupType
       String[] modes

and WindowStates is defined as:
       String   markupType
       String[] windowStates

An alternative proposal would be to collapse all these into a single structure by defining a new field in EntityDescription called markupConstraint:

MarkupConstraint[] markupConstraints
 
where MarkupConstraint is defined as:
String[] modes
String[] windowStates


The benefit of the later over the former is it gives us flexibility in the future to define additional attributes that are qualified on a per markup type basis.

Note:  In either case above, if a markup type defined in the markupTypes field isn't constrained [i.e. referenced by a constraint field] then this indicates that all modes and window states are supported.
 

Section 3: JSR 168 recommended changes.

This section contains a list of requested changes that we believe will
make it easier to implement JSR 168 containers, make it easier for such
implementations to fully interoperate, or allow for more scalable and higher
performing implementations.  These requests follow in the same spirit
as the currently proposed groupID semantics.  If they don't exist
in JSR 168, JSR 168 can still be implemented (without extensions) but there
will be a greater likelyhood that one or more of the above benefits will
be lost.  Because these are recommendations we ask they not be considered/voted
as a group.  Rather, we ask they be discussed and voted upon on
their individual merit.

• WSRP Issue #????: Support consumer caching of property descriptions.

Currently, entities are allowed to create/modify the characteristics of  properties dynamically.  JSR 168 also supports this function.  WSRP, currently doesn't provide anyway for a consumer to be told that a chaneg has occurred.  This prevents consumers from caching such information.  I.e. whenever a consumer needs to access this information it MUST call the entities getEntityPropertyDescription() method.  We recommend you:
1. Add a new boolean field called propertyDescriptionChanged to EntityResponse.  If this value is true it indicates that producer has modified the description of one or more properties in this request. If this value is false or otherwise excluded it indicates that the producer has not modified the property description during this request.
2. Add a new boolean field called changeablePropertyDescriptions to EntityDescription [entity meta data].  If this value is true it indicates that the entity's property description is dynamic.  If this value is false or otherwise excluded it indicates that the entity's property description is static.
• WSRP Issue #????: Provide guidance/support for JSR 168 types when WSRP carries an ANY.

There are a few situations where WSRP defines a value of type ANY but the JSR 168 defines/prefers a specific [set of] type(s).  One situation is in describing the type of an entity property in PropertyDescription.  Another situation is in utilizing PropertyLists [attribute-value string arrays] to carry JSR 168 extensions.  It would be very useful if WSRP defined specific representations for these types in a schema it hosts along with the standard wsdl bindings/definitions.  Doing so will greatly facilitate a common use of these types by JSR 168 implementations.

The following proposal is provided by Deam Moses of Epicentric on behalf of the JSR 168 Expert Group:

In WSRP, property values are represented by the <any> type, which means there is no guidance in how to format the value.   The idea is that the consumer reads the WSDL, and for property types whose WSDL definition it understands, it can auto-generate screens to let admins or possibly end users set values.

Basic (non-extended) JSR 168 producers will be sending only string and string array values.   You'd think it would be simple to figure out from the WSDL whether the incoming property type is a string array, but in fact there are multiple ways to represent string arrays.  SOAP and WSDL has formalized one way, but .NET uses another way, and in Epicentric's automated testing that generates UIs for hundreds of public web services, we've discovered developers using other odd ways. Here's an article that also goes into different SOAP array types: http://www.capescience.com/articles/commonerrors/

In Wednesday's conference call, we said we would like WSRP to specify a standard way of representing string arrays, so that consumers just interested in basic properties would be able to get them without having to handle different variants.  Failing that, we'd like to agree among JSR 168 producers how to specify them.

The obvious choice is to follow the SOAP and WSDL encoding schemes. The WSDL that describes this encoding must include a element with a soap:Array attribute and a sub-element with a type attibute equal to xsd:string.  This is how JAX-RPC and Axis do it. .NET does not use the type description metadata in the SOAP envelope, but will still function.

An example WSDL:

<element name="colors">
  <complexType base="soap:Array">
    <element
      name="color"
      type="xsd:string"
      minOccurs="0"
      maxOccurs="unbounded"/>
  </complexType>
  <attribute ref="soap:arrayType" wsdl:arrayType="xsd:string[]"/>
</element>

Example of a string array in a SOAP message:

<echoStringArray
   soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns="urn:TestService1">
  <colors soap:arrayType="xsd:string[3]">
    <color xsi:type="xsd:string">red</color>
    <color xsi:type="xsd:string">green</color>
    <color xsi:type="xsd:string">blue</color>
  </colors>
</echoStringArray>

By contrast, the .NET schema is this:

<s:element name="echoStringArray">
  <s:complexType>
    <s:sequence>
      <s:element
        minOccurs="0"
        maxOccurs="1"
        name="colors"
        type="s0:ArrayOfString" />
    </s:sequence>
  </s:complexType>
</s:element>
<s:complexType name="ArrayOfString">
  <s:sequence>
    <s:element
       minOccurs="0"
       maxOccurs="unbounded"
       name="color"
       nillable="true"
       type="s:string" />
  </s:sequence>
</s:complexType>

And the .NET SOAP values are like this:

<echoStringArray
   soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
   xmlns="urn:TestService1">
  <colors soap:arrayType="xsd:string[3]">
    <color xsi:type="xsd:string">red</color>
    <color xsi:type="xsd:string">green</color>
    <color xsi:type="xsd:string">blue</color>
  </colors>
</echoStringArray>
 
 

• WSRP Issue #124: Passing consumer WindowID

In JSR 168 there is only a single shared session.  Entity sessions are partitioned segments within this shared session.  We believe a more scalable JSR 168 consumer can be built if WSRP doesn't require these partitioned segments be exposed/managed by the consumer.   We recommend that WSRP be modified to pass a portletID to the producer/entity in getMarkup() and performInteraction() to support this.  This would be a required value/field.  The consumer MUST send a value that identifies the element in the consumers structure that caused this entity request.  I.e. as WSRP promotes a many entity per consumer portlet instance model, the portletID identifies which consumer portlet instance this entity is related to.

We recommend one of two approaches for representing the portletID.  Either add the portletID to the EntityContext structure or invent a new structure called ConsumerContext to carry this field.  We recommend the former if portletId is the only consumer information that needs be carried.  We recommend the later if more consumer information is identified to be carried.  Note: When we discussed this in a JSR 168 conference call, Andre Kramer suggested a number of additional pieces of information that should be carried.  He will be sending his ideas out separately.