Difference between revisions of "ALF/architecture/ALF Schemas 001"

Revision as of 16:42, 27 September 2006

ALF Wiki Home

Introduction

ALF Event Manager Schemas and WSDL version 001

We have been reviewing the ALF Event Schema and our recommendation is that if should be flattened and simplified. Here the details of our suggestions and reasoning so far. The proposed schema is just for illustration and should not be considered final. Please respond with any comments you may have and any other suggestions about way to streamline the ALF event Schema.

Here are the details of the changes which have undergone some review and will be likely be adopted. These changes are refected in the Schema and WSDL below

1. Eliminate a nesting level between BasicEventType and Event Data.

This serves no particular purpose except to separate it from the Context Array which is not returned on an ACK. If we eliminate the Context Array as I suggest below then this distinction is no longer required.

2. Eliminate the Object Array in favor of a single ObjectType.

This is in BasicEventType. It seems to me that is very rare that we will encounter a situation where a tool cannot provide a single identity to use to call back for additional information. While the array and related "relationship" attribute may be potentially powerful it would seem better relegated to a potential common vocabulary type for vocabulary or tool specific event details. The only potential issue is that removing the array from the basic event also removes it from the consideration as part of an ALF event manager dispatch rule. Currently we only use the first object in the array. This seems a reasonable price to pay The array seems somewhat complex for that purpose due to its rather arbitrary nature and, if we find we are really missing it later we have the option of extending the Basic Event to include an array of this nature in addition to the primary object.

3. Eliminate the Context Array

We should also merge the current user details into the BasicEventType. The context array does not seem that useful to me. It just makes the current context harder to discern. Further, it does not seem to be desirable from a security standpoint to be passing around arrays of credentials. I don't see any particular programmatic use of this feature and a simple log or a relationship store would be a better method of tracing contexts after the event. Even if it is of some practical use, that use relies on the support to tools to return the context in full in an event. This seems unlikely except by the most avid of ALF participating tools rendering it useless in the foreseeable future.

4.Eliminate "InitiatingFlow" and the "nesting" attribute

This is an aspect of the Context. This does not provide much useful information and again relies on all participants to behave the ALF way in order for the nesting counter to accurate. Instead provide some preceding IDs ( see below) and rely on logging. I am unclear whether it would be useful to know if the event comes from a user interaction or a service flow. It would seem to me likely that that this can be inferred from the event type and event product information and not explicit flag is required. I am unclear what you would do with it in any case. Thus I would just eliminate it.

5. Add "PrecedingEvent" and "PrecedingServiceFlow" to the Basic Event Type as nillable elements.

If the event is generated in the directly by a service flow then the ServiceFlow will fill these, identifying itself and the event that initiated it. Optionally an ALF compliant service may take this data and return it in any event it generates. The Source elements can be used to distinguish the cases.

6. Add a ALFEventNoACK element and associated Type.

Async Service flows have this type. Unfortunately the Event Manager currently dispatches using ALFEventACK which is incorrect and confusing. (Note: this change and been subsumed by the name changes describe in 8. below)

7. Eliminate the use of the "mixed" attribute.

I believed the used of the attribute "mixed" is incorrect. This attribute means that and element can contain both content text and other elements. I don't think that is the intent. Its use here appears to be associated with the use of an attribute which is incorrect.

8. "Clean up" or "Gratuitously change" some names.

The purpose is to make things feel a bit more consistent and this is really our last chance to do so.

The suggested changes are as follows:

The schema file will be called ALFEventBase.xsd

BasicEventType -> EventBaseType EventDetailsType -> EventDetailType ToolExtensionDataType -> EventExtensionType BasicEvent -> Base EventDetails -> Detail ToolExtensionData -> Extension

ALFEventACKType -> ALFEventResponseType Note: The bool value is eliminated from this since there seems little point in a boolean that will always be true if it is succesfully received but otherwise not received.

ALFEvent -> EventNotice ALFEventACK -> EventNoticeResponse Note: this is to conform with the WSDL "Document Literal Wrapped" convention

The following messages are added for "synchronous events" EventNoticeWithReply EventNoticeWithReplyResponse

The EventNoticeWithReply operations is added to the ALFEventManager service

Some new ports and corresponding bindings are added to provide the base template for Service Flow services ALFServiceFlow ALFServiceFlowWithReply

9. The Credential element should be typed "any". It is likely that the credential element will be expressed as XML. It may be more covenient to contain such an element as an XML structure rather than by having it encoded or encapsualted as CData. may the CredentialType "any" allows it to take any of these formats

Additional Changes

Listed below are some other possible simplifications and name changes. These need some some further discussion/definition before we accept them.

1. Combine Detail and Extension to a single xs:any element perhaps called <payload>.

It is not clear to me there is an advantage in keeping these separate. If there is we need to make that clear. It would seem adequate to me that a tool would declare its event data and that it will either be a pure ALF vocab structure or it will be custom or it will be some combination. Forcing the division seems like it will just make it inconvenient for tools to declare their data and will mean either misuse or no use of the ALF vocabulary.

2. Eliminate the "required" attributes.

alfEventVersion on EventBaseType (nee BasicEventType) I realise the intent is to inform the recipient that the event definition is derived froma particular verision and possibly this is useful a runtime since it would possibly allow use to handle incompatible versions. This seem somewhat unlikely at this level at which it works. Maybe it is cheap enough to make that enough but something bothers me about it and I suspect that it will never be used. It is something that can be added if we ever do need it but for now it's just extra crud someone has to set before sending the event that doesn't do anything. If we have it, it seem like the schema should define the exact value it must contain.

schemaLocation on EventDetailType (nee EventDetailsType) and EventExtensionType (nee ToolExtensionData) I realise these attributes are supposed to point to the schema for the contained data but I'm not sure what the point of these attributes really is from a practical perspective. It seems to me nothing at runtime will look at these and validate the element content so perhaps they are just gratuitous and unecessary. Possibly there is a clearer way to do this since we do need tools to declare their events. Possibly the schema attribute, if we have it, needs to be higher up in the event structure.

3. Change ProductCallbackURI to ProductCallbackURL.

I think Callback implies it must be an URL and not just a URI. I'm a bit unclear how this would be used. I think it may need some more definition to make it useful. Does it define a server, a service, an operation ??? If I was trying to design to it I would presumably need a WSDL which presumably would need to be defined as part of the event declaration.

4. Eliminate the BaseEvent structure in the ALFEventResponse message.

Currently the event manager sends back the EventBase structure that it received. I'm not sure if there was a purpose to this. It seems unecessary to send the whole structure and other information might be useful also like an indication that the event matched to a service flow. Probably worth a discussion before we put it to bed.

Schema 001

ALFEventBase_001.xsd

WSDL 001

ALFEventManager_001.WSDL

<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions name="ALFEventManager"
   	targetNamespace="http://www.eclipse.org/alf/XMLSchema/Events.wsdl"
    xmlns:tns="http://www.eclipse.org/alf/XMLSchema/Events.wsdl"
   	xmlns:evt="http://www.eclipse.org/alf/XMLSchema/Events.xsd"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    >
    
  <wsdl:documentation>
	WARNING: PRELIMINARY VERSION DO NOT USE
  
      Copyright Notice
      The material in this document is Copyright (c) Serena Software, Inc. and others, 2005
      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:types>
	<xsd:schema elementFormDefault="qualified" targetNamespace="http://www.eclipse.org/alf/XMLSchema/Events.xsd"
                      xmlns:evt="http://www.eclipse.org/alf/XMLSchema/Events.xsd"
                      xmlns="http://www.eclipse.org/alf/XMLSchema/Events.xsd">
		<xsd:include schemaLocation="ALFEventBase_001.xsd" />
    </xsd:schema>
</wsdl:types>

<wsdl:message name="EventNotice">
	<wsdl:part name="parameters" element="evt:EventNotice" />
</wsdl:message>

<wsdl:message name="EventNoticeResponse">
	<wsdl:part name="parameters" element="evt:EventNoticeResponse" />
</wsdl:message>

<wsdl:portType name="ALFEventManager">
	<wsdl:operation name="EventNotice">
		<wsdl:input message="tns:EventNotice"/>
		<wsdl:output message="tns:EventNoticeResponse"/>
	</wsdl:operation>
	<wsdl:operation name="EventNoticeWithReply">
		<wsdl:input message="tns:EventNoticeWithReply"/>
		<wsdl:output message="tns:EventNoticeWithReplyResponse"/>
	</wsdl:operation>
</wsdl:portType>

<wsdl:portType name="ALFServiceFlow">
	<wsdl:operation name="EventNotice">
		<wsdl:input message="tns:EventNotice"/>
	</wsdl:operation>
</wsdl:portType>

<wsdl:portType name="ALFServiceFlowWithReply">
	<wsdl:operation name="EventNotice">
		<wsdl:input message="tns:EventNotice"/>
		<wsdl:output message="tns:EventNoticeResponse"/>
	</wsdl:operation>
</wsdl:portType>

<wsdl:binding name="ALFEventManagerSOAP" type="tns:ALFEventManager">
	<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
	<wsdl:operation name="EventNotice">
	<soap:operation soapAction="EventNotice"/>
		<wsdl:input>
			<soap:body use="literal"/>
		</wsdl:input>
		<wsdl:output>
			<soap:body use="literal"/>
		</wsdl:output>
	</wsdl:operation>
	<wsdl:operation name="EventNoticeWithReply">
	<soap:operation soapAction="EventNoticeWithReply"/>
		<wsdl:input>
			<soap:body use="literal"/>
		</wsdl:input>
		<wsdl:output>
			<soap:body use="literal"/>
		</wsdl:output>
	</wsdl:operation>
</wsdl:binding>

<wsdl:binding name="ALFServiceFlowSOAP" type="tns:ALFServiceFlow">
	<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
		<wsdl:operation name="EventNotice">
	<soap:operation soapAction="EventNotice"/>
		<wsdl:input>
			<soap:body use="literal"/>
		</wsdl:input>
	</wsdl:operation>
</wsdl:binding>

<wsdl:binding name="ALFServiceFlowWithReplySOAP" type="tns:ALFServiceFlowWithResponse">
	<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
	<wsdl:operation name="EventNotice">
		<soap:operation soapAction="EventNotice"/>
			<wsdl:input>
				<soap:body use="literal"/>
			</wsdl:input>
			<wsdl:output>
				<soap:body use="literal"/>
			</wsdl:output>
	</wsdl:operation>
</wsdl:binding>

<!-- Example service location -->
<wsdl:service name="ALFEventManager">
	<wsdl:port binding="tns:ALFEventManagerSOAP" name="ALFEventManagerSOAP">
		<soap:address location="http://localhost:8080/alfeventmgr/services/ALFEventManager"/>
	</wsdl:port>
</wsdl:service>

</wsdl:definitions>