ALF/Vocabularies/Event Declaration Schema

From Eclipsepedia

< ALF
Revision as of 23:48, 26 June 2007 by Tbuss.serena.com (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents


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 but that same event can also be handled by a ServiceFlwo that only understands the Base Event (or if applicable only the vocabulary defined 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 but for other tools a Service defintion may be required.

Attached is an example WSDL with embedded schemas 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 ALFEventBase_1.xsd and ALFEventManager_1.wsdl. These are described elsewhere (see ALFEventBase_1.xsd and ALFEventManager_1.wsdl in the Architecture section)[[1]]

The following file is for a fictitious tool that needs to declare events

MyALFEvents.wsdl

The new types are restricted derivations from types defined in ALFEventBase_1.xsd . The restricted type also declares the specific (Vocabulary) Detail and Custom Extension data that accompanies the particular event.

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


Solutions to meeting goal #1 - defining specific events that can be handled as base events 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. This is problematic if the recommended WS-I compliant Document Literal style is used. This defines the WSDL message in terms of an element. To use the derived type we would need to use a new element to define the message since a particular top level element can only have one type. The unfortunate consequence of this that the new message would have a different root element than a base event message. Consequently, at runtime, the message couldn't be handled generically as a base event but would require a service flow define specifically for it. This is a serious drawback.

Two possible solutions are:

1. use WS-I compliant RPC literal or

2. have the Event Manager understand the type of the event and fix up the message at runtime.

RPC-Literal seems to provide the lightest weight solution of these two. It defines the WSDL messages in terms of types. Thus our new messages can be defined using the restricted derived types and consequently a custom message looks just alike a base message at runtime. The main issue with RPC-Literal is how widely it is supported since it it not generally the preferred option.

Having the Event Manager understand the type requires more complex configuration of the event-action map so it is not preferred but may be considered as a back up solution should the need arise.


Solutions to meeting goal #2 - enumerating valid event definitions for inclusion in an Event-Action Map 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 declaration of just the valid combinations - eventA and objectA, eventA and objectB etc. A potential problem is that these combinations are not easily distilled from the schema.

For this reason it is preferred to explicitly declare separate services, portTypes etc in the WSDL for the various valid combinations. Then it is only necessary to pick the particular service you required and read its event and object combination. Failing this all combinations of event Type and object Type must be considered valid

Solutions to meeting - goal #3 - enumerating valid event definitions for the purposes of creating a service flow specific to that event Tools should be able to enumerate service or portType declarations. It is unclear how easy it would be to check that the types used by the event definition are, in fact, derived by restriction from the base event schema but it is theoretically possible. Again, the more explicit the Event declaration is about valid combinations the easier it is to construct an valid service flow.

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 
	what 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 by 
	the vocabulary 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 this 
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>