Skip Headers

Oracle® Application Server Web Services Developer's Guide 10g Release 3 (10.1.3) B14434-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 4 Oracle Application Server Web Services Messages

Oracle Application Server Web Services supports SOAP 1.1 and 1.2 messages. The format of the messages can be document or RPC style and literal or encoded use.

This chapter contains these sections:

- OracleAS Web Services Message Formats

- Working with SOAP Messages

## OracleAS Web Services Message Formats

This section describes the message formats supported by the current release of OracleAS Web Services. It includes these topics:

- Understanding Message Formats

- Supported Message Formats

- Selecting Message Formats

- Changing Message Formats in a Service Implementation

- Message Format Recommendations

To understand the message formats supported by OracleAS Web Services, it is useful to understand the relationship between the Web Service Description Language (WSDL) 1.1 and the wire format. The wire format is the physical representation of a Simple Object Access Protocol (SOAP) message, or payload, for transmission. The message format is determined by the use and style attributes from the binding defined in the WSDL. The type of XML schema that defines the message part enhances the message format. The WSDL, then, can be thought of as a contract. By defining the various attributes in the WSDL, you affect the format of the message on the wire.

Any interoperability issues that arise are usually noticed at runtime in the wire format. Often, you can fix these by adjusting the WSDL and regenerating the Web service artifacts.

The relationship between the message format and the wire format is not one-to-one. For example, you can define a document-literal style Web service, Service A, with an XML schema that makes runtime SOAP messages look identical to messages produced by an RPC-literal style Web service, Service B. If you change the style and use (that is, the message format) of Service A to be "RPC" and "literal", then Service A will not be the same as Service B. The runtime SOAP messages would look completely different after the change, unless you also change the schema used in Service A.

### Understanding Message Formats

The following sections briefly describe the message formats supported by OracleAS Web Services. For detailed descriptions of the message format options (that is, the full implications of the `use` and `style` WSDL binding attributes) see the SOAP and WSDL specifications listed in "SOAP-Related Documents" and "WSDL-Related Documents".

#### RPC and Document Styles

A SOAP payload can be either RPC or document style. An RPC-style payload is usually used if there is a need to invoke a remote procedure or method call. With RPC style, the name of the top-most XML element in the SOAP body of the request is always the name of the WSDL operation. There is no ambiguity, because the names are unique in a given binding. The SOAP XML message typically consists of a method name and parameters, all represented in XML.

If the WSDL operation is overloaded, there must be a unique `SOAPAction` specified in the corresponding operation binding. Section 7 of the SOAP 1.1 specification describes the structure of an RPC-style SOAP body element (`<body>`).

The SOAP body of a document-style payload contains XML that does not have to conform to Section 7 of the SOAP 1.1 specification, but it uses an XML schema global element to define the payload of the message. That schema is defined within or imported into the WSDL's `type` section.

#### Literal and Encoded Uses

The SOAP client and server interprets the XML contents of the SOAP payload `<body>` element according to the rules specified by the `use` attribute of the WSDL's `binding` section. The client and server must agree on the same encoding rule to ensure that they can each correctly interpret the data.

For a literal use, the rules for encoding and interpreting the SOAP body of input and output messages are described entirely in terms of the schema.

For the encoded use, the `encodingStyle` attribute in the SOAP body identifies the rules used for encoding and interpreting the message according to the SOAP specification:

- For SOAP 1.1, see "SOAP Encoding", Section 5 of the SOAP 1.1 specification: `http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383512`

- For SOAP 1.2, see "SOAP Encoding", Section 3 of the SOAP 1.2 specification: `http://www.w3.org/TR/2003/REC-soap12-part2-20030624/#soapenc`

You can also use types defined in the SOAP encoding schema extension.

### Supported Message Formats

The following sections describe the message formats supported by OracleAS Web Services.

- Document-Literal Message Format

- RPC-Encoded Message Format

- RPC-Literal Message Format

#### Document-Literal Message Format

Document-literal is the default message format for OracleAS Web Services. The two common styles of document-literal operations are wrapped and bare.

- For a wrapped style, a schema definition of a wrapper element wraps the parameters belonging to a method. The messages are not SOAP encoded and do not use SOAP RPC conventions.

- For a bare style, the method must have only one parameter mapped to a SOAP body. If the method has multiple parameters, then only one can be mapped to the body part. The other parameters must be mapped to SOAP headers.

Document-literal complies with WS-I Basic Profile 1.0 and 1.1.

Each document-literal operation is uniquely identified from the `QName` of the top element of the input message. Document-literal with the wrapped style has the best interoperability with .NET Web services and is the preferred message format for OracleAS Web Services.

For information on interoperability and message formats see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

Advantages:

- Complies with WS-I.

- Provides support for interoperability.

- Natural format for SOAP fault handling.

- Format of the message part is described by the standard XML schema.

Disadvantages:

- Not fully backward compatible with older stacks.

- Does not support object graphs.

##### Sample Request Message with the Document-Literal Message Format

Example 4-1 illustrates a request message in the document-literal message format. Note that the XML element part (`payloadDocument`) under the SOAP body (`env:Body`) must be a document instance of a global element defined in the WSDL's schema.

The example applies to SOAP 1.1 messages. To change the example to apply to SOAP 1.2 messages, change the value of `xmlns:env` to `http://www.w3.org/2003/05/soap-envelope`.

Example 4-1 Request Message with the Document-Literal Message Format

    <env:Envelope
            xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:ns0="http://ws.oracle.com/doc-lit">
            <env:Body>
                    <ns0:payloadDocument>
                            <ns0:name>Scott</ns0:name>
                            <ns0:data>Hello</ns0:data>
                    </ns0:payloadDocument>
            </env:Body>
    </env:Envelope>

#### RPC-Encoded Message Format

The RPC-encoded message format uses the encoding rules defined in the SOAP specification:

- For SOAP 1.1, see "SOAP Encoding", Section 5 of the SOAP 1.1 specification.

  `http://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383512`

  The `encodingStyle` attribute for the SOAP 1.1 RPC-encoded message format is expressed with the following value.

  `encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"`

- For SOAP 1.2, see "SOAP Encoding", Section 3 of the SOAP 1.2 specification.

  `http://www.w3.org/TR/2003/REC-soap12-part2-20030624/#soapenc`

  The `encodingStyle` attribute for the SOAP 1.2 RPC-encoded message format is expressed with the following value.

  `encodingStyle="http://www.w3.org/2003/05/soap-encoding"`

For information about the issues of interoperability and message formats, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

Advantages:

- Backward compatible with older stacks, because this was one of the most common message formats for Web services.

- Supports object graphs (through `id` and `href` attributes).

- Provides additional Java type mapping support indicated by the namespace `http://www.oracle.com/webservices/internal`. For a list of supported data types, see Table 4-1.

Disadvantages:

- Does not comply with the WS-I Basic Profile.

- More difficult to perform schema validation of the entire message payload

##### Sample Messages with the RPC-Encoded Message Format

Example 4-2 illustrates a request message that uses the RPC-encoded message format. Note that the tag name of the XML element part (`echoString`) sent under the SOAP body (`env:Body`) must be the same as the name of the corresponding WSDL operation. The `env:encodingStyle` attribute indicates the SOAP encoding style being used. Each XML element part (`stringParam`) under the operation element corresponds to a parameter. It must be an instance of `simpleType` or a global type definition. If it is a global type definition, it must be in the WSDL's schema or one of the SOAP encoding extension types.

RPC-encoded request messages to OracleAS Web Services (or RPC-encoded response messages to OracleAS Web Services-generated stubs) can be consumed without `xsi:type` attributes.

Example 4-2 and Example 4-3 apply to SOAP 1.1 messages. To change the examples to apply to SOAP 1.2 messages:

- Change the value of `xmlns:env` to `http://www.w3.org/2003/05/soap-envelope`

- Change the value of `env:encodingStyle` to `http://www.w3.org/2003/05/soap-encoding`

Example 4-2 RPC-Encoded Request Message

    <env:Envelope
            xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:ns0="http://ws.oracle.com/rpc-enc">
            <env:Body>
                    <ns0:echoString
                            env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                            <stringParam>Hello</stringParam>
                    </ns0:echoString>
            </env:Body>
    </env:Envelope>

Example 4-3 illustrates a response message that uses the RPC-encoded message format. RPC-encoded response messages from OracleAS Web Services (or the RPC-encoded request messages from an OracleAS Web Services-generated stub) always contain `xsi:type` attributes.

Example 4-3 RPC-Encoded Response Message

    <env:Envelope
            xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:ns0="http://ws.oracle.com/rpc-enc">
            <env:Body>
                    <ns0:echoStringResponse
                            env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
                            <stringParam xsi:type="xsd:string">Hello</stringParam>
                    </ns0:echoStringResponse>
            </env:Body>
    </env:Envelope>

##### The xsi:type Attribute in RPC-Encoded Message Formats

In many SOAP implementations, messages that use the RPC-encoded message format usually use the `xsi:type` attribute on each element in the message payload. This attribute helps object serialization and deserialization. The `xsi:type` attribute is optional in most cases. The `xsi:type` attribute is required only if the element is an instance of a derived type of an element type defined in the schema. For inbound SOAP messages, OracleAS Web Services accepts messages with or without the `xsi:type` attribute. For outbound SOAP messages in RPC-Encoded format, OracleAS Web Services always emits the `xsi:type` attribute.

Example 4-4 and Example 4-5 apply to SOAP 1.1 messages. To change the examples to apply to SOAP 1.2 messages:

- Change the value of `xmlns:env` to `http://www.w3.org/2003/05/soap-envelope`

- Change the value of `env:encodingStyle` to `http://www.w3.org/2003/05/soap-encoding`

Example 4-4 illustrates a request message for the `echo` operation in RPC-encoded message format. Note that the code sample does not contain the `xsi:type="xsd:string"` attribute.

Example 4-4 RPC-Encoded Request Message Without the xsi:type Attribute

    <env:Envelope
            xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:ns0="http://ws.oracle.com/rpc-enc">
       <env:Body>
          <ns0:echo env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
             <param>some string</param>
          </ns0:echo>
       </env:Body>
    </env:Envelope>

Example 4-5 illustrates the same request message in RPC-encoded format with the `xsi:type` attribute.

Example 4-5 RPC-Encoded Request Message With the xsi:type Attribute

    <env:Envelope
            xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:ns0="http://ws.oracle.com/rpc-enc">
       <env:Body>
          <ns0:echo env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
             <param xsi:type="xsd:string">some string</param>
          </ns0:echo>
       </env:Body>
    </env:Envelope>

##### Oracle-Specific Type Support

For a complete list of the supported types, see Chapters 4 and 5 of the JAX-RPC 1.1 specification. The JAX-RPC 1.1 specification is available from:

`http://java.sun.com/webservices/jaxrpc/index.jsp`

For completeness, Table 4-1 describes the all of the Java types and Oracle-proprietary types supported by OracleAS Web Services RPC-encoded message format. The Java type mapping support for the types is indicated by the following OracleAS Web Services-specific namespace:

`http://www.oracle.com/webservices/internal`

This namespace accommodates nonstandard XML schema definitions for some standard Java types, such as `Collection`, that are not supported by JAX-RPC 1.1.

Note: The `java.util.Collection` family and `java.util.Map` family are also supported for the literal use (that is, document-literal and RPC-literal). The schema types for these Java types are defined under a different namespace. See "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide for more information on how these Java types are supported.

Table 4-1 Java Types Supported by RPC-Encoded Proprietary Message Format

Java Type | Java Classes | Mapping Details
--- | --- | ---
Java primitive types | boolean, byte, double, float, int, long, short | See "Mapping Java Primitive Types to XML Types" in the Oracle Application Server Advanced Web Services Developer's Guide
java.lang Object types | Boolean, Byte, Double, Float, Integer, Long, Short, String | See "Mapping Java Types to XML Types" in the Oracle Application Server Advanced Web Services Developer's Guide
basic Java types | java.math.BigDecimal java.math.BigInteger java.xml.QName java.util.Calendar java.util.Date java.net.URI | See "Mapping Java Types to XML Types" in the Oracle Application Server Advanced Web Services Developer's Guide
Java array types | One-dimensional arrays with elements of supported type | See "Mapping Java Types to XML Types" and "Mapping Java Collection Classes to XML Types" in the Oracle Application Server Advanced Web Services Developer's Guide
Java value types | Java Beans with properties of supported types | See "OracleAS Web Services Support for Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide
attachments Note: attachments are not interoperable | java.awt.Image javax.mail.internet.MimeMultipart javax.xml.transform.Source javax.activation.DataHandler | See "Working with Message Attachments" in the Oracle Application Server Advanced Web Services Developer's Guide
java.util.Collection | java.util.Collection java.util.List java.util.Set java.util.Vector java.util.Stack java.util.LinkedList java.util.ArrayList java.util.HashSet java.util.TreeSet | See "Mapping Java Collection Classes to XML Types" and "Additional Information about Oracle Proprietary XML Types" in the Oracle Application Server Advanced Web Services Developer's Guide
java.util.Map | java.util.Map java.util.HashMap java.util.TreeMap java.util.Hashtable java.util.Properties | See "Mapping Java Collection Classes to XML Types" and "Additional Information about Oracle Proprietary XML Types" in the Oracle Application Server Advanced Web Services Developer's Guide

If you want to use any value types which are not built-in (for example, `MyBean`) as items in a `Map` or `Collection`, then you must use the value of the `valueTypeClassName` argument to declare these types to the WebServicesAssembler tool when generating the WSDL.

    java -jar wsa.jar -genWsdl
                      -valueTypeClassName hello.MyBean
                      -valueTypeClassName hello.MyFoo...

This allows the generated WSDL to include the schema definitions for these value types. The runtime can then correctly generate the corresponding serialized values. All WebServicesAssembler commands and Ant tasks that assemble Web services bottom up (from Java classes, EJBs, database resources, and so on) support the `valueTypeclassName` argument. For more information on this argument, see "valueTypeClassName"

For more information on using value type classes that do not conform to the JAX-RPC value type requirements, or that cannot be handled by the default JAX-RPC serialization mechanism, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.

##### Restrictions on RPC-Encoded Format

OracleAS Web Services does not support the combination of RPC-encoded message formats and `databinding=false`.

#### RPC-Literal Message Format

RPC-literal message format complies with WS-I Basic Profile 1.0 and 1.1. This format uses the RPC style of message payload structure but supports the literal way of describing the types passed by a procedure. In this case, literal means that there exists a schema for every parameter type but not for the payload of the message body itself.

For information on interoperability and message formats, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

Advantages:

- Complies with WS-I.

- Format of the message part is described by the standard XML schema.

Disadvantages:

- Support for RPC-literal is not consistent across all vendors.

- Does not support object graphs.

- Is not backward compatible with older stacks.

- It is not possible to represent null values for Java method parameters when mapping to WSDL message parts.

##### Sample Request Message with the RPC-Literal Message Format

Example 4-6 illustrates a request message coded for the RPC-literal message format. Note that the tag name of the XML element part (`echoString`) under the SOAP body (`env:Body`) must be identical to the name of the corresponding WSDL operation. Each XML element part (`stringParam`) under the operation element corresponds to a parameter and must be an instance of `simpleType` or a global type definition. If it is a global type definition, then it must be in the WSDL's schema.

The example applies to SOAP 1.1 messages. For SOAP 1.2 messages, change the value of `xmlns:env` to `http://www.w3.org/2003/05/soap-envelope`.

Example 4-6 RPC-Literal Request Message

    <env:Envelope
            xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:ns0="http://ws.oracle.com/rpc-lit">
            <env:Body>
                    <ns0:echoString>
                            <stringParam>Hello</stringParam>
                    </ns0:echoString>
            </env:Body>
    </env:Envelope>

### Selecting Message Formats

The WebServicesAssembler tool provides arguments that let you control the message format used by a Web service. These arguments let you specify whether the message format is RPC or document (wrapped or bare), encoded or literal.

- style

- use

The following WebServicesAssembler commands allow you to use the `use` and `style` arguments to specify the message format for your Web service.

- aqAssemble

- assemble

- corbaAssemble

- dbJavaAssemble

- ejbAssemble

- genInterface

- genWsdl

- plsqlAssemble

- sqlAssemble

The following example uses the `assemble` command to assemble the Web service server components. The `style` and `use` arguments specify that the message format used is RPC-literal:

    java -jar wsa.jar -assemble
                      -appName $(app.name)
                      -serviceName HelloServiceWSIF
                      -uri $(app.name)
                      -interface oracle.demo.hello.HelloInterface
                      -className oracle.demo.helllo.HelloImpl
                      -input $(service.classes.dir)
                      -output build
                      -ear dist/$(app.name).ear
                      -style rpc
                      -use literal

For more information on the WebServicesAssembler tool and its functionality, see Chapter 17, "Using WebServicesAssembler".

### Changing Message Formats in a Service Implementation

You can expose Java service endpoint implementations in RPC-encoded, RPC-literal, or document-literal format. However, if the service endpoint implementation uses the `attachment` data types listed in the Table 4-1, then you can use only RPC-encoded. If none of these additional types are used, then you can use RPC-literal or document-literal format to achieve better interoperability. Each of the formats display similar performance in marshaling between Java objects and XML.

### Message Format Recommendations

This section provides some general guidelines for choosing a message format when designing your Web service. When choosing a message format, consider the functionality requirements of the client you want to support. Table 4-2 describes some possible client functionality requirements and suggested message formats.

Table 4-2 Message Format Suggestions, Based on Client Functionality

Client Functionality | Suggested Message Format
--- | ---
OmniPortlet | Use either RPC-encoded or document-literal. The Omniportlet APIs (wizard) does not support RPC-literal.
Oracle XML Query Service (XQS) integration | Use either RPC or document style with the literal use. Oracle XML Query Service does not support SOAP encoding.
XML Schema integration | Reuse the schema definition to describe the SOAP message part of the WSDL operation. This integration can be achieved with either RPC or document style with the literal use.
call-out from an Oracle release 9.2 database | Use RPC-encoded. Oracle release 10.1 or later supports all formats.
expose graph and preserve object identity | Use RPC-encoded. Although RPC-encoded is the easiest way, it can be achieved in document-literal if the model (schema) is well-designed.
WS-I compliance | Use either RPC or document style with the literal use.
BPEL processes | Use document style with the literal use.
Axis 1.2 client | Use either RPC-encoded or document-literal message formats

## Working with SOAP Messages

OracleAS Web Services supports SOAP 1.1 and 1.2 messages both programmatically and by using the WebServicesAssembler tool to assemble Web services bottom up and top down.

- OraSAAJ APIs

- Using SOAP 1.2 Formatted Messages in Bottom Up Web Service Assembly

- Using SOAP 1.2 Formatted Messages in Top Down Web Service Assembly

The SOAP with Attachments API for Java (SAAJ) version 1.2 is the programmatic model for representing and working with a SOAP message. The standard SAAJ APIs support SOAP 1.1. You can find more information on SAAJ at the following Web address:

`http://java.sun.com/webservices/saaj/index.jsp`

The Oracle extension of the SAAJ 1.2 API (OraSAAJ) allows a Web service to work with SOAP 1.2 messages.

### OraSAAJ APIs

OracleAS Web Services support SAAJ 1.2, which is a specification for modeling SOAP messages with attachments in Java objects. However, the standard SAAJ 1.2 APIs support only SOAP 1.1 messages. To provide programmatic support for SOAP 1.2 messages, OracleAS Web Services includes the `oracle.webservices.soap` package. The interfaces in this package allow you to work with and add information to SOAP 1.2 message objects.

The classes in this package, `VersionedMessageFactory` and `VersionedSOAPFactory`, are extensions to standard SAAJ classes `MessageFactory` and `SOAPFactory`. The methods in the `VersionedMessageFactory` and `VersionedSOAPFactory` classes contain an extra parameter that lets you specify a SOAP message version when using the standard SAAJ APIs.

Table 4-3 Interfaces and Classes in the ORASAAJ API

Interface/Class Name | Description
--- | ---
Body12 interface | Represents a SOAP 1.2 message `Body` object.
Fault12 interface | Provides methods to add SOAP 1.2 `FaultCode` and `FaultReason` elements to a SOAP 1.2 `Fault` element.
FaultCode12 interface | Provides methods to add SOAP 1.2 `FaultValue` and `FaultSubcode` elements to a SOAP 1.2 `FaultCode` element.
FaultReason12 interface | Provides methods to add a SOAP 1.2 `FaultText` element to a SOAP 1.2 `FaultReason` element.
FaultSubcode12 interface | This interface is an extension to the `FaultCode12` interface. It is a marker interface for compiler-enforced strong typing.
FaultText12 interface | Provides methods for adding the text node content and locale information to a `FaultText` element.
FaultValue12 interface | Provides methods to set the fault code on a `FaultValue12` element.
SOAPVersion interface | Provides constants representing the SOAP versions that are available to the platform.
VersionedMessageFactory class | Provides methods for creating a SOAP message. These methods mimic the standard SAAJ `MessageFactory` class, except that they contain an extra parameter for specifying a SOAP message version. One method creates an empty message with standard MIME headers. The other method creates a message based on an input stream and a specified MIME header.
VersionedSOAPFactory class | Provides methods for creating SOAP elements. These methods mimic the standard SAAJ `SOAPFactory` class, except that they contain an extra parameter for specifying a SOAP message version.

For more information on these classes and their methods, see the output of the Javadoc tool for the `oracle.webservices.soap` package at the following Web address:

`http://www.oracle.com/technology/index.html`

#### Using the OraSAAJ APIs

The OraSAAJ extensions can be used from a `javax.xml.rpc.handler.Handler`. In most cases, the standard `javax.xml.soap.*` classes can be used to manipulate SOAP 1.2 SAAJ messages. However, if you want to use the functionality provided by SOAP 1.2, you must use the OraSAAJ APIs.

Example 4-7 illustrates how the standard `javax.xml.soap.*` classes and the OraSAAJ classes can be used together. The example code creates a SOAP 1.2 message from scratch. The `VersionedMessageFactory` method returns a `javax.xml.soap.SoapMessage` object. This enables you to use the standard `javax.xml.soap.*` methods such as `getBody` and `getEnvelope` on the message.

The `addFault` method adds a SOAP 1.2 fault to the message. To send SOAP 1.2 faults, you must use the OraSAAJ `Fault12`, `FaultCode12`, `FaultValue12`, and `FaultReason12` APIs. This is because SOAP 1.2 faults contain more information than SOAP 1.1 faults.

Example 4-7 Working with the SAAJ and OraSAAJ APIs

    public boolean handleResponse(MessageContext context) {
        ...
        // create a SOAP 1.2 message from scratch.
        // Note the use of VersionedMessageFactory to get a SOAPMessage
        // for a specific version of soap
        SOAPMessage message = ((VersionedMessageFactory)MessageFactory.newInstance()).createVersionedMessage(oracle.webservices.soap.SOAPVersion.SOAP_1_2);
        // Now standard APIs can be used.
        SOAPBody body = message.getSOAPPart().getEnvelope().getBody();
        // However, if you need to send a fault, you must
        // use Oracle-specific APIs, because SOAP 1.2
        // faults contain more information than SOAP 1.1 faults.
        // Note the use of Fault12, FaultCode12, and FaultReason12
        SOAPFault fault = body.addFault();
          Fault12 soapFault = (Fault12) fault;
          FaultCode12 faultCode = soapFault.addCode();
          FaultValue12 faultValue = faultCode.addFaultValue();
          QNameAdapter faultCodeQName = new QNameAdapter("http://my.foo.com/",
                                                           "myFaultCode",
                                                           "foo");
          faultValue.setFaultCode(faultCodeQName);
          FaultReason12 faultReason = soapFault.addReason();
          faultReason.addFaultText().setValue("An unknown error occurred");
        ...
    }

### Using SOAP 1.2 Formatted Messages in Bottom Up Web Service Assembly

To support SOAP version 1.2 messages in bottom up Web service generation, WebServicesAssembler provides a `soapVersion` argument. Values can be "`1.1`", "`1.2`", or "`1.1,1.2`". Default value is "`1.1`".

The "`1.1,1.2`" value means that WebServicesAssembler will create two ports with two bindings. One port and binding will support version 1.1; the other port and binding will support version 1.2. Each port must be bound to a different URL. That is, you cannot support both versions concurrently with the same URL address.

See "soapVersion" for more information on the WebServicesAssembler `soapVersion` argument.

### Using SOAP 1.2 Formatted Messages in Top Down Web Service Assembly

To support SOAP 1.2 messages in top down Web services development, you must supply a WSDL with a SOAP 1.2 binding. A WSDL with a SOAP 1.2 binding contains a set of URIs specific to SOAP 1.2. These URIs are listed in Table 4-4.

Table 4-4 URIs for SOAP 1.2 Messages

URI | Description
--- | ---
`http://schemas.xmlsoap.org/wsdl/soap12` | The namespace of the SOAP 1.2 binding element that goes into the WSDL `binding` element.
`http://www.w3.org/2003/05/soap-encoding` | For a SOAP 1.2 message, indicates the encoding rules that the contents of the containing element follows. For more information, see the SOAP Version 1.2 Part 2 Recommendation at: `http://www.w3.org/TR/2003/REC-soap12-part2-20030624/`
`http://www.w3.org/2003/05/soap/bindings/HTTP` and `http://schemas.xmlsoap.org/soap/http` | Describes HTTP transport for SOAP 1.2. Both URIs are accepted by the OracleAS Web Services stack, but the `schemas.xmlsoap.org` URI is more interoperable than the `www.w3.org` URI. Therefore, the `schemas.xmlsoap.org` URI is used when the WSDL is generated for bottom up Web Service assembly.

Example 4-8 displays a WSDL that supports SOAP 1.2 messages. The URIs and elements that are needed to support SOAP 1.2 are displayed in bold font.

Example 4-8 Sample WSDL with SOAP 1.2 Binding

    <?xml version="1.0" encoding="UTF-8"?>
    <definitions
         name="Rpclitbottomup"
         targetNamespace="http://www.oracle.ws/rpcliteral"
         xmlns="http://schemas.xmlsoap.org/wsdl/"
         xmlns:tns="http://www.oracle.ws/rpcliteral"
         xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
         xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
         xmlns:tns0="http://www.oracle.ws/rpcliteral/schema"
         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
         xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
        >
        <types>
            <schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="http://www.oracle.ws/rpcliteral/schema"
                 elementFormDefault="qualified" xmlns:tns="http://www.oracle.ws/rpcliteral/schema"
                 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <complexType name="HelloMessage">
                    <sequence>
                        <element name="longValue" type="long"/>
                        <element name="age" type="int"/>
                        <element name="greeting" type="string" nillable="true"/>
                        <element name="name" type="string" nillable="true"/>
                        <element name="id" type="decimal" nillable="true"/>
                    </sequence>
                </complexType>
            </schema>
        </types>
        <message name="HelloInterface_hello">
            <part name="msg" type="tns0:HelloMessage"/>
        </message>
        <message name="HelloInterface_helloResponse">
            <part name="result" type="tns0:HelloMessage"/>
        </message>
        <portType name="HelloInterface">
            <operation name="hello" parameterOrder="msg">
                <input message="tns:HelloInterface_hello"/>
                <output message="tns:HelloInterface_helloResponse"/>
            </operation>
        </portType>
        <binding name="HelloInterfacePortBinding" type="tns:HelloInterface">
            <soap12:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
            <operation name="hello">
                <soap12:operation soapAction="http://www.oracle.ws/rpcliteral/hello" soapActionRequired="false"/>
                <input>
                    <soap12:body use="literal" namespace="http://www.oracle.ws/rpcliteral" parts="msg"/>
                </input>
                <output>
                    <soap12:body use="literal" namespace="http://www.oracle.ws/rpcliteral" parts="result"/>
                </output>
            </operation>
        </binding>
        <service name="Rpclitbottomup">
            <port name="HelloInterfacePort" binding="tns:HelloInterfacePortBinding">
                <soap:address location="REPLACE_WITH_ACTUAL_URL"/>
            </port>
        </service>
    </definitions>

## Converting XML Elements to SOAP Elements

The `oracle.webservices` package provides a `toSOAPElement` method in the `SOAPUtil` class to convert XML elements (`org.w3c.dom.Element`) to SOAP elements (`javax.xml.soap.SOAPElement`).

Example 4-9 illustrates a code sample that creates an XML document, converts it to a SOAP element, and prints it to the standard output.

Example 4-9 Converting an XML Element to a SOAP Element

    ...
    try {
       DOMParser parser = new DOMParser();
       parser.parse(new StringReader(
          "<Flds:CustomerGroup xmlns:Flds=\"http://foo.com/foo.xsd\">
          "<Flds:Customer>xyz</Flds:Customer>
          "</Flds:CustomerGroup>"));

       SOAPElement se = SOAPUtil.toSOAPElement(
          parser.getDocument().getDocumentElement());
       ((XMLElement)se).print(System.out);
    } catch (Exception ex) {
       ex.printStackTrace();
    }
    ...

## Limitations

See "OracleAS Web Services Messages".

## Additional Information

For more information on:

- using the WebServicesAssembler tool to assemble Web services, see Chapter 17, "Using WebServicesAssembler".

- Web services interoperability, see "Ensuring Interoperable Web Services" in the Oracle Application Server Advanced Web Services Developer's Guide.

- message attachments, and using attachments in your Web service, see "Working with Message Attachments" in the Oracle Application Server Advanced Web Services Developer's Guide

- processing nonstandard data types, see "Custom Serialization of Java Value Types" in the Oracle Application Server Advanced Web Services Developer's Guide.

- the JAX-RPC mapping file, see "JAX-RPC Mapping File Descriptor" in the Oracle Application Server Advanced Web Services Developer's Guide.

- data types supported by OracleAS Web Services, see "Mapping Java Types to XML and WSDL Types" in the Oracle Application Server Advanced Web Services Developer's Guide.