# SOAP 1.2

## Introduction

The default binding supported by JAX-WS 2.0 is SOAP 1.1 over HTTP. With this release we have added SOAP 1.2 binding over HTTP support into JAX-WS 2.0. This document describes how SOAP 1.2 binding can be applied to an endpoint and how it can be used on the client side in the case of proxy port. To enable SOAP 1.2 support in the `Dispatch` client please refer to the `Dispatch` documents.

## SOAP 1.2 Endpoint

To enable SOAP 1.2 binding on an endpoint. You would need to set binding attribute value in sun-jaxws.xml to SOAP 1.2 HTTP binding value as specified by `javax.xml.ws.soap.SOAPBinding.SOAP12HTTP_BINDING` which is: "http://www.w3.org/2003/05/soap/bindings/HTTP/" or "http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/"

Here is the `sun-jaxws.xml` from fromjava-soap1.2 sample:

    <?xml version="1.0" encoding="UTF-8"?>
    <endpoints xmlns="http://java.sun.com/xml/ns/jax-ws/ri/runtime"
            version="2.0">
        <endpoint name="fromjava-soap12"
                implementation="fromjava_soap12.server.AddNumbersImpl"
                binding="http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/
                url-pattern="/addnumbers"/>
    </endpoints>

JAX-WS 2.0 generates WSDL on the fly when requested by a client. If this binding attribute is present and is equal to SOAP 1.2 HTTP binding WSDL with SOAP 1.2 binding is generated. Based on this binding descriptor JAX-WS runtime configures itself to handle SOAP 1.2 messages.

Notice that the binding id "http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/" is not a standard binding id. If you use SOAP 1.2 binding id "http://www.w3.org/2003/05/soap/bindings/HTTP/" defined by JAX-WS, still the endpoint is configured to use SOAP 1.2 binding, except that a wsdl will not be generated on the fly.

Alternatively, you can specify the binding through `@BindingType` annotation in the implementation class to use SOAP 1.2 binding. Here is an example from the fromjava_soap12 sample.

    @WebService
    @BindingType(value = "http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/")
    public class AddNumbersImpl {

        /**
         * @param number1
         * @param number2
         * @return The sum
         * @throws AddNumbersException if any of the numbers to be added is
         *                             negative.
         */
        public int addNumbers(int number1, int number2) throws
                AddNumbersException {
            if (number1 < 0 || number2 < 0) {
                throw new AddNumbersException("Negative number cant be added " +
                        "!", "Numbers: " + number1 + ", " + number2);
            }
            return number1 + number2;
        }

    }

The commandline and the equivalent ant task can be used to generate SOAP 1.1 (default) or SOAP 1.2 WSDL. The binding information should be passed using `-wsdl:protocol` switch.

## Client

On the client there is nothing special that has to be done. JAX-WS runtime looks into the WSDL to determine the binding being used and configures itself accordingly. command line tool or `wsimport` ant task can be used to import the WSDL and to generated the client side artifacts.

## Samples

There are 2 samples bundled with this release

- fromwsdl-soap12 - shows SOAP 1.2 endpoint developed starting from wsdl

- fromjava-soap12 - shows SOAP 1.2 endpoint developed starting from Java

A SOAP 1.2 message generated by JAX-WS:

    Content-Type: application/soap+xml; charset=utf-8
    Content-Length: 178
    SOAPAction: ""

    <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
        <soapenv:Body>
            <addNumbers xmlns="http://duke.example.org">
                <arg0>-10</arg0>
                <arg1>20</arg1>
            </addNumbers>
        </soapenv:Body>
    </soapenv:Envelope>

A SOAP 1.2 Fault message generated by JAX-WS:

    Content-Type:application/soap+xml; charset=utf-8
    Content-Length: 476
    SOAPAction: ""

    <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
        <soapenv:Body>
            <soapenv:Fault>
                <soapenv:Code>
                    <soapenv:Value>
                        soapenv:Sender
                    </soapenv:Value>
                </soapenv:Code>
                <soapenv:Reason>
                    <soapenv:Text xml:lang="en">
                        Negative number cant be added!
                    </soapenv:Text>
                </soapenv:Reason>
                <soapenv:Detail>
                    <AddNumbersFault xmlns="http://duke.example.org">
                        <faultInfo>Numbers: -10, 20</faultInfo>
                        <message>Negative number cant be added!</message>
                    </AddNumbersFault>
                </soapenv:Detail>
            </soapenv:Fault>
        </soapenv:Body>
    </soapenv:Envelope>