[Ws Wiki] Update of "FrontPage/Woden/WSDLExtensions" by JohnKaputin

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Ws Wiki" for change notification.

The following page has been changed by JohnKaputin:
http://wiki.apache.org/ws/FrontPage/Woden/WSDLExtensions

New page:
= 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 properties''. Extension properties are an abstraction of extension elements and extension attributes - i.e. WSDL Components may be extended by extension properties which may originate from extension elements or attributes in a WSDL document, but this distinction is not reflected in the Component model.

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 will include two extensions based on this extension architecture and the Woden implementation will pre-register them in the extension registry. These extensions will be 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.

The Woden Extension API is defined by the interfaces declared in package {{{org.apache.woden.wsdl20.extensions}}}:
 * {{{AttributeExtensible}}}
 * {{{ElementExtensible}}}
 * {{{ExtensionElement}}}
 * {{{ExtensionSerializer}}}
 * {{{ExtensionDeserializer}}}
 * {{{UnknownExtensionElement}}}
 * {{{UnknownExtensionSerializer}}}
 * {{{UnknownExtensionDeserializer}}}
 * {{{ComponentExtensions}}}
 * {{{ExtensionRegistry}}}

WSDL extension attributes are represented in the Woden API by the interfaces defined in Package {{{org.apache.woden.xml}}}:
 * {{{XMLAttr}}}
 * {{{BooleanAttr}}}
 * {{{StringAttr}}}
 * {{{URIAttr}}}
 * {{{QNameAttr}}}
 * {{{QNameOrTokenAttr}}}
 * {{{QNameListAttr}}}
 * {{{QNameListOrTokenAttr}}}

The interfaces currently in {{{org.apache.woden.xml}}} represent just the XML types for the 'known' extension attributes, as defined for 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 to look into this.

=== 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.

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

=== SOAP extension elements and attributes (Element model) ===

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}}}.
 * wsoap:subcodes of type ''union of List of xs:QName and xs:token'' is represented by {{{QNameListOrTokenAttr}}}.

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}}}.

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}}}.

=== 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 ==

John Kaputin to complete these notes on proposed HTTP extensions, based on conventions used for SOAP binding extensions.