Within a WSDL document, the binding describes how the service is bound to the SOAP messaging protocol. Following the WSDL 1.1 specification, located at http://www.w3.org/TR/wsdl), the WSDL SOAP binding can be either RPC style or document style. In addition, the binding can have an encoded use or a literal use. Of the possible combinations, WSO2 SOA Enablement Server supports the following:

The combinations wrapped/literal and rpc/literal are compliant with WS-I Basic Profile Version 1.0.

The RPC/encoded binding style was mostly used during the early days of Web services. Today the de-facto standard is document/literal (or wrapped document/literal) because of its compatibility with .NET services and because of the WS-I basic profile. This is the default binding/encoding style of WSDL documents generated by WSO2 SOA Enablement Server Java2WSDL. A WSDL document with this style of binding is in Example 170. We see the style attribute of the soap:binding element has the value document and the soap:body element specifies the literal use.

<wsdl:binding name="HelloService" type="tns:HelloService">
    <soap:binding style="document" 
    transport="http://schemas.xmlsoap.org/soap/http"/>
    <wsdl:operation name="hello">
        <soap:operation soapAction="helloService" style="document"/>
        <wsdl:input>
            <soap:body parts="name" use="literal"/>
        </wsdl:input>
        <wsdl:output>
            <soap:body parts="response" use="literal"/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

WSDL documents utilizing all four supported binding styles are presented below for the following Hello service:

public interface Hello {
    String hello(String s);
}

<wsdl:message name='Hello_hello_Response_Soap'>
    <wsdl:part name='response' type='xsd:string'/>
</wsdl:message>
<wsdl:message name='Hello_hello__Request_Soap'>
    <wsdl:part name='name' type='xsd:string'/>
</wsdl:message>
<wsdl:portType name='Hello'>
    <wsdl:operation name='hello' parameterOrder='name'>
        <wsdl:input message='tns:Hello_hello__Request_Soap'/>
        <wsdl:output message='tns:Hello_hello_Response_Soap'/>
    </wsdl:operation>
</wsdl:portType>
<wsdl:binding name='Hello' type='tns:Hello'>
    <soap:binding transport='http://schemas.xmlsoap.org/soap/http' 
        style='rpc'/>
    <wsdl:operation name='hello'>
        <soap:operation soapAction='' style='rpc'/>
        <wsdl:input>
            <soap:body parts='name' use='encoded' 
            encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' 
            namespace='http://wso2.com/wsdl/hello/Hello#hello#KExqYXZhL2xhbmcvU3RyaW5nOylMamF2YS9sYW5nL1N0cmluZzs='/>
        </wsdl:input>
        <wsdl:output>
            <soap:body parts='response' use='encoded' 
            encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' 
            namespace='http://wso2.com/wsdl/hello/Hello#hello#KExqYXZhL2xhbmcvU3RyaW5nOylMamF2YS9sYW5nL1N0cmluZzs='/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

<wsdl:types>
    <xsd:schema elementFormDefault="qualified"
        targetNamespace="http://wso2.com/xsd/SchemaTypes/"
        xmlns:tns="http://wso2.com/xsd/SchemaTypes/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <xsd:element name="name" nillable="true" type="xsd:string"/>
        <xsd:element name="string_Response" nillable="true" 
            type="xsd:string"/>
    </xsd:schema>
</wsdl:types>

<wsdl:message name='Hello_hello_Response_Soap'>
    <wsdl:part name='response' element='ns0:string_Response'/>
</wsdl:message>
<wsdl:message name='Hello_hello__Request_Soap'>
    <wsdl:part name='name' element='ns0:name'/>
</wsdl:message>
<wsdl:portType name='Hello'>
    <wsdl:operation name='hello' parameterOrder='name'>
        <wsdl:input message='tns:Hello_hello__Request_Soap'/>
        <wsdl:output message='tns:Hello_hello_Response_Soap'/>
    </wsdl:operation>
</wsdl:portType>
<wsdl:binding name='Hello' type='tns:Hello'>
    <soap:binding transport='http://schemas.xmlsoap.org/soap/http'
        style='document'/>
    <wsdl:operation name='hello'>
        <soap:operation soapAction='hello' style='document'/>
        <wsdl:input>
            <soap:body parts='name' use='literal'/>
        </wsdl:input>
        <wsdl:output>
            <soap:body parts='response' use='literal'/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

Document/Literal Wrapped  ^Locate

This is very similar to document/literal. The difference is the wrapping of parameters. All method parameters are wrapped into an element whose name is the same as the name of the operation. The wrapping element is described in the XML schema, so the message content can easily be validated against the schema. The wrapper element type is xsd:complexType, containing the xsd:sequence. This sequence contains one element for each parameter. The name of the wrapper element can be used to dispatch the call on the server side.

Wrapped document/literal binding is the de-facto standard used by Microsoft .NET. Because it maps the parameters inside the wrapper element, the message can contain only one part, making it WS-I compliant.

The wrapper elements are recognized according to the following criteria:

• The input message has only one part inside the SOAP body.

• That part is an element.

• The element name is the same as the name of the operation.

• The type of the element is complexType and it has no attributes.

	Note
	Wrapped document/literal binding has been supported since WSO2 SOA Enablement Server for Java 4.7.

Because the WS-I basic profile dictates that no more than one message part be present inside a SOAP message, we recommend using wrapped/literal to publish your services. Example 173 contains a wrapped document/literal-bound WSDL for the Hello service.

Example 173. Wrapped Document/Literal Binding for the Hello Service

<wsdl:types>
    <xsd:schema elementFormDefault="qualified"
        targetNamespace="http://wso2.com/wsdl/hello/"
        xmlns:tns="http://wso2.com/wsdl/hello/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <xsd:element name="hello">
            <xsd:complexType>
                <xsd:sequence>
                    <xsd:element name="name" nillable="true" 
                        type="xsd:string"/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
        <xsd:element name="helloResponse">
            <xsd:complexType>
                <xsd:sequence>
                    <xsd:element name="response" nillable="true" 
                        type="xsd:string"/>
                </xsd:sequence>
            </xsd:complexType>
        </xsd:element>
    </xsd:schema>
</wsdl:types>

<wsdl:message name='Hello_hello_Response_Soap'>
    <wsdl:part name='parameters' element='tns:helloResponse'/>
</wsdl:message>
<wsdl:message name='Hello_hello__Request_Soap'>
    <wsdl:part name='parameters' element='tns:hello'/>
</wsdl:message>
<wsdl:portType name='Hello'>
    <wsdl:operation name='hello'>
        <wsdl:input message='tns:Hello_hello__Request_Soap'/>
        <wsdl:output message='tns:Hello_hello_Response_Soap'/>
    </wsdl:operation>
</wsdl:portType>
<wsdl:binding name='Hello' type='tns:Hello'>
    <soap:binding transport='http://schemas.xmlsoap.org/soap/http'
        style='document'/>
    <wsdl:operation name='hello'>
        <soap:operation soapAction='hello' style='document'/>
        <wsdl:input>
            <soap:body parts='parameters' use='literal'/>
        </wsdl:input>
        <wsdl:output>
            <soap:body parts='parameters' use='literal'/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

<wsdl:message name='Hello_hello_Response_Soap'>
    <wsdl:part name='response' type='xsd:string'/>
</wsdl:message>
<wsdl:message name='Hello_hello__Request_Soap'>
    <wsdl:part name='name' type='xsd:string'/>
</wsdl:message>
<wsdl:portType name='Hello'>
    <wsdl:operation name='hello' parameterOrder='name'>
        <wsdl:input message='tns:Hello_hello__Request_Soap'/>
        <wsdl:output message='tns:Hello_hello_Response_Soap'/>
    </wsdl:operation>
</wsdl:portType>
<wsdl:binding name='Hello' type='tns:Hello'>
    <soap:binding transport='http://schemas.xmlsoap.org/soap/http'
        style='rpc'/>
    <wsdl:operation name='hello'>
        <soap:operation soapAction='' style='rpc'/>
        <wsdl:input>
            <soap:body parts='name' use='literal' 
            namespace='http://wso2.com/wsdl/hello/Hello#hello#KExqYXZhL2xhbmcvU3RyaW5nOylMamF2YS9sYW5nL1N0cmluZzs='/>
        </wsdl:input>
        <wsdl:output>
            <soap:body parts='response' use='literal' 
            namespace='http://wso2.com/wsdl/hello/Hello#hello#KExqYXZhL2xhbmcvU3RyaW5nOylMamF2YS9sYW5nL1N0cmluZzs='/>
        </wsdl:output>
    </wsdl:operation>
</wsdl:binding>

The structure of WSDL is modular. The Java2WSDL utility works in two modes:

The latter mode can be useful in situations when you do not want to use the WSDL directly but have it reused by another service. For more information, please refer to Partially Generated WSDL File .

Use Class Inclusion and Exclusion when you do not wish to map private sections of your frameworks. The settings are delegated to Java2Schema. See Class Inclusion and Exclusion in Java2Schema for more information.

By default, Java2WSDL puts all public methods of a service class into the WSDL. However, problems can occur, such as a service implementing a configurable interface which should not be part of public operations. This is why Java2WSDL allows exclusion of methods.

Each method can be targeted using: packageName.className.methodNamesignature .

Method inclusion is used with class exclusion. It allows you to use methods from a class you otherwise wish to keep private. There is a similar case with the Java2Schema Tool (see Java2Schema: Class Inclusion and Exclusion.

See the Method Signature Listing example for a description of how to find the method signature.

A method can be designated one-way instead of the default request-response. In this case, no SOAP response is generated. Only an HTTP notification is sent back. This can be useful for notifications if no response is expected. Use the --one-way parameter and the method name to set a method as one-way, as follows:

Java2WSDL --one-way examples.package.Service.method(Ljava/lang/String;)V org.Service

For more information, please refer to Example 181 .

WSO2 SOA Enablement Server fully supports attachments. An attachment is binary data processed as a directional stream. The way that attachments are represented is described in the Attachments section of Java2Schema.

WSO2 SOA Enablement Server supports either Multipurpose Internet Mail Extension (MIME) or Direct Internet Message Encapsulation (DIME) attachments. The default setting is for MIME attachments. To change the type of attachment to DIME, use the advanced --attachment-type option and set the value to dime.

There are three possible directions for an attachment:

The default direction is input/output. There are two ways to change the direction. The first is with the --set-attachment option for the Java2WSDL Tool. The second, recommended way is to use the classes described in Java2Schema attachments. With these classes, the direction of the attachment is automatically set as input or output according to the class type.

	Note
	When generating WSDLs with MIME attachments, the generated MIME content type is 'application/octet-stream' and not 'application/binary', as we had used previously. This value can be changed in the deployment descriptor of the builtin_serialization package.

Setting custom inheritance paths is a feature of Java2Schema. See Multiple Inheritance.

Extra type mapping allows the user to map additional Java types into the WSDL and send them via SOAP. You need this when your interface uses type polymorphism. Often, a method parameter is just an interface allowing for more loosely coupled implementations. The WSDL for such a service may not contain all the required information. One example is a method with an array of objects as a parameter. Adding a class instance to this array may prevent the opposite side from understanding the message.

The following command maps two types, examples.StructureA and examples.StructureB, to their XML Schema representation and adds them to the target WSDL. If the structure is sent, necessary information can be extracted from the WSDL.

Java2WSDL examples.package.Service --add-type examples.StructureA 
                --add-type examples.StructureB

Java type mapping can be customized using deployment descriptors (Please see Deployment Descriptors). If the user already has a descriptor, he can simply tell Java2WSDL to use it, with the --deployment-descriptor parameter. Note that the deployment descriptor and processing options must be set together, as in the following command:

Java2WSDL --deployment-descriptor package.xml --processing MyProcessing 
                example.service.MyService

This command tells Java2Schema to parse the deployment descriptor file package.xml. The processing node inside the descriptor named Processing is taken and put into the mapping context. If the descriptor contains additional information--about type mapping, for example--WSO2 SOA Enablement Server will hold the new settings.

The Java2Schema utility handles custom mapping. For more details, see Java2 Schema: Schema Reference and Custom Mapping.

Java2WSDL generates custom WSDL extensions to help a related tool, WSDL2Java, generate Java classes easily.

Each .class or source file processed or used during compilation must be in the current classpath. Java2WSDL can extend the classpath for custom purposes with the --classpath parameter, which has the following syntax:

Java2WSDL --classpath c:\temp classname

Once Web service class sources are available in the classpath, parameter names are read from them and fed into WSDL. This occurs when either Java2WSDL or Runtime Publishing is used. The same occurs with the contents of deployment packages.

The following basic properties are related:

Target namespaces are determined by the package name. The filename is mapped to a namespace. The endpoint URI can be changed for each class (and therefore for each service) separately. The command in Example 176 sets the WSDL filename, target namespace and endpoint URI for the BasicProperties class.

Java2WSDL --package-mapping example.tools.java2wsdl.BasicProperties=http://my.org/

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.BasicProperties;

public interface Service {
    public int serviceMethodA();

    public void serviceMethodB();
}

In Example 176 , the file ExampleWSDL.wsdl is created. Its target namespace is http://my.org/ and the service endpoint URI is set to http://my.org/Service'/, as can be seen in Example 177 .

<?xml version='1.0'?>
<wsdl:definitions name="example.tools.java2wsdl.BasicProperties.Service"
    targetNamespace="http://my.org/" xmlns:map="http://systinet.com/mapping/"
    xmlns:ns0="http://systinet.com/xsd/SchemaTypes/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://my.org/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <wsdl:types>
        <xsd:schema elementFormDefault="qualified"
            targetNamespace="http://systinet.com/xsd/SchemaTypes/"
            xmlns:tns="http://systinet.com/xsd/SchemaTypes/" 
            xmlns:xsd="http://www.w3.org/2001/XMLSchema">
            <xsd:element name="int_Response" type="xsd:int"/>
        </xsd:schema>
    </wsdl:types>
    <wsdl:message name="Service_serviceMethodB_1_Request"/>
    <wsdl:message name="Service_serviceMethodA_1_Request"/>
    <wsdl:message name="Service_serviceMethodB_Response"/>
    <wsdl:message name="Service_serviceMethodA_Response">
        <wsdl:part element="ns0:int_Response" name="response"/>
    </wsdl:message>
    <wsdl:portType name="Service">
        <wsdl:operation name="serviceMethodA">
            <wsdl:input message="tns:Service_serviceMethodA_1_Request"/>
            <wsdl:output message="tns:Service_serviceMethodA_Response"/>
        </wsdl:operation>
        <wsdl:operation name="serviceMethodB">
            <wsdl:input message="tns:Service_serviceMethodB_1_Request"/>
            <wsdl:output message="tns:Service_serviceMethodB_Response"/>
        </wsdl:operation>
    </wsdl:portType>
    <wsdl:binding name="Service" type="tns:Service">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
        <wsdl:operation name="serviceMethodA">
            <map:java-operation name="serviceMethodA" signature="KClJ"/>
            <soap:operation
                soapAction="http://my.org/Service#serviceMethodA#KClJ" style="document"/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
        <wsdl:operation name="serviceMethodB">
            <map:java-operation name="serviceMethodB" signature="KClW"/>
            <soap:operation
                soapAction="http://my.org/Service#serviceMethodB#KClW" style="document"/>
            <wsdl:input>
                <soap:body use="literal"/>
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal"/>
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>
    <wsdl:service name="JavaService">
        <wsdl:port binding="tns:Service" name="Service">
            <soap:address location="http://my.org/Service"/>
        </wsdl:port>
    </wsdl:service>
</wsdl:definitions>

The default values for generated WSDLs are set in the WSO2 SOA Enablement Server configuration (please see Preferences in wasp/conf/clientconf.xml). They are initially set during the installation phase. The default value is the document binding style with literal encoding.

You can override the default values using:

Please see the section SOAP Binding and Encoding Styles for a full description of binding styles.

The following command changes from default to RPC/encoded binding for the RpcVsDocumentService:

Java2WSDL --soap-encoding-style encoded --soap-binding-style
                rpc example.tools.java2wsdl.RpcVsDocument.Service

To change back to document/literal, use:

Java2WSDL --soap-encoding-style literal --soap-binding-style document
            example.tools.java2wsdl.RpcVsDocument.Service

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.RpcVsDocument;

public interface Service {
    public int serviceMethodA();

    public void serviceMethodB(String s);
}

The --disable-bindings parameter in the following command causes Java2WSDL to exclude the binding and service sections of the WSDL file for the PartialWSDL service:

Java2WSDL --disable-bindings example.tools.java2wsdl.PartialWSDL.Service

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.PartialWSDL;

public interface Service {
    public int serviceMethodA();

    public void serviceMethodB(String s);
}

To simplify creation of method signatures, use the Java2WSDL --list-signatures class option, which prints the signatures of all class methods. The following command performs this for the class shown in Example 180:

Java2WSDL --list-signatures example.tools.java2wsdl.MethodSignatures.Service

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.MethodSignatures;


/**
 * Methods in class Service have following signatures:
 *
 * example.tools.java2wsdl.MethodSignatures.Service.echoVoid()V
 * example.tools.java2wsdl.MethodSignatures.Service.echoInt(I)I
 * example.tools.java2wsdl.MethodSignatures.Service.echoList(
 * Ljava/util/List;)Ljava/lang/String;
 */
public class Service {
    public void echoVoid() {
    }

    public int echoInt(int i) {
        return i;
    }

    public String echoList(java.util.List list) {
        return list.toString();
    }
}

Methods in a Web service are normally two-way, request-response. In some cases you may need to treat a method as one-way. For example, imagine a service with two methods. The first method returns an integer representing a status code. The second takes a parameter which might be heavily processed. In this case, it is better to process the second method as one-way. The following command uses the --one-way parameter to generate serviceMethodB in the OneWay service as one-way, while other methods are still generated as request-response:

Java2WSDL --one-way example.tools.java2wsdl.OneWay.Service.serviceMethodB
(Ljava/lang/String;)V example.tools.java2wsdl.OneWay.Service

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.OneWay;

public interface Service {
    public int serviceMethodA();

    public void serviceMethodB(String s);
}

Sometimes a number of services might share common types. The default behavior of Java2WSDL is to generate such types into the WSDL for each service. Java2WSDL can be told to generate all types into one common WSDL and let the services reuse the definitions.

Each of the services ServiceA, ServiceB and ServiceC uses the common type Struct. The following command generates three WSDL files for these services. Each file contains a definition of the Struct type.

Java2WSDL --reuse-types example.tools.java2wsdl.ReuseTypes.a.ServiceA
                    example.tools.java2wsdl.ReuseTypes.b.ServiceB example.tools.java2wsdl.ReuseTypes.c.ServiceC

//Service A

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.OneWay;

public interface Service {
  public int serviceMethodA();
  public void serviceMethodB(String s);
}

//Service B


// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.ReuseTypes.b;
import example.tools.java2wsdl.ReuseTypes.common.Structure;

public interface ServiceB {
  Structure echo(Structure p0);
}


//Service C


// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.ReuseTypes.c;
import example.tools.java2wsdl.ReuseTypes.common.Structure;

public interface ServiceC {
  Structure echo(Structure p0);
}

//Common Structure

// Copyright WSO2 Inc. All rights reserved.
// Use is subject to license terms.
package example.tools.java2wsdl.ReuseTypes.common;

public class Structure {
  public int i;
  public java.lang.String s;
}

By contrast, the following command does not reuse types. It generates four WSDL files. The fourth file contains only XML Schema definitions and this file is just imported by the others.

Java2WSDL example.tools.java2wsdl.ReuseTypes.a.ServiceA
                    example.tools.java2wsdl.ReuseTypes.b.ServiceB example.tools.java2wsdl.ReuseTypes.c.ServiceC