Differences between revisions 13 and 14
Revision 13 as of 2006-05-18 13:21:51
Size: 23595
Editor: ArthurRyman
Comment:
Revision 14 as of 2009-09-20 22:48:52
Size: 23595
Editor: localhost
Comment: converted to 1.6 markup
No differences found!

WSDL Extensions

Overview

The Woden API has 2 WSDL models; the Component model (org.apache.woden.wsdl20) represents the abstract WSDL component model described in the WSDL 2.0 Part 1 spec and the Element model (org.apache.woden.wsdl20.xml) represents the WSDL 2.0 XML Infoset (i.e. the XML representation of the WSDL 2.0 components described in Part 1). Both WSDL models are extensible. The Element model supports extension elements and extension attributes. The Component model supports extension components and extension properties. Extension components and properties are an abstraction of extension elements and extension attributes - i.e. WSDL Components may be extended by extension components and properties which may originate from extension elements or attributes in a WSDL document, but this distinction is not reflected in the Component model.

See the editors copy of the WSDL 2.0 Part 1 Core Language spec at: http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20.html?content-type=text/html;%20charset=utf-8

Woden's WSDL extension architecture is based on that used in WSDL4J for handling extension elements and attributes. It has been enhanced in Woden to support Component extension properties too. Applications can follow the Woden Extension model to define WSDL extensions and register them in an extension registry. At runtime Woden will query the extension registry when it encounters unknown (i.e. non-WSDL) content and invoke any registered extension artifacts via a well defined API to handle the unknown content. These artifacts include Java classes or objects, such as serializers and deserializers and Java type mappings.

So for example, if Woden encounters some unknown content in a WSDL document (i.e. non-WSDL elements or attributes) it will check if an extension has been registered for this content and if so, will use the registered deserializer to convert the XML content into the registered Java type. A similar approach will exist for serializing Java types into extension elements or attributes. When initializing the Component model from the Element model, Woden will use registered component extensions to map the extension elements or attributes in the Element model to extension properties in the Component model.

The Woden API includes four extensions based on this extension architecture and the Woden implementation pre-registers them in the extension registry. These extensions are operation safety extension, wsdlx:safe, the operation RPC signature extenstion, wrpc:signature, the SOAP binding extensions, and HTTP binding extensions described in the WSDL 2.0 Part 2 Adjuncts spec. Applications can use this same extension architecture to create their own extensions and register them in the extension registry.

See the editors copy of the WSDL 2.0 Part 2 Adjuncts spec at: http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20-adjuncts.html?content-type=text/html;%20charset=utf-8

The Woden Extension API is defined by the interfaces declared in package org.apache.woden.wsdl20.extensions. These are implemented by classes from the WSDL Element and Component models or by the extension classes themselves. These interfaces form a well defined API used by Woden to invoke extension-specific logic without the need for extension-specific additions to the Woden API. Some of these methods are discussed below.

The interfaces in package org.apache.woden.wsdl20.extensions are:

  • AttributeExtensible declares methods like getExtensionAttribute and setExtensionAttribute, used by a parent WSDL element for handling its extension attributes. Inherited by org.apache.woden.wsdl20.xml.WSDLElement, the super type of all WSDL element interfaces.

  • ElementExtensible declares similar accessor / modifier methods, used by a parent WSDL element for handling its extension elements. Also inherited by WSDLElement.

  • ExtensionElement declares methods like isRequired and getExtensionType which are common to all extension elements. Implementors are registered as the Java type to which the extension element will be mapped.

  • ExtensionSerializer declares the marshall method for serializing an ExtensionElement object into an XML element. The implementor is registered as the extension element's serializer.

  • ExtensionDeserializer declares the unmarshall method for deserializing an XML element into the registered ExtensionElement subclass. The implementor is registered as the extension element's deserializer.

  • UnknownExtensionElement an implementation of ExtensionElement which provides a default Java type for extension elements which have not been registered (i.e. unknown Java type). This class basically wraps the org.w3c.dom.Element representing the extension element.

  • UnknownExtensionSerializer an implementation of ExtensionSerializer for serializing an UnknownExtensionElement object to an XML element.

  • UnknownExtensionDeserializer an implementation of ExtensionDeserializer for deserializing an XML element into an UnknownExtensionElement object.

  • ComponentExtensions declaring just the getNamespace method, this interfaces groups together all extension properties of a WSDL component that belong to the same namespace. Implementors will add accessor and modifier methods specific to those extensions properties. The implementor is registered for a given WSDL component and namespace (e.g. the Binding component has the ComponentExtensions subtype, SOAPBindingExtensions, registered with the SOAP namespace URI).

  • ExtensionRegistry defines methods to register and query serializers, deserializers and Java types for extension elements or attributes and to instantiate those Java types. Also has methods to register, query and instantiate Java subtypes of ComponentExtensions.

WSDL extension attributes are represented in the Woden API by the interfaces defined in package org.apache.woden.xml. These interfaces declare methods to convert the string values of XML attributes into the appropriate Java types and to query the original string value. An implementator of one of these interfaces is registered for each extension attribute and is invoked by Woden to deserialize the XML attribute into the appropriate Java type. It then stores both the original string value and the typed Java object.

The interfaces currently defined in package org.apache.woden.xml are:

  • XMLAttr a super type for all XML attribute types, it defines common methods for converting an attribute from a string value into a specific Java type.

  • BooleanAttr converts an attribute of type xs:boolean to java.lang.Boolean

  • StringAttr converts an attribute of type xs:string to java.lang.String

  • URIAttr converts an attribute of type xs:anyURI to java.net.URI

  • QNameAttr converts an attribute of type xs:QName to javax.xml.namespace.QName

  • QNameListAttr converts an attribute of type list of xs:QName to a javax.xml.namespace.QName array

  • QNameOrTokenAttr converts an attribute of type union of xs:QName and xs:token to either a QName or a String and provides methods to query the type.

  • QNameListOrTokenAttr converts an attribute of type union of List of xs:QName and xs:token to either a QName array or a String and provides methods to query the type.

  • UnknownAttr An implementation of XMLAttr used for extension attributes that have not been registered (i.e. whose type is unknown). Returns the attribute's string value, but does not attempt to convert it into a specific Java type.

The interfaces currently in org.apache.woden.xml represent just the XML types for the 'known' extension attributes, as defined for RPC signature, SOAP and HTTP bindings in the WSDL 2.0 Part 2 Adjuncts spec. Obviously, this package needs to be expanded to cater for any possible attribute types that might appear in user-defined extensions as well. There is a 'todo' in the Woden TaskList wiki page about this.

Interface Operation Extensions

The wsdlx:safe extension is contained in the following packages:

  • org.apache.woden.wsdl20.extensions - ExtensionConstants defines the XML names, InterfaceOperationExtensions defines the {safety} property

  • org.apache.woden.internal.wsdl20.extensions - InterfaceOperationExtensionsImpl implements the {safety} property

The wrpc:signature extension is contained in the following packages:

  • org.apache.woden.wsdl20.extension.rpc - RPCInterfaceOperationsExtentions defines the {rpc signature} property and the types Argument and Direction, RPCConstants defines the XML names

  • org.apache.woden.internal.wsdl20.extension.rpc - RPCInterfaceOperationExtensionsImpl implements the {rpc signature} property

  • org,apache.woden.xml - ArgumentArrayAttr - implements the type of the wrpc:signature attribute

SOAP Binding Extensions

The package org.apache.woden.wsdl20.extensions.soap declares the API for SOAP binding extensions, including both the Element model extensions and the Component model extensions. The package org.apache.woden.internal.wsdl20.extensions.soap defines the implementation of that API.

SOAP extension elements and attributes (Element model)

The noarg constructor of the implementation class org.apache.woden.internal.wsdl20.extensions.PopulatedExtensionRegistry registers the SOAP binding extension elements and attributes.

The <wsdl:binding> element has 3 SOAP extension attributes, which are registered as attribute extensions of BindingElement:

  • wsoap:version of type xs:string is represented by StringAttr.

  • wsoap:protocol of type xs:anyURI is represented by URIAttr.

  • wsoap:mepDefault of type xs:anyURI is represented by URIAttr.

The <wsdl:fault> element within <wsdl:binding> has 2 SOAP extension attributes, which are registered as attribute extensions of BindingFaultElement:

  • wsoap:code of type union of xs:QName and xs:token is represented by QNameOrTokenAttr. Note that the implementation class actually registered in the extension registry is called QNameOrTokenAnyAttrImpl and this performs an additional check that an xs:token has the value #any.

  • wsoap:subcodes of type union of List of xs:QName and xs:token is represented by QNameListOrTokenAttr. Note that implementation class actually registered in the extension registry is called QNameListOrTokenAnyAttrImpl and this performs an additional check that an xs:token has the value #any.

The <wsdl:operation> element within <wsdl:binding> has 2 SOAP extensions attributes, which are registered as attribute extensions of BindingOperationElement:

  • wsoap:mep of type xs:anyURI is represented by URIAttr.

  • wsoap:action of type xs:anyURI is represented by URIAttr.

The <wsoap:module> extension element may appear within the binding-related WSDL elements <wsdl:binding>, <wsdl:fault>, <wsdl:input>, <wsdl:output>, <wsdl:infault>, <wsdl:outfault>. It is represented in the Element model by the interface SOAPModuleElement and in the Component model by SOAPModule. These interfaces are implemented by a single class, SOAPModuleImpl.

The <wsoap:header> extension element may appear within the binding-related WSDL elements <wsdl:fault>, <wsdl:input> and <wsdl:output>. It is represented in the Element model by the interface SOAPHeaderBlockElement and in the Component model by SOAPHeaderBlock. These interfaces are implemented by a single class, SOAPHeaderBlockImpl.

SOAP extension properties (Component model)

Each binding-related WSDL Component that is extended by SOAP properties has a corresponding subtype of the ComponentExtensions interface which encapsulates those component-specific properties.

The noarg constructor of the implementation class org.apache.woden.internal.wsdl20.extensions.PopulatedExtensionRegistry registers these SOAP component extensions.

SOAPBindingExtensions declares the SOAP properties that extend the Binding component:

  • {soap version} mapped from the wsoap:version attribute
  • {soap underlying protocol} mapped from the wsoap:protocol attribute
  • {soap mep default} mapped from the wsoap:mepDefault attribute
  • {soap modules} a collection of SOAPModule objects, mapped from the set of <wsoap:module> child elements of <wsdl:binding>

SOAPBindingFaultExtensions declares the SOAP properties that extend the BindingFault component:

  • {soap fault code} mapped from the wsoap:code attribute
  • {soap fault subcodes} mapped from the wsoap:subcodes attribute
  • {soap modules} a collection of SOAPModule objects, mapped from the set of <wsoap:module> child elements of binding <wsdl:fault>

  • {soap headers} a collection of SOAPHeaderBlock objects, mapped from the set of <wsoap:header> child elements of binding <wsdl:fault>

SOAPBindingOperationExtensions declares the SOAP properties that extend the BindingOperation component:

  • {soap mep} mapped from the wsoap:mep attribute
  • {soap action} mapped from the wsoap:action attribute
  • {soap modules} a collection of SOAPModule objects, mapped from the set of <wsoap:module> child elements of binding <wsdl:operation>

SOAPBindingFaultReferenceExtensions declares the SOAP properties that extend the BindingFaultReference component:

  • {soap modules} a collection of SOAPModule objects, mapped from the set of <wsoap:module> child elements of binding operation <wsdl:infault> or <wsdl:outfault>

SOAPBindingMessageReferenceExtensions declares the SOAP properties that extend the BindingMessageReference component:

  • {soap modules} a collection of SOAPModule objects, mapped from the set of <wsoap:module> child elements of binding operation <wsdl:input> or <wsdl:output>

  • {soap headers} a collection of SOAPHeaderBlock objects, mapped from the set of <wsoap:header> child elements of binding operation <wsdl:input> or <wsdl:output>

HTTP Binding Extensions

The HTTP Binding Extensions have not yet been developed in Woden (March 2006). This section provides guidance for creating these extensions by proposing package and interface names that follow the same conventions used for the SOAP binding extensions described above. The see Woden code for SOAP binding extensions for detailed examples.

The package org.apache.woden.wsdl20.extensions.http should be created to contain the HTTP binding extensions interfaces. The package org.apache.woden.internal.wsdl20.extensions.http should contain the implementation classes.

HTTP extension elements and attributes (Element model)

The noarg constructor of the implementation class PopulatedExtensionRegistry should register the HTTP binding extension elements and attributes, similarly to those of the SOAP binding extensions.

The <wsdl:binding> element has 4 HTTP extension attributes, which should be registered as attribute extensions of BindingElement:

  • whttp:methodDefault of type xs:string is represented by StringAttr.

  • whttp:queryParameterSeparatorDefault of type xs:string is represented by StringAttr.

  • whttp:cookies of type xs:boolean is represented by BooleanAttr.

  • whttp:transferCodingDefault of type xs:string is represented by StringAttr.

The <wsdl:fault> element within <wsdl:binding> has 2 HTTP extension attributes, which should be registered as attribute extensions of BindingFaultElement:

  • whttp:code of type union of xs:int, xs:token is represented by IntOrTokenAttr, which needs to be created in package org.apache.woden.xml and based on QNameOrTokenAttr.

  • whttp:transferCoding of type xs:string is represented by StringAttr.

Note: for attribute whttp:code, the class implementing IntOrTokenAttr should be called IntOrTokenAnyAttrImpl and should add the same check as per class QNameOrTokenAnyAttrImpl, which is to check for an xs:token value of #any in the convert method.

The <wsdl:operation> element within <wsdl:binding> has 7 HTTP extension attributes, which should be registered as attribute extensions of BindingOperationElement:

  • whttp:location of type xs:anyURI is represented by URIAttr.

  • whttp:method of type xs:string is represented by StringAttr.

  • whttp:inputSerialization of type "xs:string" is represented by StringAttr.

  • whttp:outputSerialization of type "xs:string" is represented by StringAttr.

  • whttp:faultSerialization of type "xs:string" is represented by StringAttr.

  • whttp:queryParameterSeparator of type xs:string is represented by StringAttr.

  • whttp:transferCodingDefault of type "xs:string" is represented by StringAttr.

The <wsdl:input> and <wsdl:output> elements within binding <wsdl:operation> have 1 HTTP extension attribute, which should be registered as attribute extensions of BindingMessageReferenceElement:

  • whttp:transferCoding of type "xs:string" is represented by StringAttr.

The <wsdl:endpoint> element within <wsdl:service> has 2 HTTP extension attributes, which should be registered as attribute extensions of EndpointElement:

  • whttp:authenticationType of type xs:token is represented by TokenAttr.

  • whttp:authenticationRealm of type xs:string is represented by StringAttr.

The <whttp:header> extension element may appear within the binding-related WSDL elements <wsdl:fault>, <wsdl:input> and <wsdl:output>. It should be represented in the Element model by the interface HTTPHeaderElement and in the Component model by HTTPHeader. These interfaces should be implemented by a single class, HTTPHeaderImpl.

HTTPHeaderElement should extend ExtensionElement and also AttributeExtensible and ElementExtensible (because it is itself extensible). For its method declarations, it should follow the element extension conventions used for SOAP and those used for QName dereferencing:

  • void addDocumentationElement(DocumentationElement)

  • DocumentationElement[] getDocumentationElements()

  • void setName(String)

  • String getName()

  • void setTypeName(QName)

  • QName getTypeName()

  • XmlSchemaType getType()

  • void setParentElement(WSDLElement)

  • WSDLElement getParentElement()

Note 1: the implementation class HTTPHeaderImpl should store the QName specified by the setTypeName method and its getType method should dynamically resolve this QName to an XmlSchemaType stored within TypesElement. See PropertyImpl.getConstraint() for an example.

Note 2: methods for the 'required' attribute are declared in the super interface ExtensionElement.

HTTPHeader should follow the component extension conventions used for SOAP in deriving method declarations from the HTTP Header properties:

  • String getName() for property {name}

  • TypeDefinition getTypeDefinition() for property {type definition}

  • Boolean isRequired for property {required}

  • WSDLComponent getParent() for property {parent}

HTTP extension properties (Component model)

Each binding-related WSDL Component that is extended by HTTP properties should have a corresponding subtype of the ComponentExtensions interface which encapsulates those component-specific properties.

The noarg constructor of the implementation class PopulatedExtensionRegistry should register these HTTP component extensions, similarly to those registered for the SOAP component extensions.

The following interfaces should be created in package org.apache.woden.wsdl20.extensions.http as subtypes of ComponentExtensions (and their implementation classes created in package org.apache.woden.internal.wsdl20.extensions.http):

HTTPBindingExtensions should be created with methods to return the HTTP properties that extend the Binding component:

  • {http method default} mapped from the whttp:methodDefault attribute requires the method String getHttpMethodDefault()

  • {http query parameter separator default} mapped from the whttp:queryParameterSeparatorDefault attribute requires the method String getHttpQueryParameterSeparatorDefault

  • {http cookies} mapped from the whttp:cookies attribute requires the method String getHttpCookies()

  • {http transfer coding default} mapped from the whttp:transferCodingDefault attribute requires the method String getHttpTransferCodingDefault()

HTTPBindingFaultExtensions should be created with methods to return the HTTP properties that extend the BindingFault component:

  • {http error status code} mapped from the whttp:code attribute requires the method HTTPErrorStatusCode getHttpErrorStatusCode(), where HTTPErrorStatusCode is to be created as a type safe enumeration similar to org.apache.woden.wsdl20.enumeration.SOAPFaultCode

  • {http transfer coding} mapped from the whttp:transferCoding attribute requires the method String getHttpTransferCoding()

  • {http headers} mapped from the set of <whttp:header> child elements of a binding <wsdl:fault> element requires the method HTTPHeader[] getHttpHeaders()

HTTPBindingOperationExtensions should be created with methods to return the HTTP properties that extend the BindingOperation component:

  • {http location} mapped from the whttp:location attribute requires the method java.net.URI getHttpLocation()

  • {http method} mapped from the whttp:method attribute requires the method String getHttpMethod()

  • {http input serialization} mapped from the whttp:inputSerialization attribute requires the method String getHttpInputSerialization()

  • {http output serialization} mapped from the whttp:outputSerialization attribute requires the method String getHttpOutputSerialization()

  • {http fault serialization} mapped from the whttp:faultSerialization attribute requires the method String getHttpFaultSerialization()

  • {http query parameter separator} mapped from the whttp:queryParameterSeparator attribute requires the method String getHttpQueryParameterSeparator()

  • {http transfer coding default} mapped from whttp:transferCodingDefault requires the method String getHttpTransferCodingDefault()

HTTPBindingMessageReferenceExtensions should be created with methods to return the HTTP properties that extend the BindingMessageReference component:

  • {http transfer coding} mapped from the whttp:transferCoding attribute requires the method String getHttpTransferCoding()

  • {http headers} mapped from the set of <whttp:header> child elements of a binding operation <wsdl:input> or <wsdl:output> element requires the method HTTPHeader[] getHttpHeaders()


END of WSDL Extensions

FrontPage/Woden/WSDLExtensions (last edited 2009-09-20 22:48:52 by localhost)