ALF/Vocabularies/Event Declaration Schema

ALF Wiki Home

Event Declaration

There are a number of goals we wish to achieve.

1. A tool needs to define the Details and Extensions that come with particular event types such that we can design a service flow to access the Detail and Extension data in the event

2. We need to be able to enumerate the possible events as explict combinations for inclusion in the event dispatch map.

3. A design tool may wish to enumerate the possible events to allow a user to pick one to design to. For most BPEL tools this probably means picking a WSDL PortType.

Attached are some experimental schemas and WSDL that illustrate how a tool might declare its ALF events.

The basic technique used here is to define schema "restriction base" derived types that allows you to tighten the value range or other restrictions on certain elements in a complex type. In this way we can declare a type that is an ALFEventType but that only allows an event type of "ThingCreated" and an object type of either "Thing1" or "Thing2" for example.

The following sample is derived from 1st round simplification base schema/wsdl (version 001). This is described elsewhere and not relavent to this discussion see ALFEventBase_001.xsd and ALFEventManager_001.wsdl in the Architecture section [[1]]

The following two files are for a fictitious tool that needs to declare events

MyALFEvents_001.xsd MyALFEvents_001.wsdl

The xsd is derived from the ALFEventBase_001.xsd and defines derived restricted types. These restricted type also declare the specific Detail and Extension data that accompanies the particular event. A few variant have been defined to illustrate how restrictions can be combined to create a more compact schema when particular values are valid to use interchangeably (eg any one of these object types can come with this event). I think that this combination is actually a bad idea for reasons discussed below.

The WSDL uses the derived types to redeclare the ALFEventManager WSDL in terms of the more restrictive and details tool specific types.

I am not 100% happy with the result since this requires rather more schema slinging than I feel is ideal. There are also some possible runtime problems with the WSDL.

Problems with the WSDL - goal #1 In schema it is not possible to declare an element as having a type that is a union of complex types. "Choice" comes close but it introduces an <element> and is really a choice of elements that may have different types. Consequently, it is not possible to simply re-declare the base event messages and port type using a union type. A solution is to declare new messages and ports, one set for each event. The unfortunate consequence of this that the message "element" of the event message must be named for the derived event. Since the event operation must still be EventNotice we must break the WSDL "Document Literal Wrapped" convention of the operation and the message element having the same name.

The runtime consequences of this depend on what the tool acutally does when it sends its event message to the EventManager.

It could treat its declarations as simply "for information" descriptions and not be bound to the message name. Consequently, at runtime the tool, will always send the ALFEvent message as defined by the ALFEventManager_001.xsd. That is the message will contain a single element called "EventNotice". The content of the message will vary and will be one of the variants described be the tool schema.

Alternatively, it could use its event message definitions literally and send then with the tool defined element name. The operation must always be EventNotice (or EventNoticeWithReply) but the messages would essentially be event dependant since there root element name would change.

Which of these two possibilities we choose probably shouldn't matter to the EventManager so long as it knows to always search below the root element when finding the fields it uses to dispatch on. However, the root element name may matter to the BPEL flow definition. If a flow is designed to expect a particular message it will probably be the case that it has to have the correct name for its root element. This probably means that the literal message definition technique is required. This may have the undesirable effect of forcing a service flow to be product specific when it doesn't otherwise need to be. This issue remains to be resolved. Probably need to do some experiments.

Problems with the valid combinations - goal #2 The technique of defining the set of possibilities via type restrictions is powerful and allows considerable flexibility as far as how valid combinations can be expressed. We can go from full permutation - any event type can have any object type to full declartion of just the valid combinations - eventA and objectA, eventA and objectB etc. The problem is that these combinations are not easily distilled from the schema. It is probably necessary to walk the tree of event type definitions as XML and accumulate the values that are possible for any particular element. Then you would need to discover which values of another element make valid combinations. The information is there but it is not easy to derive.

Problems with enumerating the events - goal #3 While it is probably easy enough to enumerate port types in the WSDL and find those that contain EventNotice (or EventNoticeWithReply) operations there may be difficulties if the events combinations are not fully and individually declared. This can only be determined by walking the schema. Consequently we should probably recommend that a tool not use a combined declaration for EventBase combinations but should explicitly declare the valid combinations as separate types. A problem is there is probably no way to enforce that.

WSDL/Schema

MyALFEvents.wsdl This example shows a simple derived event definition with both a Vocabulary extension and a Custom extension. The XSD schemas and the WSDL are combined into a single file for simplicity although it is generally more flexible to separate them.

Note that a real vocabulary schema would define its own set of derived event types. A a tool supporting a vocabulary must derive its event schema from that vocabulary schema adding its customizations and exclusive events. To use a tool with not customization it should be possible to use the vocabulary schema as to define the the corresponding service flows. How well this works will depend on how well the tool implements the base vocabulary events

Note: A potential problem with vocabulary schemas is that the object and event values could clash. The problem may arise when an existing tool that has defined is own events and objects now wants to support a vocabulary. We may solve this by pre-pending a namespace to these values.

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions 
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
name="MyALFEvents" 
targetNamespace="http://www.eclipse.org/alf/schema/EventBase/1"
xmlns:tns="http://www.eclipse.org/alf/schema/EventBase/1" 
xmlns:evt="http://www.eclipse.org/alf/schema/EventBase/1"
xmlns:ext="http://www.example.org/MyEventExtensions" 
xmlns:evc="http://www.eclipse.org/ALF/ExampleVocabulary"
>
    
  <wsdl:documentation>
	WARNING: PRELIMINARY VERSION SUBJECT TO CHANGE
  
      Copyright Notice
      The material in this document is Copyright (c) Serena Software, Inc. and others, 2005, 2006, 2007
      Terms and Conditions:
      The Eclipse Foundation makes available all content in this document ("Content").
      Unless otherwise indicated below, the Content is provided to you under the terms
      and conditions of the Eclipse Public License Version 1.0 ("EPL").
      A copy of the EPL is available at http://www.eclipse.org/legal/epl-v10.html.
      For purposes of the EPL, "Program" will mean the Content.
      If you did not receive this Content directly from the Eclipse Foundation, the
      Content is being redistributed by another party ("Redistributor") and different
      terms and conditions may apply to your use of any object code in the Content.
      Check the Redistributor's license that was provided with the Content.
      If you did not receive any such license, contact the Redistributor.
      Unless otherwise indicated below, the terms and conditions of the EPL still apply to the Content.
  </wsdl:documentation>
    
  <!-- ALF EventManager WSDL -->  
<wsdl:import location="ALFEventManager_1.wsdl" namespace="http://www.eclipse.org/alf/schema/EventBase/1"></wsdl:import>
  
<wsdl:types>

	<!-- The various schemas are defined below.
	Generally, it is prefered to import these schemas
	This example is defines them in-line for simplicity. 
	-->

	<!-- Example Vocabulary Extension
	This schema is a simple example of a Vocabulary extension.
	Generally, extension schemas such as this would be imported.
	This example is defined in-line for simplicity. 
	-->
	<xsd:schema xmlns="http://www.eclipse.org/ALF/ExampleVocabulary" elementFormDefault="qualified" targetNamespace="http://www.eclipse.org/ALF/ExampleVocabulary">

	<xs:complexType name="ExampleVocabularyExtension">
		<xs:annotation>
			<xs:documentation>
				Vocabulary Event Extension
			</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="ExampleVocabularyData" type="xs:string"/>
		</xs:sequence>
		<xs:anyAttribute/>
	</xs:complexType>

	</xsd:schema>

	<!-- Example Custom Extension
	This schema is an simple example of a Tool specific custom extension.
	Generally, extension schemas such as this would be imported.
	This example is defined in-line for simplicity. 
	-->
	<xsd:schema xmlns="http://www.example.org/MyEventExtensions" elementFormDefault="qualified" targetNamespace="http://www.example.org/MyEventExtensions">

	<xs:complexType name="MyCustomExtension">
		<xs:annotation>
			<xs:documentation>
				Custom Extension
			</xs:documentation>
		</xs:annotation>
		<xs:sequence>
			<xs:element name="MyData" type="xs:string"/>
		</xs:sequence>
		<xs:anyAttribute/>
	</xs:complexType>

	</xsd:schema>

	<!-- The Tool's ALF Events.
	This schema shows some examples of how to declare ALF events by deriving schema types
	from the base ALF Event Schema
	Generally, it is prefered to import the schema.
	This example is defined in-line for simplicity. 

	-->
	<xsd:schema xmlns="http://www.eclipse.org/alf/schema/EventBase/1" elementFormDefault="qualified" targetNamespace="http://www.eclipse.org/alf/schema/EventBase/1">
	
	<xsd:include schemaLocation="ALFEventBase_1.xsd"/>
		
	<xs:import namespace="http://www.eclipse.org/ALF/ExampleVocabulary" />
	<xs:import namespace="http://www.example.org/MyEventExtensions" />
		
	<!-- Derived Basic Event -->
	<!-- This event declaration restrict the possible values for EventType, Object and Source by declaring derived types for those elements.
	See MyEventType1Type, MyObjectType1Type and MySourceType.
	There are various options for declaring these derived types depending on the valid combinations of EventType and Object values
	If any EventType value can be combined with any Object value then all possible values can be declared in a single type.
	If only one or some EventType values can be combined with one or some Object value the separate types can be declared for the valid combinations
	The Source is generally constant for any particular product. -->
	<!-- This example, MyBasicEvent1Type, is restricted to an event with the value "My Product Event Type A", and an object with the type value, "My Product Object Type A" -->
	<xs:complexType name="MyEventBase1Type">
		<xs:annotation>
			<xs:documentation>
      </xs:documentation>
		</xs:annotation>
		<xs:complexContent>
			<xs:restriction base="EventBaseType">
				<xs:sequence>
					<xs:element name="EventId" type="EventIdType"/>
					<xs:element name="Timestamp" type="TimestampType"/>
					<xs:element name="EventType" type="MyEventType1Type"/>
					<xs:element name="ObjectType" type="MyObjectType1Type"/>
					<xs:element name="ObjectId" type="ObjectIdType"/>
					<xs:element name="Source" type="MySourceType"/>
					<xs:element name="User" type="CredentialsType"/>
					<xs:element name="EventControl" type="EmBaseType"/>
					<xs:element minOccurs="0" name="BaseExtension" type="BaseExtensionType"/>
				</xs:sequence>
				<xs:anyAttribute/>
			</xs:restriction>
		</xs:complexContent>
	</xs:complexType>
	
	<!-- Derived subtypes -->
	<!-- In order to restrict the EventType, ObjectType and Source we need to declare one or more custom restricted types.
	Depending how the allowed values for EventType, Object and Source combine we can declare either one type for each element
	that restricts to all possible values, a number of single value types or some combination -->

	<!-- Derived EventTypeType -->
	<!-- This example restricts to a single possible value -->
	<xs:simpleType name="MyEventType1Type">
		<xs:restriction base="EventTypeType">
			<xs:enumeration value="My Product Event Type A"/>
		</xs:restriction>
	</xs:simpleType>
	
	<!-- Derived ObjectTypeType -->
	<!-- This example restricts to a single possible value -->
	<xs:simpleType name="MyObjectType1Type">
		<xs:restriction base="ObjectTypeType">
			<xs:enumeration value="MyObjectType1Name"/>
		</xs:restriction>
	</xs:simpleType>
	
	<!-- Derived SourceType -->
	<!-- The SourceType has its own sub-types, ProductType and ProductVersionType, which must also be derived. 
	Typically a Product will only have a single value whereas ProductVersion may have multiple.
	ProductVersion may combine with other derived types to allow version specific events to be declared-->
	<xs:complexType name="MySourceType">
		<xs:complexContent>
			<xs:restriction base="SourceType">
				<xs:sequence>
					<xs:element name="Product" type="MyProductType"/>
					<xs:element name="ProductVersion" type="MyProductVersionType"/>
					<xs:element name="ProductInstance" type="ProductInstanceType"/>
					<xs:element name="ProductCallbackURI" type="ProductCallbackURIType" nillable="true" minOccurs="0"/>
				</xs:sequence>
			</xs:restriction>
		</xs:complexContent>
	</xs:complexType>
	
	<!-- Derived ProductType -->
	<!-- This example restricts to a single value -->
	<xs:simpleType name="MyProductType">
		<xs:restriction base="ProductType">
			<xs:enumeration value="My Product Name"/>
		</xs:restriction>
	</xs:simpleType>
	
	<!-- Derived ProductVersionType -->
	<!-- This example restricts to a single value -->
	<xs:simpleType name="MyProductVersionType">
		<xs:restriction base="ProductVersionType">
			<xs:enumeration value="3.0"/>
		</xs:restriction>
	</xs:simpleType>
	
	<!-- Derived ALFEventType -->
	<!-- The actual event message is always an ALFEvent type.  
	The derived type just restricts the possible values and declares wha will be found in the extension areas.
	A tool that defines a CustomExtension data may define different content for the each event-object combination if it needs to.
	For Vocabulary events the content of the Vocabulary extension is defined byt eh vocabualry schema which a tool must follow.
	Vocabulary schemas provide for some extensibility and a tool may declare is own specializations for that.
	The same techniques are used but the extendable types are specialized to the particular vocabulary-->
	<xs:complexType name="MyALFEventType">
		<xs:sequence>
			<xs:element name="Base" type="MyEventBase1Type"/>
			<xs:element minOccurs="0" name="Detail" type="evc:ExampleVocabularyExtension"/>
			<xs:element minOccurs="0" name="Extension" type="ext:MyCustomExtension"/>
			<xs:any maxOccurs="unbounded" minOccurs="0" namespace="##other" processContents="lax"/>
		</xs:sequence>
		<xs:attribute default="1.0" name="version" type="ALFSchemaVersionType"/>
	</xs:complexType>

   </xsd:schema>
</wsdl:types>

<!-- Customized  EventNoice Message -->
<!-- Note that the WSDL message is defined with a type.
A type is used to be complient with WS-I RPC-Literal style.
The type used must be derived by restriction from the base ALFEventType.
In other words the type is actually an ALFEventType but its definition is more explicit.
There should be a derived EventNotice Message defined for each derived ALFEventType declared.
 -->
<wsdl:message name="MyEventNotice">
	<wsdl:documentation>Derived EventNotice message</wsdl:documentation>
	<wsdl:part name="EventNotice" type="evt:MyALFEventType"/>
</wsdl:message>

<!-- Customized  EventNoiceWithReply Message -->
<!-- EventNoticeWithReply is a placeholder for a future feature.
The input message has the same characteristics as the EventNotice input message -->
<wsdl:message name="MyEventNoticeWithReply">
	<wsdl:part name="EventNoticeWithReply" type="evt:MyALFEventType" />
</wsdl:message>

<!-- Customized  EventNoiceWithReplyResponse Message -->
<!-- EventNoticeWithReply is a placeholder for a future feature. 
The response message may be specialized for the particular event using the same derived type techniques -->
<wsdl:message name="MyEventNoticeWithReplyResponse">
	<wsdl:part name="EventNoticeWithReplyResponse" type="evt:ALFEventWithReplyResponseType" />
</wsdl:message>

<!-- Customized ALEEventManager PortType -->
<!-- This is shown for completness. Currently it is not required to declare a derived ALFEventManager port. -->
<wsdl:portType name="MyALFEventManager">
	<wsdl:operation name="EventNotice">
		<wsdl:input message="tns:MyEventNotice"/>
		<wsdl:output message="tns:EventNoticeResponse"/>
	</wsdl:operation>
	<wsdl:operation name="EventNoticeWithReply">
		<wsdl:input message="tns:MyEventNoticeWithReply"/>
		<wsdl:output message="tns:MyEventNoticeWithReplyResponse"/>
	</wsdl:operation>
</wsdl:portType>

<!-- Customized ALFServiceFlow PortType -->
<!-- This portType is used to define service flows that understand the specific event or set of events.
There should be a derived ALFServiceFlow portType defined for each derived EventNotice message declared.  -->
<wsdl:portType name="MyALFServiceFlow">
	<wsdl:documentation>Derived ServiceFlow port</wsdl:documentation>
	<wsdl:operation name="EventNotice">
		<wsdl:input message="tns:MyEventNotice"/>
	</wsdl:operation>
</wsdl:portType>

<!-- Customized ServiceFlowWithReply PortType -->
<!-- EventNoticeWithReply is a placeholder for a future feature. 
This portType is used to define service flows with reply that understand the specific event or set of events.
There should be a derived ALFServiceFlow portType defined for each derived EventNotice message declared.  -->
<wsdl:portType name="MyALFServiceFlowWithReply">
	<wsdl:operation name="EventNotice">
		<wsdl:input message="tns:MyEventNotice"/>
		<wsdl:output message="tns:MyEventNoticeWithReplyResponse"/>
	</wsdl:operation>
</wsdl:portType>

<!-- Customized MyALFEventManagerSOAP Binding -->
<!-- This is shown for completness. Currently it is not required to define a customized ALFEventManager Binding. 
Note that the binding style is rpc and the body uses literal encoding -->
<wsdl:binding name="MyALFEventManagerSOAP" type="tns:MyALFEventManager">
	<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
	<wsdl:operation name="EventNotice">
	<soap:operation soapAction=""/>
		<wsdl:input>
			<soap:body use="literal" namespace="http://www.eclipse.org/alf/schema/EventBase/1"/>
		</wsdl:input>
		<wsdl:output>
			<soap:body use="literal" namespace="http://www.eclipse.org/alf/schema/EventBase/1"/>
		</wsdl:output>
	</wsdl:operation>
	<wsdl:operation name="EventNoticeWithReply">
	<soap:operation soapAction=""/>
		<wsdl:input>
			<soap:body use="literal" namespace="http://www.eclipse.org/alf/schema/EventBase/1"/>
		</wsdl:input>
		<wsdl:output>
			<soap:body use="literal" namespace="http://www.eclipse.org/alf/schema/EventBase/1"/>
		</wsdl:output>
	</wsdl:operation>
</wsdl:binding>

<!-- Customized MyALFServiceFlowWithReplySOAP Binding -->
<!-- This is shown for completness. ServiceFlowWithReply is a future feature 
Note that the binding style is rpc and the body uses literal encoding -->
<wsdl:binding name="MyALFServiceFlowWithReplySOAP" type="tns:MyALFServiceFlowWithReply">
	<wsdl:documentation>Derived ServiceFlowWithReply binding</wsdl:documentation>
	<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
	<wsdl:operation name="EventNotice">
		<soap:operation soapAction=""/>
			<wsdl:input>
				<soap:body use="literal" namespace="http://www.eclipse.org/alf/schema/EventBase/1"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal" namespace="http://www.eclipse.org/alf/schema/EventBase/1"/>
			</wsdl:output>
	</wsdl:operation>
</wsdl:binding>

<!-- Customized ALFServiceFlowSOAP Binding -->
<!--  This declaration provides the template for a binding compatible with the base ALFEvent but using the derived types
Note that the binding style is rpc and the body uses literal encoding -->
<wsdl:binding name="MyALFServiceFlowSOAP" type="tns:MyALFServiceFlow">
	<wsdl:documentation>Derived ServiceFlow binding</wsdl:documentation>
	<soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
		<wsdl:operation name="EventNotice">
		<soap:operation soapAction=""/>
		<wsdl:input>
			<soap:body use="literal" namespace="http://www.eclipse.org/alf/schema/EventBase/1"/>
		</wsdl:input>
	</wsdl:operation>
</wsdl:binding>

<!-- Customized ALFEventManager Service Example -->
<!-- This is shown for completness. ServiceFlowWithReply is a future feature 
Currently it is not required to define an example customized ALFEventManager Service. -->
<wsdl:service name="MyALFEventManager">
	<wsdl:documentation>Example Derived EventManager service</wsdl:documentation>
	<wsdl:port binding="tns:MyALFEventManagerSOAP" name="MyALFEventManagerSOAP">
		<soap:address location="http://localhost:8080/ALFEventManager/services/ALFEventManagerSOAP"/>
	</wsdl:port>
</wsdl:service>

<!-- Customized ALFServiceFlow Service Example -->
<!--  This declaration provides the template service compatible with the base ALFEvent
but using the derived types. It is not intended to declare an actual service but to define a template 
that can be imported by a web service toos to create a web service interface that expects the custom data 
as defined by the various supporting custom defintions.  Since thsi service definition uses a types defined 
by restricted derivation, a base service flow may also be used to handle the corresponding event.  
This allows a tools events be handled three differnt ways - 
	a base event
	a vocabualry event should it support one or 
	a custom event
 -->
<wsdl:service name="MyALFServiceFlow">
	<wsdl:documentation>Example Derived ServiceFlow service</wsdl:documentation>
	<wsdl:port binding="tns:MyALFServiceFlowSOAP" name="MyALFServiceFlowSOAP">
		<soap:address location="http://localhost:8080/ALFServiceFlowEngine/services/MyALFServiceFlowSOAP"/>
	</wsdl:port>
</wsdl:service>

</wsdl:definitions>