Apache Muse - WSDL Conventions Used by Tools

There are some conventions that we are expecting from the input WSDL as is evident from the algorithm described in the Wsdl2Java documentation. We'll cover each major portion of a WSDL document and discuss the conventions we expect when trying to extract capabilities.

• Types:
  • Namespaces: Since we extract capabilities by namespace, we expect that the input messages and resource properties (referenced in the WSRP document schema) all belong to the same namespace URI.
  • Imports: Schema imports are perfectly valid, but they will be inlined during the generation process (see the FAQ for further explanation).
  • Methods that return nothing (void in Java): This case is interesting because it deals with optimizations defined in the schema standard. It is impossible to differentiate between a method that returns xsd:anyType (equivalent to Java's org.w3c.dom.Element) and a method that returns nothing (void). The convention used to handle this ambiguity is as follows:
    1. If the method has a message whose type attribute is xsd:anyType (xsd being bound to the XML Schema namespace), then this means it returns void. This method must only have a type attribute, there must not be any other attribute (for example, a element attribute).
    2. If the method has a message whose element references an XSD element whose type is xsd:anyType or the element has no type, then it returns org.w3c.dom.Element
    The problem stems from the fact that an XSD element with type xsd:anyType is equivalent (according to the XML Schema spec) to an XSD element with no type.
  • Properties that are arrays: If a property has a minOccurs or maxOcurrs greater than one (this includes "unbounded") we consider it an array. These attributes should be set in the resource property document definition and not in the element definitions that are referenced from that document.
  • Parameters: A method can take zero or more input parameters. Method parameters are encapsulated by the element that is referenced from WSDL message for the particular operation. For example, if a message has an element attribute referencing "pre:foobar" (where pre is mapped appropriately), then parameters for this message would be created as follows:

    <xsd:element name="foobar">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element name="param1" type="xsd:string"/>
                <xsd:element name="param2" type="xsd:integer"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
                

    The preceding describes a method that takes two parameters: the first parameter (param1) is a string and the second param (param2) is an integer.
  • Parameters that are arrays: Parameters that are arrays need to be defined as above, but the minOccurs/maxOccurs attributes must be set inside of the complexType/sequence/element path defined above.
  • Return types: Since methods only return one parameter, you must define return types as a type reference on the element referenced from the message. So if your return message is called "pre:foobarResponse" (where pre is mapped appropriately). Then the return element should look like:

    <xsd:element name="foobarResponse" type="xsd:string">

    The return can be an array as well, in which case one would set the appropriate minOccurs/maxOccurs on this element.
• Messages:
  • Methods that return nothing (void in Java) must follow the convention explained above.
• PortType:
  • Single port type: We expect one portType with all of the operations defined in it.
• Binding:
  • Single binding: We expect one binding referencing the above portType. Generating the binding is a totally automated process if you already have the portType. We provide a tool for doing this (as well as merging multiple WSDL files together) called wsdlmerge.
• Service:
  • Useful address (optional): During code generation, the Axis2-specific artifact generator will try to determine the context path for the muse.xml and services.xml descriptors. This information can be included in the address element. If it is not included, a reasonable default will be used. For example:

    location="http://localhost:8080/simple/services/SimpleResource"

    would translate to a context path of SimpleResource in the muse.xml decsriptor and a service name of SimpleResource in the services.xml descriptor.