LibraryPrintFeedback

Using the Web Services Bindings and Transports

Version 7.1

December 2012
Trademark Disclaimer
Third Party Acknowledgements

Updated: 08 Jan 2014

Table of Contents

I. Bindings
1. Understanding Bindings in WSDL
2. Using SOAP 1.1 Messages
Adding a SOAP 1.1 Binding
Adding SOAP Headers to a SOAP 1.1 Binding
3. Using SOAP 1.2 Messages
Adding a SOAP 1.2 Binding to a WSDL Document
Adding Headers to a SOAP 1.2 Message
4. Sending Binary Data Using SOAP with Attachments
5. Sending Binary Data with SOAP MTOM
Annotating Data Types to use MTOM
Enabling MTOM
Using JAX-WS APIs
Using configuration
6. Using XML Documents
II. Transports
7. Understanding How Endpoints are Defined in WSDL
8. Using HTTP
Adding a Basic HTTP Endpoint
Configuring a Consumer
Using Configuration
Using WSDL
Consumer Cache Control Directives
Configuring a Service Provider
Using Configuration
Using WSDL
Service Provider Cache Control Directives
Configuring the Jetty Runtime
Using the HTTP Transport in Decoupled Mode
9. Using SOAP Over JMS
Basic configuration
JMS URIs
WSDL extensions
10. Using Generic JMS
Using the JMS configuration bean
Using WSDL to configure JMS
Basic JMS configuration
JMS client configuration
JMS provider configuration
Using a Named Reply Destination
III. Appendices
A. Integrating with Fuse Message Broker
B. Conduits
C. Conduit and Destination Based JMS Configuration
Basic endpoint configuration
Consumer configuration
Provider configuration
JMS Session Pool Configuration
Index

List of Figures

8.1. Message Flow in for a Decoupled HTTP Transport

List of Tables

3.1. soap12:header Attributes
4.1. mime:content Attributes
8.1. Elements Used to Configure an HTTP Consumer Endpoint
8.2. HTTP Consumer Configuration Attributes
8.3. http-conf:client Cache Control Directives
8.4. Elements Used to Configure an HTTP Service Provider Endpoint
8.5. HTTP Service Provider Configuration Attributes
8.6. http-conf:server Cache Control Directives
8.7. Elements for Configuring a Jetty Runtime Factory
8.8. Elements for Configuring a Jetty Runtime Instance
8.9. Attributes for Configuring a Jetty Thread Pool
9.1. JMS URI variants
9.2. JMS properties settable as URI options
9.3. JNDI properties settable as URI options
9.4. SOAP/JMS WSDL extension elements
10.1. General JMS Configuration Properties
10.2. JMS endpoint attributes
10.3. JMS Client WSDL Extensions
10.4. JMS provider endpoint WSDL extensions
C.1. messageType values
C.2. Provider Endpoint Configuration
C.3. Attributes for Configuring the JMS Session Pool

List of Examples

2.1. Ordering System Interface
2.2. SOAP 1.1 Binding for orderWidgets
2.3. SOAP Header Syntax
2.4. SOAP 1.1 Binding with a SOAP Header
2.5. SOAP 1.1 Binding for orderWidgets with a SOAP Header
3.1. Ordering System Interface
3.2. SOAP 1.2 Binding for orderWidgets
3.3. SOAP Header Syntax
3.4. SOAP 1.2 Binding with a SOAP Header
3.5. SOAP 1.2 Binding for orderWidgets with a SOAP Header
4.1. MIME Namespace Specification in a Contract
4.2. Contract using SOAP with Attachments
5.1. Message for MTOM
5.2. Binary Data for MTOM
5.3. JAXB Class for MTOM
5.4. Getting the SOAP Binding from an Endpoint
5.5. Setting a Service Provider's MTOM Enabled Property
5.6. Getting a SOAP Binding from a BindingProvider
5.7. Setting a Consumer's MTOM Enabled Property
5.8. Configuration for Enabling MTOM
6.1. Valid XML Binding Message
6.2. Invalid XML Binding Message
6.3. Invalid XML Document
6.4. XML Binding with rootNode set
6.5. XML Document generated using the rootNode attribute
6.6. Using xformat:body
8.1. SOAP 1.1 Port Element
8.2. SOAP 1.2 Port Element
8.3. HTTP Port Element
8.4. HTTP Consumer Configuration Namespace
8.5. http-conf:conduit Element
8.6. HTTP Consumer Endpoint Configuration
8.7. HTTP Consumer WSDL Element's Namespace
8.8. WSDL to Configure an HTTP Consumer Endpoint
8.9. HTTP Provider Configuration Namespace
8.10. http-conf:destination Element
8.11. HTTP Service Provider Endpoint Configuration
8.12. HTTP Provider WSDL Element's Namespace
8.13. WSDL to Configure an HTTP Service Provider Endpoint
8.14. Jetty Runtime Configuration Namespace
8.15. Configuring a Jetty Instance
8.16. Activating WS-Addressing using WSDL
8.17. Activating WS-Addressing using a Policy
8.18. Configuring a Consumer to Use a Decoupled HTTP Endpoint
9.1. SOAP over JMS binding specification
9.2. JMS URI syntax
9.3. SOAP/JMS endpoint address
9.4. Syntax for JMS URI options
9.5. Setting a JNDI property in a JMS URI
9.6. JMS URI that configures a JNDI connection
9.7. WSDL contract with SOAP/JMS configuration
10.1. Declaring the Spring p-namespace
10.2. JMS configuration bean
10.3. Adding JMS configuration to a JAX-WS client
10.4. Adding JMS configuration to a JMS conduit
10.5. JMS WSDL extension namespace
10.6. JMS WSDL port specification
10.7. WSDL for a JMS consumer endpoint
10.8. WSDL for a JMS provider endpoint
10.9. JMS Consumer Specification Using a Named Reply Queue
A.1. SOAP/JMS WSDL to connect to Fuse Message Broker
A.2. SOAP/JMS WSDL for specifying the Fuse Message Broker connection factory
A.3. WSDL port specification with a dynamically created queue
C.1. JMS Configuration Namespaces
C.2. Addressing Information in a Fuse Services Framework Configuration File
C.3. Configuration for a JMS Consumer Endpoint
C.4. Configuration for a Provider Endpoint
C.5. JMS Session Pool Configuration

Bindings are defined in a contract using the WSDL binding element. The binding element has a single attribute, name, that specifies a unique name for the binding. The value of this attribute is used to associate the binding with an endpoint as discussed in Defining Your Logical Interfaces in Writing WSDL Contracts.

The actual mappings are defined in the children of the binding element. These elements vary depending on the type of payload format you decide to use. The different payload formats and the elements used to specify their mappings are discussed in the following chapters.

[Note]Note

To use wsdl2soap you will need to download the Fuse Services Framework distribution.

To generate a SOAP 1.1 binding using wsdl2soap use the following command:

wsdl2soap {-i port-type-name} [-b binding-name] [-d output-directory] [-o output-file] [-n soap-body-namespace] [-style (document/rpc)] [-use (literal/encoded)] [-v] [[-verbose] | [-quiet]] wsdlurl

The command has the following options:

OptionInterpretation
-i port-type-name

Specifies the portType element for which a binding is generated.

wsdlurlThe path and name of the WSDL file containing the portType element definition.

The tool has the following optional arguments:

OptionInterpretation
-b binding-nameSpecifies the name of the generated SOAP binding.
-d output-directorySpecifies the directory to place the generated WSDL file.
-o output-fileSpecifies the name of the generated WSDL file.
-n soap-body-namespaceSpecifies the SOAP body namespace when the style is RPC.
-style (document/rpc)Specifies the encoding style (document or RPC) to use in the SOAP binding. The default is document.
-use (literal/encoded)Specifies the binding use (encoded or literal) to use in the SOAP binding. The default is literal.
-vDisplays the version number for the tool.
-verboseDisplays comments during the code generation process.
-quietSuppresses comments during the code generation process.

The -i port-type-name and wsdlurl arguments are required. If the -style rpc argument is specified, the -n soap-body-namspace argument is also required. All other arguments are optional and may be listed in any order.

[Important]Important

wsdl2soap does not support the generation of document/encoded SOAP bindings.

If your system has an interface that takes orders and offers a single operation to process the orders it is defined in a WSDL fragment similar to the one shown in Example 2.1.


The SOAP binding generated for orderWidgets is shown in Example 2.2.


This binding specifies that messages are sent using the document/literal message style.

The syntax for defining a SOAP header is shown in Example 2.3. The message attribute of soap:header is the qualified name of the message from which the part being inserted into the header is taken. The part attribute is the name of the message part inserted into the SOAP header. Because SOAP headers are always document style, the WSDL message part inserted into the SOAP header must be defined using an element. Together the message and the part attributes fully describe the data to insert into the SOAP header.


As well as the mandatory message and part attributes, soap:header also supports the namespace, the use, and the encodingStyle attributes. These optional attributes function the same for soap:header as they do for soap:body.

Example 2.4 shows a modified version of the orderWidgets service shown in Example 2.1. This version has been modified so that each order has an xsd:base64binary value placed in the SOAP header of the request and response. The SOAP header is defined as being the keyVal part from the widgetKey message. In this case you are responsible for adding the SOAP header to your application logic because it is not part of the input or output message.

Example 2.4. SOAP 1.1 Binding with a SOAP Header

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>
<message name="widgetKey">
  <part name="keyVal" element="xsd1:keyElem"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap:operation soapAction="" style="document"/>
      <input name="order">
        <soap:body use="literal"/>
        <soap:header message="tns:widgetKey" part="keyVal"/>
      </input>
      <output name="bill">
        <soap:body use="literal"/>
        <soap:header message="tns:widgetKey" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>

You can modify Example 2.4 so that the header value is a part of the input and output messages as shown in Example 2.5. In this case keyVal is a part of the input and output messages. In the soap:body element's parts attribute specifies that keyVal cannot be inserted into the body. However, it is inserted into the SOAP header.

Example 2.5. SOAP 1.1 Binding for orderWidgets with a SOAP Header

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
  <part name="keyVal" element="xsd1:keyElem"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
  <part name="keyVal" element="xsd1:keyElem"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap:operation soapAction="" style="document"/>
      <input name="order">
        <soap:body use="literal" parts="numOrdered"/>
        <soap:header message="tns:widgetOrder" part="keyVal"/>
      </input>
      <output name="bill">
        <soap:body use="literal" parts="bill"/>
        <soap:header message="tns:widgetOrderBill" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>

[Note]Note

To use wsdl2soap you will need to download the Fuse Services Framework distribution.

To generate a SOAP 1.2 binding using wsdl2soap use the following command:

wsdl2soap {-i port-type-name} [-b binding-name] {-soap12} [-d output-directory] [-o output-file] [-n soap-body-namespace] [-style (document/rpc)] [-use (literal/encoded)] [-v] [[-verbose] | [-quiet]] wsdlurl

The tool has the following required arguments:

OptionInterpretation
-i port-type-name

Specifies the portType element for which a binding is generated.

-soap12Specifies that the generated binding uses SOAP 1.2.
wsdlurlThe path and name of the WSDL file containing the portType element definition.

The tool has the following optional arguments:

OptionInterpretation
-b binding-nameSpecifies the name of the generated SOAP binding.
-soap12Specifies that the generated binding will use SOAP 1.2.
-d output-directorySpecifies the directory to place the generated WSDL file.
-o output-fileSpecifies the name of the generated WSDL file.
-n soap-body-namespaceSpecifies the SOAP body namespace when the style is RPC.
-style (document/rpc)Specifies the encoding style (document or RPC) to use in the SOAP binding. The default is document.
-use (literal/encoded)Specifies the binding use (encoded or literal) to use in the SOAP binding. The default is literal.
-vDisplays the version number for the tool.
-verboseDisplays comments during the code generation process.
-quietSuppresses comments during the code generation process.

The -i port-type-name and wsdlurl arguments are required. If the -style rpc argument is specified, the -n soap-body-namspace argument is also required. All other arguments are optional and can be listed in any order.

[Important]Important

wsdl2soap does not support the generation of document/encoded SOAP 1.2 bindings.

If your system has an interface that takes orders and offers a single operation to process the orders it is defined in a WSDL fragment similar to the one shown in Example 3.1.


The SOAP binding generated for orderWidgets is shown in Example 3.2.


This binding specifies that messages are sent using the document/literal message style.

Example 3.4 shows a modified version of the orderWidgets service shown in Example 3.1. This version is modified so that each order has an xsd:base64binary value placed in the header of the request and the response. The header is defined as being the keyVal part from the widgetKey message. In this case you are responsible for adding the application logic to create the header because it is not part of the input or output message.

Example 3.4. SOAP 1.2 Binding with a SOAP Header

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>
<message name="widgetKey">
  <part name="keyVal" element="xsd1:keyElem"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap12:operation soapAction="" style="document"/>
      <input name="order">
        <soap12:body use="literal"/>
        <soap12:header message="tns:widgetKey" part="keyVal"/>
      </input>
      <output name="bill">
        <soap12:body use="literal"/>
        <soap12:header message="tns:widgetKey" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap12:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>

You can modify Example 3.4 so that the header value is a part of the input and output messages, as shown in Example 3.5. In this case keyVal is a part of the input and output messages. In the soap12:body elements the parts attribute specifies that keyVal should not be inserted into the body. However, it is inserted into the header.

Example 3.5. SOAP 1.2 Binding for orderWidgets with a SOAP Header

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="widgetOrderForm.wsdl"
    targetNamespace="http://widgetVendor.com/widgetOrderForm"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:tns="http://widgetVendor.com/widgetOrderForm"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsd1="http://widgetVendor.com/types/widgetTypes"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/">

<types>
  <schema targetNamespace="http://widgetVendor.com/types/widgetTypes"
           xmlns="http://www.w3.org/2001/XMLSchema"
           xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
    <element name="keyElem" type="xsd:base64Binary"/>
  </schema>
</types>

<message name="widgetOrder">
  <part name="numOrdered" type="xsd:int"/>
  <part name="keyVal" element="xsd1:keyElem"/>
</message>
<message name="widgetOrderBill">
  <part name="price" type="xsd:float"/>
  <part name="keyVal" element="xsd1:keyElem"/>
</message>
<message name="badSize">
  <part name="numInventory" type="xsd:int"/>
</message>

<portType name="orderWidgets">
  <operation name="placeWidgetOrder">
    <input message="tns:widgetOrder" name="order"/>
    <output message="tns:widgetOrderBill" name="bill"/>
    <fault message="tns:badSize" name="sizeFault"/>
  </operation>
</portType>

<binding name="orderWidgetsBinding" type="tns:orderWidgets">
  <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="placeWidgetOrder">
      <soap12:operation soapAction="" style="document"/>
      <input name="order">
        <soap12:body use="literal" parts="numOrdered"/>
        <soap12:header message="tns:widgetOrder" part="keyVal"/>
      </input>
      <output name="bill">
        <soap12:body use="literal" parts="bill"/>
        <soap12:header message="tns:widgetOrderBill" part="keyVal"/>
      </output>
      <fault name="sizeFault">
        <soap12:body use="literal"/>
      </fault>
  </operation>
</binding>
...
</definitions>

MIME multipart messages are described using a mime:multipartRelated element that contains a number of mime:part elements. To fully describe a MIME multipart message you must do the following:

  1. Inside the input or output message you are sending as a MIME multipart message, add a mime:mulipartRelated element as the first child element of the enclosing message.

  2. Add a mime:part child element to the mime:multipartRelated element and set its name attribute to a unique string.

  3. Add a soap:body element as the child of the mime:part element and set its attributes appropriately.

    [Tip]Tip

    If the contract had a default SOAP binding, you can copy the soap:body element from the corresponding message from the default binding into the MIME multipart message.

  4. Add another mime:part child element to the mime:multipartReleated element and set its name attribute to a unique string.

  5. Add a mime:content child element to the mime:part element to describe the contents of this part of the message.

    To fully describe the contents of a MIME message part the mime:content element has the following attributes:


  6. For each additional MIME part, repeat steps Step 4 and Step 5.

Example 4.2 shows a WSDL fragment defining a service that stores X-rays in JPEG format. The image data, xRay, is stored as an xsd:base64binary and is packed into the MIME multipart message's second part, imageData. The remaining two parts of the input message, patientName and patientNumber, are sent in the first part of the MIME multipart image as part of the SOAP body.

Example 4.2. Contract using SOAP with Attachments

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="XrayStorage"
    targetNamespace="http://mediStor.org/x-rays"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://mediStor.org/x-rays"
    xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <message name="storRequest">
    <part name="patientName" type="xsd:string"/>
    <part name="patientNumber" type="xsd:int"/>
    <part name="xRay" type="xsd:base64Binary"/>
  </message>
  <message name="storResponse">
    <part name="success" type="xsd:boolean"/>
  </message>

  <portType name="xRayStorage">
    <operation name="store">
      <input message="tns:storRequest" name="storRequest"/>
      <output message="tns:storResponse" name="storResponse"/>
    </operation>
  </portType>

  <binding name="xRayStorageBinding" type="tns:xRayStorage">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="store">
      <soap:operation soapAction="" style="document"/>
      <input name="storRequest">
        <mime:multipartRelated>
          <mime:part name="bodyPart">
            <soap:body use="literal"/>
          </mime:part>
          <mime:part name="imageData">
            <mime:content part="xRay" type="image/jpeg"/>
          </mime:part>
        </mime:multipartRelated>
      </input>
      <output name="storResponse">
        <soap:body use="literal"/>
      </output>
    </operation>
  </binding>

  <service name="xRayStorageService">
    <port binding="tns:xRayStorageBinding" name="xRayStoragePort">
      <soap:address location="http://localhost:9000"/>
    </port>
  </service>
</definitions>

SOAP Message Transmission Optimization Mechanism (MTOM) specifies an optimized method for sending binary data as part of a SOAP message. Unlike SOAP with Attachments, MTOM requires the use of XML-binary Optimized Packaging (XOP) packages for transmitting binary data. Using MTOM to send binary data does not require you to fully define the MIME Multipart/Related message as part of the SOAP binding. It does, however, require that you do the following:

  1. Annotate the data that you are going to send as an attachment.

    You can annotate either your WSDL or the Java class that implements your data.

  2. Enable the runtime's MTOM support.

    This can be done either programmatically or through configuration.

  3. Develop a DataHandler for the data being passed as an attachment.

    [Note]Note

    Developing DataHandlers is beyond the scope of this book.

Example 5.1 shows a WSDL document for a Web service that uses a message which contains one string field, one integer field, and a binary field. The binary field is intended to carry a large image file, so it is not appropriate to send it as part of a normal SOAP message.

Example 5.1. Message for MTOM

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="XrayStorage"
    targetNamespace="http://mediStor.org/x-rays"
    xmlns="http://schemas.xmlsoap.org/wsdl/"
    xmlns:tns="http://mediStor.org/x-rays"
    xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/"
    xmlns:xsd1="http://mediStor.org/types/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">

  <types>
    <schema targetNamespace="http://mediStor.org/types/"
            xmlns="http://www.w3.org/2001/XMLSchema">
      <complexType name="xRayType">
        <sequence>
          <element name="patientName" type="xsd:string" />
          <element name="patientNumber" type="xsd:int" />
          <element name="imageData" type="xsd:base64Binary" />
        </sequence>
      </complexType>
      <element name="xRay" type="xsd1:xRayType" />
    </schema>
  </types>

  <message name="storRequest">
    <part name="record" element="xsd1:xRay"/>
  </message>
  <message name="storResponse">
    <part name="success" type="xsd:boolean"/>
  </message>

  <portType name="xRayStorage">
    <operation name="store">
      <input message="tns:storRequest" name="storRequest"/>
      <output message="tns:storResponse" name="storResponse"/>
    </operation>
  </portType>

  <binding name="xRayStorageSOAPBinding" type="tns:xRayStorage">
    <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
    <operation name="store">
      <soap12:operation soapAction="" style="document"/>
      <input name="storRequest">
        <soap12:body use="literal"/>
      </input>
      <output name="storResponse">
        <soap12:body use="literal"/>
      </output>
    </operation>
  </binding>
  ...
</definitions>

If you want to use MTOM to send the binary part of the message as an optimized attachment you must add the xmime:expectedContentTypes attribute to the element containing the binary data. This attribute is defined in the http://www.w3.org/2005/05/xmlmime namespace and specifies the MIME types that the element is expected to contain. You can specify a comma separated list of MIME types. The setting of this attribute changes how the code generators create the JAXB class for the data. For most MIME types, the code generator creates a DataHandler. Some MIME types, such as those for images, have defined mappings.

[Note]Note

The MIME types are maintained by the Internet Assigned Numbers Authority(IANA) and are described in detail in Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies and Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types.

[Tip]Tip

For most uses you specify application/octet-stream.

Example 5.2 shows how you can modify xRayType from Example 5.1 for using MTOM.


The generated JAXB class generated for xRayType no longer contains a byte[]. Instead the code generator sees the xmime:expectedContentTypes attribute and generates a DataHandler for the imageData field.

[Note]Note

You do not need to change the binding element to use MTOM. The runtime makes the appropriate changes when the data is sent.

By default the Fuse Services Framework runtime does not enable MTOM support. It sends all binary data as either part of the normal SOAP message or as an unoptimized attachment. You can activate MTOM support either programmatically or through the use of configuration.

To map an interface to a pure XML payload format do the following:

  1. Add the namespace declaration to include the extensions defining the XML binding. See XML binding namespace.

  2. Add a standard WSDL binding element to your contract to hold the XML binding, give the binding a unique name, and specify the name of the WSDL portType element that represents the interface being bound.

  3. Add an xformat:binding child element to the binding element to identify that the messages are being handled as pure XML documents without SOAP envelopes.

  4. Optionally, set the xformat:binding element's rootNode attribute to a valid QName. For more information on the effect of the rootNode attribute see XML messages on the wire.

  5. For each operation defined in the bound interface, add a standard WSDL operation element to hold the binding information for the operation's messages.

  6. For each operation added to the binding, add the input, output, and fault children elements to represent the messages used by the operation.

    These elements correspond to the messages defined in the interface definition of the logical operation.

  7. Optionally add an xformat:body element with a valid rootNode attribute to the added input, output, and fault elements to override the value of rootNode set at the binding level.

[Note]Note

If any of your messages have no parts, for example the output message for an operation that returns void, you must set the rootNode attribute for the message to ensure that the message written on the wire is a valid, but empty, XML document.

When you specify that an interface’s messages are to be passed as XML documents, without a SOAP envelope, you must take care to ensure that your messages form valid XML documents when they are written on the wire. You also need to ensure that non-Fuse Services Framework participants that receive the XML documents understand the messages generated by Fuse Services Framework.

A simple way to solve both problems is to use the optional rootNode attribute on either the global xformat:binding element or on the individual message’s xformat:body elements. The rootNode attribute specifies the QName for the element that serves as the root node for the XML document generated by Fuse Services Framework. When the rootNode attribute is not set, Fuse Services Framework uses the root element of the message part as the root element when using doc style messages, or an element using the message part name as the root element when using rpc style messages.

For example, if the rootNode attribute is not set the message defined in Example 6.1 would generate an XML document with the root element lineNumber.


For messages with one part, Fuse Services Framework will always generate a valid XML document even if the rootNode attribute is not set. However, the message in Example 6.2 would generate an invalid XML document.


Without the rootNode attribute specified in the XML binding, Fuse Services Framework will generate an XML document similar to Example 6.3 for the message defined in Example 6.2. The generated XML document is invalid because it has two root elements: pairName and entryNum.


If you set the rootNode attribute, as shown in Example 6.4 Fuse Services Framework will wrap the elements in the specified root element. In this example, the rootNode attribute is defined for the entire binding and specifies that the root element will be named entrants.


An XML document generated from the input message would be similar to Example 6.5. Notice that the XML document now only has one root element.


HTTP consumer endpoints can specify a number of HTTP connection attributes including whether the endpoint automatically accepts redirect responses, whether the endpoint can use chunking, whether the endpoint will request a keep-alive, and how the endpoint interacts with proxies. In addition to the HTTP connection properties, an HTTP consumer endpoint can specify how it is secured.

A consumer endpoint can be configured using two mechanisms:

You configure an HTTP consumer endpoint using the http-conf:conduit element and its children. The http-conf:conduit element takes a single attribute, name, that specifies the WSDL port element corresponding to the endpoint. The value for the name attribute takes the form portQName.http-conduit. Example 8.5 shows the http-conf:conduit element that would be used to add configuration for an endpoint that is specified by the WSDL fragment <port binding="widgetSOAPBinding" name="widgetSOAPPort> when the endpoint's target namespace is http://widgets.widgetvendor.net.


The http-conf:conduit element has child elements that specify configuration information. They are described in Table 8.1.


The http-conf:client element is used to configure the non-security properties of a consumer endpoint's HTTP connection. Its attributes, described in Table 8.2, specify the connection's properties.

Table 8.2. HTTP Consumer Configuration Attributes

AttributeDescription
ConnectionTimeout

Specifies the amount of time, in milliseconds, that the consumer attempts to establish a connection before it times out. The default is 30000.

0 specifies that the consumer will continue to send the request indefinitely.

ReceiveTimeout

Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. The default is 30000.

0 specifies that the consumer will wait indefinitely.

AutoRedirect

Specifies if the consumer will automatically follow a server issued redirection. The default is false.

MaxRetransmits

Specifies the maximum number of times a consumer will retransmit a request to satisfy a redirect. The default is -1 which specifies that unlimited retransmissions are allowed.

AllowChunking

Specifies whether the consumer will send requests using chunking. The default is true which specifies that the consumer will use chunking when sending requests.

Chunking cannot be used if either of the following are true:

  • http-conf:basicAuthSupplier is configured to provide credentials preemptively.

  • AutoRedirect is set to true.

In both cases the value of AllowChunking is ignored and chunking is disallowed.

Accept

Specifies what media types the consumer is prepared to handle. The value is used as the value of the HTTP Accept property. The value of the attribute is specified using multipurpose internet mail extensions (MIME) types.

AcceptLanguage

Specifies what language (for example, American English) the consumer prefers for the purpose of receiving a response. The value is used as the value of the HTTP AcceptLanguage property.

Language tags are regulated by the International Organization for Standards (ISO) and are typically formed by combining a language code, determined by the ISO-639 standard, and country code, determined by the ISO-3166 standard, separated by a hyphen. For example, en-US represents American English.

AcceptEncoding

Specifies what content encodings the consumer is prepared to handle. Content encoding labels are regulated by the Internet Assigned Numbers Authority (IANA). The value is used as the value of the HTTP AcceptEncoding property.

ContentType

Specifies the media type of the data being sent in the body of a message. Media types are specified using multipurpose internet mail extensions (MIME) types. The value is used as the value of the HTTP ContentType property. The default is text/xml.

For web services, this should be set to text/xml. If the client is sending HTML form data to a CGI script, this should be set to application/x-www-form-urlencoded. If the HTTP POST request is bound to a fixed payload format (as opposed to SOAP), the content type is typically set to application/octet-stream.

Host

Specifies the Internet host and port number of the resource on which the request is being invoked. The value is used as the value of the HTTP Host property.

This attribute is typically not required. It is only required by certain DNS scenarios or application designs. For example, it indicates what host the client prefers for clusters (that is, for virtual servers mapping to the same Internet protocol (IP) address).

Connection

Specifies whether a particular connection is to be kept open or closed after each request/response dialog. There are two valid values:

  • Keep-Alive — Specifies that the consumer wants the connection kept open after the initial request/response sequence. If the server honors it, the connection is kept open until the consumer closes it.

  • close(default) — Specifies that the connection to the server is closed after each request/response sequence.

CacheControl

Specifies directives about the behavior that must be adhered to by caches involved in the chain comprising a request from a consumer to a service provider. See Consumer Cache Control Directives.

Cookie

Specifies a static cookie to be sent with all requests.

BrowserType

Specifies information about the browser from which the request originates. In the HTTP specification from the World Wide Web consortium (W3C) this is also known as the user-agent. Some servers optimize based on the client that is sending the request.

Referer

Specifies the URL of the resource that directed the consumer to make requests on a particular service. The value is used as the value of the HTTP Referer property.

This HTTP property is used when a request is the result of a browser user clicking on a hyperlink rather than typing a URL. This can allow the server to optimize processing based upon previous task flow, and to generate lists of back-links to resources for the purposes of logging, optimized caching, tracing of obsolete or mistyped links, and so on. However, it is typically not used in web services applications.

If the AutoRedirect attribute is set to true and the request is redirected, any value specified in the Referer attribute is overridden. The value of the HTTP Referer property is set to the URL of the service that redirected the consumer’s original request.

DecoupledEndpoint

Specifies the URL of a decoupled endpoint for the receipt of responses over a separate provider->consumer connection. For more information on using decoupled endpoints see, Using the HTTP Transport in Decoupled Mode.

You must configure both the consumer endpoint and the service provider endpoint to use WS-Addressing for the decoupled endpoint to work.

ProxyServer

Specifies the URL of the proxy server through which requests are routed.

ProxyServerPort

Specifies the port number of the proxy server through which requests are routed.

ProxyServerType

Specifies the type of proxy server used to route requests. Valid values are:

  • HTTP(default)

  • SOCKS


Table 8.3 lists the cache control directives supported by an HTTP consumer.

Table 8.3. http-conf:client Cache Control Directives

DirectiveBehavior
no-cache

Caches cannot use a particular response to satisfy subsequent requests without first revalidating that response with the server. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response.

no-store

Caches must not store either any part of a response or any part of the request that invoked it.

max-age

The consumer can accept a response whose age is no greater than the specified time in seconds.

max-stale

The consumer can accept a response that has exceeded its expiration time. If a value is assigned to max-stale, it represents the number of seconds beyond the expiration time of a response up to which the consumer can still accept that response. If no value is assigned, the consumer can accept a stale response of any age.

min-fresh

The consumer wants a response that is still fresh for at least the specified number of seconds indicated.

no-transform

Caches must not modify media type or location of the content in a response between a provider and a consumer.

only-if-cached

Caches should return only responses that are currently stored in the cache, and not responses that need to be reloaded or revalidated.

cache-extension

Specifies additional extensions to the other cache directives. Extensions can be informational or behavioral. An extended directive is specified in the context of a standard directive, so that applications not understanding the extended directive can adhere to the behavior mandated by the standard directive.


HTTP service provider endpoints can specify a number of HTTP connection attributes including if it will honor keep alive requests, how it interacts with caches, and how tolerant it is of errors in communicating with a consumer.

A service provider endpoint can be configured using two mechanisms:

The http-conf:server element is used to configure the properties of a service provider endpoint's HTTP connection. Its attributes, described in Table 8.5, specify the connection's properties.

Table 8.5. HTTP Service Provider Configuration Attributes

AttributeDescription
ReceiveTimeout

Sets the length of time, in milliseconds, the service provider attempts to receive a request before the connection times out. The default is 30000.

0 specifies that the provider will not timeout.

SuppressClientSendErrors

Specifies whether exceptions are to be thrown when an error is encountered on receiving a request. The default is false; exceptions are thrown on encountering errors.

SuppressClientReceiveErrors

Specifies whether exceptions are to be thrown when an error is encountered on sending a response to a consumer. The default is false; exceptions are thrown on encountering errors.

HonorKeepAlive

Specifies whether the service provider honors requests for a connection to remain open after a response has been sent. The default is false; keep-alive requests are ignored.

RedirectURL

Specifies the URL to which the client request should be redirected if the URL specified in the client request is no longer appropriate for the requested resource. In this case, if a status code is not automatically set in the first line of the server response, the status code is set to 302 and the status description is set to Object Moved. The value is used as the value of the HTTP RedirectURL property.

CacheControl

Specifies directives about the behavior that must be adhered to by caches involved in the chain comprising a response from a service provider to a consumer. See Service Provider Cache Control Directives.

ContentLocation

Sets the URL where the resource being sent in a response is located.

ContentType

Specifies the media type of the information being sent in a response. Media types are specified using multipurpose internet mail extensions (MIME) types. The value is used as the value of the HTTP ContentType location.

ContentEncoding

Specifies any additional content encodings that have been applied to the information being sent by the service provider. Content encoding labels are regulated by the Internet Assigned Numbers Authority (IANA). Possible content encoding values include zip, gzip, compress, deflate, and identity. This value is used as the value of the HTTP ContentEncoding property.

The primary use of content encodings is to allow documents to be compressed using some encoding mechanism, such as zip or gzip. Fuse Services Framework performs no validation on content codings. It is the user’s responsibility to ensure that a specified content coding is supported at application level.

ServerType

Specifies what type of server is sending the response. Values take the form program-name/version; for example, Apache/1.2.5.


Table 8.6 lists the cache control directives supported by an HTTP service provider.

Table 8.6. http-conf:server Cache Control Directives

DirectiveBehavior
no-cache

Caches cannot use a particular response to satisfy subsequent requests without first revalidating that response with the server. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response.

public

Any cache can store the response.

private

Public (shared) caches cannot store the response because the response is intended for a single user. If specific response header fields are specified with this value, the restriction applies only to those header fields within the response. If no response header fields are specified, the restriction applies to the entire response.

no-store

Caches must not store any part of the response or any part of the request that invoked it.

no-transform

Caches must not modify the media type or location of the content in a response between a server and a client.

must-revalidate

Caches must revalidate expired entries that relate to a response before that entry can be used in a subsequent response.

proxy-revalidate

Does the same as must-revalidate, except that it can only be enforced on shared caches and is ignored by private unshared caches. When using this directive, the public cache directive must also be used.

max-age

Clients can accept a response whose age is no greater that the specified number of seconds.

s-max-age

Does the same as max-age, except that it can only be enforced on shared caches and is ignored by private unshared caches. The age specified by s-max-age overrides the age specified by max-age. When using this directive, the proxy-revalidate directive must also be used.

cache-extension

Specifies additional extensions to the other cache directives. Extensions can be informational or behavioral. An extended directive is specified in the context of a standard directive, so that applications not understanding the extended directive can adhere to the behavior mandated by the standard directive.


The httpj:engine element is used to configure specific instances of the Jetty runtime. It has a single attribute, port, that specifies the number of the port being managed by the Jetty instance.

[Tip]Tip

You can specify a value of 0 for the port attribute. Any threading properties specified in an httpj:engine element with its port attribute set to 0 are used as the configuration for all Jetty listeners that are not explicitly configured.

Each httpj:engine element can have two children: one for configuring security properties and one for configuring the Jetty instance's thread pool. For each type of configuration you can either directly provide the configuration information or you can provide a reference to a set of configuration properties defined in the parent httpj:engine-factory element.

The child elements used to provide the configuration properties are described in Table 8.8.


Using the HTTP transport in decoupled mode adds extra layers of complexity to the processing of HTTP messages. While the added complexity is transparent to the implementation level code in an application, it might be important to understand what happens for debugging reasons.

Figure 8.1 shows the flow of messages when using HTTP in decoupled mode.


A request starts the following process:

  1. The consumer implementation invokes an operation and a request message is generated.

  2. The WS-Addressing layer adds the WS-A headers to the message.

    When a decoupled endpoint is specified in the consumer's configuration, the address of the decoupled endpoint is placed in the WS-A ReplyTo header.

  3. The message is sent to the service provider.

  4. The service provider receives the message.

  5. The request message from the consumer is dispatched to the provider's WS-A layer.

  6. Because the WS-A ReplyTo header is not set to anonymous, the provider sends back a message with the HTTP status code set to 202, acknowledging that the request has been received.

  7. The HTTP layer sends a 202 Accepted message back to the consumer using the original connection's back-channel.

  8. The consumer receives the 202 Accepted reply on the back-channel of the HTTP connection used to send the original message.

    When the consumer receives the 202 Accepted reply, the HTTP connection closes.

  9. The request is passed to the service provider's implementation where the request is processed.

  10. When the response is ready, it is dispatched to the WS-A layer.

  11. The WS-A layer adds the WS-Addressing headers to the response message.

  12. The HTTP transport sends the response to the consumer's decoupled endpoint.

  13. The consumer's decoupled endpoint receives the response from the service provider.

  14. The response is dispatched to the consumer's WS-A layer where it is correlated to the proper request using the WS-A RelatesTo header.

  15. The correlated response is returned to the client implementation and the invoking call is unblocked.

The SOAP over JMS protocol is defined by the World Wide Web Consortium(W3C) as a way of providing a more reliable transport layer to the customary SOAP/HTTP protocol used by most services. The Fuse Services Framework implementation is fully compliant with the specification and should be compatible with any framework that is also compliant.

This transport uses JNDI to find the JMS destinations. When an operation is invoked, the request is packaged as a SOAP message and sent in the body of a JMS message to the specified destination.

To use the SOAP/JMS transport:

  1. Specify that the transport type is SOAP/JMS.

  2. Specify the target destination using a JMS URI.

  3. Optionally, configure the JNDI connection.

  4. Optionally, add additional JMS configuration.

You specify the address of the JMS target destination when specifying the WSDL port for the endpoint. The address specification for a SOAP/JMS endpoint uses the same soap:address element and attribute as a SOAP/HTTP endpoint. The difference is the address specification. JMS endpoints use a JMS URI as defined in the URI Scheme for JMS 1.0. Example 9.2 shows the syntax for a JMS URI.


Table 9.1 describes the available variants for the JMS URI.


The options portion of a JMS URI are used to configure the transport and are discussed in JMS URIs.

Example 9.3 shows the WSDL port entry for a SOAP/JMS endpoint whose target destination is looked up using JNDI.


For working with SOAP/JMS services in Java see Using SOAP over JMS in Developing Applications Using JAX-WS.

As shown in Example 9.2, you can append one or more options to the end of a JMS URI by separating them from the destination's address with a question mark(?). Multiple options are separated by an ampersand(&). Example 9.4 shows the syntax for using multiple options in a JMS URI.


Table 9.4 shows all of the WSDL extension elements you can use to configure the JMS transport.

Table 9.4. SOAP/JMS WSDL extension elements

ElementDefaultDescription
soapjms:jndiInitialContextFactory Specifies the fully qualified Java class name of the JNDI provider. Equivalent to setting the java.naming.factory.initial Java system property.
soapjms:jndiURL Specifies the URL that initializes the JNDI provider. Equivalent to setting the java.naming.provider.url Java system property.
soapjms:jndiContextParameter Enables you to specify an additional property for creating the JNDI InitialContext. Use the name and value attributes to specify the property.
soapjms:jndiConnectionFactoryName Specifies the JNDI name of the JMS connection factory.
soapjms:deliveryModePERSISTENTSpecifies whether to use JMS PERSISTENT or NON_PERSISTENT message semantics. In the case of PERSISTENT delivery mode, the JMS broker stores messages in persistent storage before acknowledging them; whereas NON_PERSISTENT messages are kept in memory only.
soapjms:replyToName 

Explicitly specifies the reply destination to appear in the JMSReplyTo header. Setting this property is recommended for SOAP invocations that have request-reply semantics. If this property is not set the JMS provider allocates a temporary queue with an automatically generated name.

The value of this property has an interpretation that depends on the variant specified in the JMS URI, as follows:

  • jndi variant—the JNDI name of the destination.

  • queue or topic variants—the actual name of the destination.

soapjms:priority4Specifies the JMS message priority, which ranges from 0 (lowest) to 9 (highest).
soapjms:timeToLive0Time, in milliseconds, after which the message will be discarded by the JMS provider. A value of 0 represents an infinite lifetime.

Example 9.7 shows a WSDL contract for a SOAP/JMS service. It configures the JNDI layer in the binding scope, the message delivery details in the service scope, and the reply destination in the port scope.

Example 9.7. WSDL contract with SOAP/JMS configuration

<wsd;definitions ...
1    xmlns:soapjms="http://www.w3.org/2010/soapjms/"
  ... >
  ...
  <wsdl:binding name="JMSGreeterPortBinding" type="tns:JMSGreeterPortType">
    ...
2    <soapjms:jndiInitialContextFactory>
      org.apache.activemq.jndi.ActiveMQInitialContextFactory
    </soapjms:jndiInitialContextFactory>
    <soapjms:jndiURL>tcp://localhost:61616</soapjms:jndiURL>
    <soapjms:jndiConnectionFactoryName>
      ConnectionFactory
    </soapjms:jndiConnectionFactoryName>
    ...
  </wsdl:binding>
  ...
  <wsdl:service name="JMSGreeterService">
    ...
3    <soapjms:deliveryMode>NON_PERSISTENT</soapjms:deliveryMode>
    <soapjms:timeToLive>60000</soapjms:timeToLive>
    ...
    <wsdl:port binding="tns:JMSGreeterPortBinding" name="GreeterPort">
4      <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" />
5      <soapjms:replyToName>
        dynamicQueues/greeterReply.queue
      </soapjms:replyToName>
      ...
    </wsdl:port>
    ...
  </wsdl:service>
  ...
</wsdl:definitions>

The WSDL in Example 9.7 does the following:

1

Declare the namespace for the SOAP/JMS extensions.

2

Configure the JNDI connections in the binding scope.

3

Configure the JMS delivery style to non-persistent and each message to live for one minute.

4

Specify the target destination.

5

Configure the JMS transport so that reply messages are delivered on the greeterReply.queue queue.

The Fuse Services Framework generic JMS transport can connect to any JMS provider and work with applications that exchange JMS messages with bodies of either TextMessage or ByteMessage.

There are two ways to enable and configure the JMS transport:

You specify the JMS configuration by defining a bean of class org.apache.cxf.transport.jms.JMSConfiguration. The properties of the bean provide the configuration settings for the transport.

Table 10.1 lists properties that are common to both providers and consumers.

Table 10.1. General JMS Configuration Properties

PropertyDefaultDescription
connectionFactory-ref Specifies a reference to a bean that defines a JMS ConnectionFactory.
wrapInSingleConnectionFactorytrueSpecifies whether to wrap the ConnectionFactory with a Spring SingleConnectionFactory. Doing so can improve the performance of the JMS transport when the specified connection factory does not pool connections.
reconnectOnExceptionfalseSpecifies whether to create a new connection in the case of an exception. This property is only used when wrapping the connection factory with a Spring SingleConnectionFactory.
targetDestination Specifies the JNDI name or provider specific name of a destination.
replyDestination Specifies the JMS name of the JMS destinations where replies are sent. This attribute allows you to use a user defined destination for replies. For more details see Using a Named Reply Destination.
destinationResolver Specifies a reference to a Spring DestinationResolver. This allows you to define how destination names are resolved. By default a DynamicDestinationResolver is used. It resolves destinations using the JMS providers features. If you reference a JndiDestinationResolver you can resolve the destination names using JNDI.
transactionManager Specifies a reference to a Spring transaction manager. This allows the service to participate in JTA Transactions.
taskExecutor Specifies a reference to a Spring TaskExecutor. This is used in listeners to decide how to handle incoming messages. By default the transport uses the Spring SimpleAsyncTaskExecutor.
useJms11falseSpecifies whether JMS 1.1 features are available.
messageIdEnabledtrueSpecifies whether the JMS transport wants the JMS broker to provide message IDs. Setting this to false causes the endpoint to call its message producer's setDisableMessageID() method with a value of true. The JMS broker is then given a hint that it does not need to generate message IDs or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
messageTimestampEnabledtrueSpecifies whether the JMS transport wants the JMS broker to provide message time stamps. Setting this to false causes the endpoint to call its message producer's setDisableMessageTimestamp() method with a value of true. The JMS broker is then given a hint that it does not need to generate time stamps or add them to the messages from the endpoint. The JMS broker can choose to accept the hint or ignore it.
cacheLevel3Specifies the level of caching allowed by the listener. Valid values are 0(CACHE_NONE), 1(CACHE_CONNECTION), 2(CACHE_SESSION), 3(CACHE_CONSUMER), 4(CACHE_AUTO).
pubSubNoLocalfalseSpecifies whether to receive messages produced from the same connection.
receiveTimeout0Specifies, in milliseconds, the amount of time to wait for response messages. 0 means wait indefinitely.
explicitQosEnabledfalseSpecifies whether the QoS settings like priority, persistence, and time to live are explicitly set for each message or if they are allowed to use default values.
deliveryMode1

Specifies if a message is persistent. The two values are:

  • 1(NON_PERSISTENT)—messages will be kept memory

  • 2(PERSISTENT)—messages will be persisted to disk

priority4Specifies the message's priority for the messages. JMS priority values can range from 0 to 9. The lowest priority is 0 and the highest priority is 9.
timeToLive0Specifies, in milliseconds, the message will be available after it is sent. 0 specifies an infinite time to live.
sessionTransactedfalseSpecifies if JMS transactions are used.
concurrentConsumers1Specifies the minimum number of concurrent consumers created by the listener.
maxConcurrentConsumers1Specifies the maximum number of concurrent consumers by listener.
messageSelector Specifies the string value of the selector. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification.
subscriptionDurablefalseSpecifies whether the server uses durrable subscriptions.
durableSubscriptionName Specifies the string used to register the durable subscription.
messageTypetextSpecifies how the message data will be packaged as a JMS message. text specifies that the data will be packaged as a TextMessage. binary specifies that the data will be packaged as an ByteMessage.
pubSubDomainfalseSpecifies whether the target destination is a topic.
jmsProviderTibcoEmsfalseSpecifies if your JMS provider is Tibco EMS. This causes the principal in the security context to be populated from the JMS_TIBCO_SENDER header.
useMessageIDAsCorrelationIDfalseSpecifies whether JMS will use the message ID to correlate messages. If not, the client will set a generated correlation ID.

As shown in Example 10.2, the bean's properties are specified as attributes to the bean element. They are all declared in the Spring p namespace.


The WSDL extensions for defining a JMS endpoint are defined in the namespace http://cxf.apache.org/transports/jms. In order to use the JMS extensions you will need to add the line shown in Example 10.5 to the definitions element of your contract.


The basic configuration for a JMS endpoint is done by using a jms:address element as the child of your service’s port element. The jms:address element used in WSDL is identical to the one used in the configuration file. Its attributes are listed in Table 10.2.


The jms:address WSDL element uses a jms:JMSNamingProperties child element to specify additional information needed to connect to a JNDI provider.

The Fuse Services Framework JMS configuration properties are specified under the http://cxf.apache.org/transports/jms namespace. In order to use the JMS configuration properties you will need to add the line shown in Example C.1 to the beans element of your configuration.


C

configuration
consumer endpoint (see jms:conduit)
HTTP consumer connection properties, The client element
HTTP consumer endpoint, Using Configuration
HTTP service provider connection properties, The server element
HTTP service provider endpoint, Using Configuration
HTTP thread pool, Configuring the thread pool
Jetty engine, The engine-factory element
Jetty instance, The engine element
JMS session pool (see jms:sessionPool)
jms:address (see jms:address)
provider endpoint (see jms:destination)
provider endpoint properties, Quality of service configuration
provider runtime, Runtime configuration
consumer runtime configuration, jms:clientConfig
request time to live, jms:clientConfig
response timeout, jms:clientConfig

E

endpoint address configuration (see jms:address)

H

HTTP
endpoint address, Adding a Basic HTTP Endpoint
http-conf:authorization, The conduit element
http-conf:basicAuthSupplier, The conduit element
http-conf:client, The client element
Accept, The client element
AcceptEncoding, The client element
AcceptLanguage, The client element
AllowChunking, The client element
AutoRedirect, The client element
BrowserType, The client element
CacheControl, The client element, Consumer Cache Control Directives
Connection, The client element
ConnectionTimeout, The client element
ContentType, The client element
Cookie, The client element
DecoupledEndpoint, The client element, Configuring the consumer
Host, The client element
MaxRetransmits, The client element
ProxyServer, The client element
ProxyServerPort, The client element
ProxyServerType, The client element
ReceiveTimeout, The client element
Referer, The client element
http-conf:conduit, The conduit element
name attribute, The conduit element
http-conf:contextMatchStrategy, The destination element
http-conf:destination, The destination element
name attribute, The destination element
http-conf:fixedParameterOrder, The destination element
http-conf:proxyAuthorization, The conduit element
http-conf:server, The destination element, The server element
CacheControl, The server element, Service Provider Cache Control Directives
ContentEncoding, The server element
ContentLocation, The server element
ContentType, The server element
HonorKeepAlive, The server element
ReceiveTimeout, The server element
RedirectURL, The server element
ServerType, The server element
SuppressClientReceiveErrors, The server element
SuppressClientSendErrors, The server element
http-conf:tlsClientParameters, The conduit element
http-conf:trustDecider, The conduit element
http:address, Other messages types
httpj:engine, The engine element
httpj:engine-factory, The engine-factory element
httpj:identifiedThreadingParameters, The engine-factory element, Configuring the thread pool
httpj:identifiedTLSServerParameters, The engine-factory element
httpj:threadingParameters, The engine element, Configuring the thread pool
maxThreads, Configuring the thread pool
minThreads, Configuring the thread pool
httpj:threadingParametersRef, The engine element
httpj:tlsServerParameters, The engine element
httpj:tlsServerParametersRef, The engine element

J

JMS
specifying the message type, Specifying the message type
JMS destination
specifying, Specifying the JMS address
jms:address, Specifying the JMS address
connectionPassword attribute, Specifying the JMS address
connectionUserName attribute, Specifying the JMS address
destinationStyle attribute, Specifying the JMS address
jmsDestinationName attribute, Specifying the JMS address
jmsiReplyDestinationName attribute, Using a Named Reply Destination
jmsReplyDestinationName attribute, Specifying the JMS address
jndiConnectionFactoryName attribute, Specifying the JMS address
jndiDestinationName attribute, Specifying the JMS address
jndiReplyDestinationName attribute, Specifying the JMS address, Using a Named Reply Destination
jms:client, Specifying the message type
messageType attribute, Specifying the message type
jms:clientConfig, jms:clientConfig
clientReceiveTimeout, jms:clientConfig
messageTimeToLive, jms:clientConfig
jms:conduit, Configuration elements, Configuration elements
jms:destination, Configuration elements, Configuration elements
jms:JMSNamingProperties, Specifying JNDI properties, The JMSNamingProperties element
jms:runtimePolicy
consumer endpoint properties, Specifying the message type
durableSubscriberName, Quality of service configuration
messageSelector, Quality of service configuration
messageType attribute, Specifying the message type
provider configuration, Quality of service configuration
transactional, Quality of service configuration
useMessageIDAsCorrealationID, Quality of service configuration
jms:server, Specifying the configuration
durableSubscriberName, Specifying the configuration
messageSelector, Specifying the configuration
transactional, Specifying the configuration
useMessageIDAsCorrealationID, Specifying the configuration
jms:serverConfig, Runtime configuration
durableSubscriptionClientId, Runtime configuration
messageTimeToLive, Runtime configuration
jms:sessionPool, Configuration element
highWaterMark, Configuration element
lowWaterMark, Configuration element
JMSConfiguration, Specifying the configuration
JNDI
specifying the connection factory, Specifying the JMS address

N

named reply destination
specifying in WSDL, Specifying the JMS address
using, Using a Named Reply Destination

P

provider runtime configuration, Runtime configuration
durable subscriber identification, Runtime configuration
response time to live, Runtime configuration

S

session pool configuration (see jms:sessionPool)
SOAP 1.1
endpoint address, SOAP 1.1
SOAP 1.2
endpoint address, SOAP 1.2
SOAP Message Transmission Optimization Mechanism, Sending Binary Data with SOAP MTOM
soap12:address, SOAP 1.2
soap12:body
parts, Splitting messages between body and header
soap12:header, Overview
encodingStyle, Syntax
message, Syntax
namespace, Syntax
part, Syntax
use, Syntax
soap:address, SOAP 1.1
soap:body
parts, Splitting messages between body and header
soap:header, Overview
encodingStyle, Syntax
message, Syntax
namespace, Syntax
part, Syntax
use, Syntax

W

WS-Addressing
using, Configuring an endpoint to use WS-Addressing
wsam:Addressing, Configuring an endpoint to use WS-Addressing
WSDL
binding element, The WSDL elements
name attribute, The WSDL elements
port element, The WSDL elements
binding attribute, The WSDL elements
service element, The WSDL elements
name attribute, The WSDL elements
WSDL extensors
jms:address (see jms:address)
jms:client (see jms:client)
jms:JMSNamingProperties (see jms:JMSNamingProperties)
jms:server (see jms:server)
wsdl2soap, Using wsdl2soap, Using wsdl2soap
wswa:UsingAddressing, Configuring an endpoint to use WS-Addressing

X

xformat:binding, Hand editing
rootNode, Hand editing
xformat:body, Hand editing
rootNode, Hand editing