[alf-dev] ALF Event Simplification - Combine Detail and Extension to a s

["Tim Buss" <TBuss@xxxxxxxxxx>]

Note: There is some urgency in deciding this particularly if we are to change the element name to <payload> since we need a stable definition for ALF milestone 0.7.  Please respond with any feedback before Wednesday, Oct 11th.  This proposal has been available for review on the ALF wiki since Sept 7th 2006.

 

 

Currently the ALF event as defined by ALFEventBase_001.xsd includes two elements now called <Detail> and <Extension> .  In the original schema they were called <EventDetails> and <ToolExtensionData>

 

see  http://wiki.eclipse.org/index.php/Talk:ALF/architecture/ALF_Schemas and the discussion page http://wiki.eclipse.org/index.php/Talk:ALF/architecture/ALF_Schemas

 

The purpose of these elements is to hold event "payload" and the distinction between them is that  <Detail> is intended for "Vocabulary" defined payloads where as <Extension> is intended for "tool" defined non vocabulary payloads.  The distinction between these elements has been questioned on several occasions and it has been proposed to combine them into one element called, say, <Payload>

 

The main argument for doing so is that events may be defined specifically and in full relating the full value content of the event (eg event type and object type) to the specific type of the payload if the event definition requires it (see event declaration schema) http://wiki.eclipse.org/index.php/ALF/Vocabularies/Event_Declaration_Schema

 

Thus a vocabulary defined event would define a vocabulary defined payload.  Any allowable extensions to the vocabulary defined event payload would be defined by the vocabulary defined event payload.  This provides for the substitution of tools that raise the same vocabulary events provided the service flows that handle the events are designed to the vocabulary defined schema and not the extended tool defined schema.

 

Similarly tool defined events would define their own payload in the <Payload> area using their own specific non vocabulary types.

 

The main argument for keeping the <Extension> element is that it can provide better separation between what is Vocabulary and what is Tool specific payload making it easier to ignore the tool specific payload if that is a goal.  Issues this argument does not address are:

•  how to enforce the use of <Detail> for purely vocabulary defined payloads and
•  how to address the desire of tools to provide extensions to the vocabulary payload which logically have proximity to their vocabulary counterparts (eg addtional options). 

 

It seems clear that substitutability can and will be enforced by the vocabulary event definition as a whole by using the schema extension techniques of restricting and extending types and the judicious inclusion of <xs:any minOccurs=0> .  If a tool wishes to extend a vocabulary event it can do so by deriving a new schema type from the full event definition published by that vocabulary.  The new schema type will be accepted as a vocabulary event but can optionally be used in its extended form if the tool specific features are required.  Given that a tool will define its own non-vocabulary events as new schema types, the tool is free to use the same "Payload" element without fear of ambiguity and without affecting tool substitutability.  A further argument to recommend this approach is that it allows a well designed tool specific ALF event schema to be proposed and accepted as a "Vocabulary" schema without structural change.  Thus the original intent and more is addressed without the presence of a specific <Extension> element. 

 

Despite this, one reason for keeping the <Extension> element is that it provides a "guaranteed" way to extend the vocabulary payload if that payload is defined is such a way that it is not extensible.  This might also be achieved by adding and <any minOccurs="0"> at the BaseEvent level which would allow for organized but arbitrary extension to the Event definition as a whole and probably should be considered in any case.  With this addition, should Tools require an "extension element post ALF 1.0 they are free to define one as part of their event definition schemas. 

 

To conclude, the case for keeping both the <Detail> and the <Extension> payload element does not seem that strong.  The question really comes down to whether we feel having two "payload" elements helps clarify our intent or merely complicates and confuses it.  This is a judgment call but I personally favor providing just one "Payload" element since the primary motivation for the second can and will be adequately met in other ways.  Eliminating the second payload element would give a ALFEventType definition along the lines of the following schema fragment.

 

<xs:complexType name="ALFEventType">
<xs:sequence>
<xs:element name="Base" type="EventBaseType"/>
<xs:element name="Payload" type="EventPayloadType"/>
<xs:any minOccurs="0"/>
</xs:sequence>

...

 </xs:complexType>
Note: attributes omitted for clarity

 

Tim Buss

Serena Inc.

**********************************************************************

This email and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed. Any unauthorized review, use, disclosure or distribution is prohibited. If you are not the intended recipient, please contact the sender by reply e-mail and destroy all copies of the original message.