Apache CXF Development Guide
Develop applications with Apache CXF Web services
Abstract
Part I. Writing WSDL Contracts
This part describes how to define a Web service interface using WSDL.
Chapter 1. Introducing WSDL Contracts
Abstract
WSDL documents define services using Web Service Description Language and a number of possible extensions. The documents have a logical part and a concrete part. The abstract part of the contract defines the service in terms of implementation neutral data types and messages. The concrete part of the document defines how an endpoint implementing a service will interact with the outside world.
The recommended approach to design services is to define your services in WSDL and XML Schema before writing any code. When hand-editing WSDL documents you must make sure that the document is valid, as well as correct. To do this you must have some familiarity with WSDL. You can find the standard on the W3C web site, www.w3.org.
1.1. Structure of a WSDL document
Overview
A WSDL document is, at its simplest, a collection of elements contained within a root definition
element. These elements describe a service and how an endpoint implementing that service is accessed.
A WSDL document has two distinct parts:
- A logical part that defines the service in implementation neutral terms
- A concrete part that defines how an endpoint implementing the service is exposed on a network
The logical part
The logical part of a WSDL document contains the types
, the message
, and the portType
elements. It describes the service’s interface and the messages exchanged by the service. Within the types
element, XML Schema is used to define the structure of the data that makes up the messages. A number of message
elements are used to define the structure of the messages used by the service. The portType
element contains one or more operation
elements that define the messages sent by the operations exposed by the service.
The concrete part
The concrete part of a WSDL document contains the binding
and the service
elements. It describes how an endpoint that implements the service connects to the outside world. The binding
elements describe how the data units described by the message
elements are mapped into a concrete, on-the-wire data format, such as SOAP. The service
elements contain one or more port
elements which define the endpoints implementing the service.
1.2. WSDL elements
A WSDL document is made up of the following elements:
-
definitions
— The root element of a WSDL document. The attributes of this element specify the name of the WSDL document, the document’s target namespace, and the shorthand definitions for the namespaces referenced in the WSDL document. -
types
— The XML Schema definitions for the data units that form the building blocks of the messages used by a service. For information about defining data types see Chapter 2, Defining Logical Data Units. -
message
— The description of the messages exchanged during invocation of a services operations. These elements define the arguments of the operations making up your service. For information on defining messages see Chapter 3, Defining Logical Messages Used by a Service. -
portType
— A collection ofoperation
elements describing the logical interface of a service. For information about defining port types see Chapter 4, Defining Your Logical Interfaces. -
operation
— The description of an action performed by a service. Operations are defined by the messages passed between two endpoints when the operation is invoked. For information on defining operations see the section called “Operations”. -
binding
— The concrete data format specification for an endpoint. Abinding
element defines how the abstract messages are mapped into the concrete data format used by an endpoint. This element is where specifics such as parameter order and return values are specified. -
service
— A collection of relatedport
elements. These elements are repositories for organizing endpoint definitions. -
port
— The endpoint defined by a binding and a physical address. These elements bring all of the abstract definitions together, combined with the definition of transport details, and they define the physical endpoint on which a service is exposed.
1.3. Designing a contract
To design a WSDL contract for your services you must perform the following steps:
- Define the data types used by your services.
- Define the messages used by your services.
- Define the interfaces for your services.
- Define the bindings between the messages used by each interface and the concrete representation of the data on the wire.
- Define the transport details for each of the services.
Chapter 2. Defining Logical Data Units
Abstract
When describing a service in a WSDL contract complex data types are defined as logical units using XML Schema.
2.1. Introduction to Logical Data Units
When defining a service, the first thing you must consider is how the data used as parameters for the exposed operations is going to be represented. Unlike applications that are written in a programming language that uses fixed data structures, services must define their data in logical units that can be consumed by any number of applications. This involves two steps:
- Breaking the data into logical units that can be mapped into the data types used by the physical implementations of the service
- Combining the logical units into messages that are passed between endpoints to carry out the operations
This chapter discusses the first step. Chapter 3, Defining Logical Messages Used by a Service discusses the second step.
2.2. Mapping data into logical data units
Overview
The interfaces used to implement a service define the data representing operation parameters as XML documents. If you are defining an interface for a service that is already implemented, you must translate the data types of the implemented operations into discreet XML elements that can be assembled into messages. If you are starting from scratch, you must determine the building blocks from which your messages are built, so that they make sense from an implementation standpoint.
Available type systems for defining service data units
According to the WSDL specification, you can use any type system you choose to define data types in a WSDL contract. However, the W3C specification states that XML Schema is the preferred canonical type system for a WSDL document. Therefore, XML Schema is the intrinsic type system in Apache CXF.
XML Schema as a type system
XML Schema is used to define how an XML document is structured. This is done by defining the elements that make up the document. These elements can use native XML Schema types, like xsd:int
, or they can use types that are defined by the user. User defined types are either built up using combinations of XML elements or they are defined by restricting existing types. By combining type definitions and element definitions you can create intricate XML documents that can contain complex data.
When used in WSDL XML Schema defines the structure of the XML document that holds the data used to interact with a service. When defining the data units used by your service, you can define them as types that specify the structure of the message parts. You can also define your data units as elements that make up the message parts.
Considerations for creating your data units
You might consider simply creating logical data units that map directly to the types you envision using when implementing the service. While this approach works, and closely follows the model of building RPC-style applications, it is not necessarily ideal for building a piece of a service-oriented architecture.
The Web Services Interoperability Organization’s WS-I basic profile provides a number of guidelines for defining data units and can be accessed at http://www.ws-i.org/Profiles/BasicProfile-1.1-2004-08-24.html#WSDLTYPES. In addition, the W3C also provides the following guidelines for using XML Schema to represent data types in WSDL documents:
- Use elements, not attributes.
- Do not use protocol-specific types as base types.
2.3. Adding data units to a contract
Overview
Depending on how you choose to create your WSDL contract, creating new data definitions requires varying amounts of knowledge. The Apache CXF GUI tools provide a number of aids for describing data types using XML Schema. Other XML editors offer different levels of assistance. Regardless of the editor you choose, it is a good idea to have some knowledge about what the resulting contract should look like.
Procedure
Defining the data used in a WSDL contract involves the following steps:
- Determine all the data units used in the interface described by the contract.
-
Create a
types
element in your contract. Create a
schema
element, shown in Example 2.1, “Schema entry for a WSDL contract”, as a child of thetype
element.The
targetNamespace
attribute specifies the namespace under which new data types are defined. Best practice is to also define the namespace that provides access to the target namespace. The remaining entries should not be changed.Example 2.1. Schema entry for a WSDL contract
<schema targetNamespace="http://schemas.iona.com/bank.idl" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xsd1="http://schemas.iona.com/bank.idl" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
-
For each complex type that is a collection of elements, define the data type using a
complexType
element. See Section 2.5.1, “Defining data structures”. -
For each array, define the data type using a
complexType
element. See Section 2.5.2, “Defining arrays”. -
For each complex type that is derived from a simple type, define the data type using a
simpleType
element. See Section 2.5.4, “Defining types by restriction”. -
For each enumerated type, define the data type using a
simpleType
element. See Section 2.5.5, “Defining enumerated types”. -
For each element, define it using an
element
element. See Section 2.6, “Defining elements”.
2.4. XML Schema simple types
Overview
If a message part is going to be of a simple type it is not necessary to create a type definition for it. However, the complex types used by the interfaces defined in the contract are defined using simple types.
Entering simple types
XML Schema simple types are mainly placed in the element
elements used in the types section of your contract. They are also used in the base
attribute of restriction
elements and extension
elements.
Simple types are always entered using the xsd
prefix. For example, to specify that an element is of type int
, you would enter xsd:int
in its type
attribute as shown in Example 2.2, “Defining an element with a simple type”.
Example 2.2. Defining an element with a simple type
<element name="simpleInt" type="xsd:int" />
Supported XSD simple types
Apache CXF supports the following XML Schema simple types:
-
xsd:string
-
xsd:normalizedString
-
xsd:int
-
xsd:unsignedInt
-
xsd:long
-
xsd:unsignedLong
-
xsd:short
-
xsd:unsignedShort
-
xsd:float
-
xsd:double
-
xsd:boolean
-
xsd:byte
-
xsd:unsignedByte
-
xsd:integer
-
xsd:positiveInteger
-
xsd:negativeInteger
-
xsd:nonPositiveInteger
-
xsd:nonNegativeInteger
-
xsd:decimal
-
xsd:dateTime
-
xsd:time
-
xsd:date
-
xsd:QName
-
xsd:base64Binary
-
xsd:hexBinary
-
xsd:ID
-
xsd:token
-
xsd:language
-
xsd:Name
-
xsd:NCName
-
xsd:NMTOKEN
-
xsd:anySimpleType
-
xsd:anyURI
-
xsd:gYear
-
xsd:gMonth
-
xsd:gDay
-
xsd:gYearMonth
-
xsd:gMonthDay
2.5. Defining complex data types
Abstract
XML Schema provides a flexible and powerful mechanism for building complex data structures from its simple data types. You can create data structures by creating a sequence of elements and attributes. You can also extend your defined types to create even more complex types.
In addition to building complex data structures, you can also describe specialized types such as enumerated types, data types that have a specific range of values, or data types that need to follow certain patterns by either extending or restricting the primitive types.
2.5.1. Defining data structures
Overview
In XML Schema, data units that are a collection of data fields are defined using complexType
elements. Specifying a complex type requires three pieces of information:
-
The name of the defined type is specified in the
name
attribute of thecomplexType
element. -
The first child element of the
complexType
describes the behavior of the structure’s fields when it is put on the wire. See the section called “Complex type varieties”. -
Each of the fields of the defined structure are defined in
element
elements that are grandchildren of thecomplexType
element. See the section called “Defining the parts of a structure”.
For example, the structure shown in Example 2.3, “Simple Structure” is defined in XML Schema as a complex type with two elements.
Example 2.3. Simple Structure
struct personalInfo { string name; int age; };
Example 2.4, “A complex type” shows one possible XML Schema mapping for the structure shown in Example 2.3, “Simple Structure” The structure defined in Example 2.4, “A complex type” generates a message containing two elements: name
and age
.
.
Example 2.4. A complex type
<complexType name="personalInfo"> <sequence> <element name="name" type="xsd:string" /> <element name="age" type="xsd:int" /> </sequence> </complexType>
Complex type varieties
XML Schema has three ways of describing how the fields of a complex type are organized when represented as an XML document and passed on the wire. The first child element of the complexType
element determines which variety of complex type is being used. Table 2.1, “Complex type descriptor elements” shows the elements used to define complex type behavior.
Element | Complex Type Behavior |
---|---|
All of a complex type’s fields can be present and they must be in the order in which they are specified in the type definition. | |
All of the complex type’s fields can be present but they can be in any order. | |
Only one of the elements in the structure can be placed in the message. |
If the structure is defined using a choice
element, as shown in Example 2.5, “Simple complex choice type”, it generates a message with either a name
element or an age
element.
Example 2.5. Simple complex choice type
<complexType name="personalInfo"> <choice> <element name="name" type="xsd:string"/> <element name="age" type="xsd:int"/> </choice> </complexType>
Defining the parts of a structure
You define the data fields that make up a structure using element
elements. Every complexType
element should contain at least one element
element. Each element
element in the complexType
element represents a field in the defined data structure.
To fully describe a field in a data structure, element
elements have two required attributes:
In addition to name
and type
, element
elements have two other commonly used optional attributes: minOcurrs
and maxOccurs
. These attributes place bounds on the number of times the field occurs in the structure. By default, each field occurs only once in a complex type. Using these attributes, you can change how many times a field must or can appear in a structure. For example, you can define a field, previousJobs
, that must occur at least three times, and no more than seven times, as shown in Example 2.6, “Simple complex type with occurrence constraints”.
Example 2.6. Simple complex type with occurrence constraints
<complexType name="personalInfo"> <all> <element name="name" type="xsd:string"/> <element name="age" type="xsd:int"/> <element name="previousJobs" type="xsd:string: minOccurs="3" maxOccurs="7"/> </all> </complexType>
You can also use the minOccurs
to make the age
field optional by setting the minOccurs
to zero as shown in Example 2.7, “Simple complex type with minOccurs set to zero”. In this case age
can be omitted and the data will still be valid.
Example 2.7. Simple complex type with minOccurs set to zero
<complexType name="personalInfo"> <choice> <element name="name" type="xsd:string"/> <element name="age" type="xsd:int" minOccurs="0"/> </choice> </complexType>
Defining attributes
In XML documents, attributes are contained in the element’s tag. For example, in the complexType
element in the code below, name
is an attribute. To specify an attribute for a complex type, you define an attribute
element in the complexType
element definition. An attribute
element can appear only after the all
, sequence
, or choice
element. Specify one attribute
element for each of the complex type’s attributes. Any attribute
elements must be direct children of the complexType
element.
Example 2.8. Complex type with an attribute
<complexType name="personalInfo"> <all> <element name="name" type="xsd:string"/> <element name="previousJobs" type="xsd:string" minOccurs="3" maxOccurs="7"/> </all> <attribute name="age" type="xsd:int" use="required" /> </complexType>
In the previous code, the attribute
element specifies that the personalInfo
complex type has an age
attribute. The attribute
element has these attributes:
-
name
— A required attribute that specifies the string that identifies the attribute. -
type
— Specifies the type of the data stored in the field. The type can be one of the XML Schema simple types. -
use
— An optional attribute that specifies whether the complex type is required to have this attribute. Valid values arerequired
oroptional
. The default is that the attribute is optional.
In an attribute
element, you can specify the optional default
attribute, which lets you specify a default value for the attribute.
2.5.2. Defining arrays
Overview
Apache CXF supports two methods for defining arrays in a contract. The first is define a complex type with a single element whose maxOccurs
attribute has a value greater than one. The second is to use SOAP arrays. SOAP arrays provide added functionality such as the ability to easily define multi-dimensional arrays and to transmit sparsely populated arrays.
Complex type arrays
Complex type arrays are a special case of a sequence complex type. You simply define a complex type with a single element and specify a value for the maxOccurs
attribute. For example, to define an array of twenty floating point numbers you use a complex type similar to the one shown in Example 2.9, “Complex type array”.
Example 2.9. Complex type array
<complexType name="personalInfo"> <element name="averages" type="xsd:float" maxOccurs="20"/> </complexType>
You can also specify a value for the minOccurs
attribute.
SOAP arrays
SOAP arrays are defined by deriving from the SOAP-ENC:Array
base type using the wsdl:arrayType
element. The syntax for this is shown in Example 2.10, “Syntax for a SOAP array derived using wsdl:arrayType”. Ensure that the definitions
element declares xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
.
Example 2.10. Syntax for a SOAP array derived using wsdl:arrayType
<complexType name="TypeName"> <complexContent> <restriction base="SOAP-ENC:Array"> <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="ElementType<ArrayBounds>"/> </restriction> </complexContent> </complexType>
Using this syntax, TypeName specifies the name of the newly-defined array type. ElementType specifies the type of the elements in the array. ArrayBounds specifies the number of dimensions in the array. To specify a single dimension array use []
; to specify a two-dimensional array use either [][]
or [,]
.
For example, the SOAP Array, SOAPStrings, shown in Example 2.11, “Definition of a SOAP array”, defines a one-dimensional array of strings. The wsdl:arrayType
attribute specifies the type of the array elements, xsd:string
, and the number of dimensions, with []
implying one dimension.
Example 2.11. Definition of a SOAP array
<complexType name="SOAPStrings"> <complexContent> <restriction base="SOAP-ENC:Array"> <attribute ref="SOAP-ENC:arrayType" wsdl:arrayType="xsd:string[]"/> </restriction> </complexContent> </complexType>
You can also describe a SOAP Array using a simple element as described in the SOAP 1.1 specification. The syntax for this is shown in Example 2.12, “Syntax for a SOAP array derived using an element”.
Example 2.12. Syntax for a SOAP array derived using an element
<complexType name="TypeName"> <complexContent> <restriction base="SOAP-ENC:Array"> <sequence> <element name="ElementName" type="ElementType" maxOccurs="unbounded"/> </sequence> </restriction> </complexContent> </complexType>
When using this syntax, the element’s maxOccurs
attribute must always be set to unbounded
.
2.5.3. Defining types by extension
Like most major coding languages, XML Schema allows you to create data types that inherit some of their elements from other data types. This is called defining a type by extension. For example, you could create a new type called alienInfo
, that extends the personalInfo
structure defined in Example 2.4, “A complex type” by adding a new element called planet
.
Types defined by extension have four parts:
-
The name of the type is defined by the
name
attribute of thecomplexType
element. The
complexContent
element specifies that the new type will have more than one element.NoteIf you are only adding new attributes to the complex type, you can use a
simpleContent
element.-
The type from which the new type is derived, called the base type, is specified in the
base
attribute of theextension
element. -
The new type’s elements and attributes are defined in the
extension
element, the same as they are for a regular complex type.
For example, alienInfo
is defined as shown in Example 2.13, “Type defined by extension”.
Example 2.13. Type defined by extension
<complexType name="alienInfo"> <complexContent> <extension base="xsd1:personalInfo"> <sequence> <element name="planet" type="xsd:string"/> </sequence> </extension> </complexContent> </complexType>
2.5.4. Defining types by restriction
Overview
XML Schema allows you to create new types by restricting the possible values of an XML Schema simple type. For example, you can define a simple type, SSN
, which is a string of exactly nine characters. New types defined by restricting simple types are defined using a simpleType
element.
The definition of a type by restriction requires three things:
-
The name of the new type is specified by the
name
attribute of thesimpleType
element. -
The simple type from which the new type is derived, called the base type, is specified in the
restriction
element. See the section called “Specifying the base type”. -
The rules, called facets, defining the restrictions placed on the base type are defined as children of the
restriction
element. See the section called “Defining the restrictions”.
Specifying the base type
The base type is the type that is being restricted to define the new type. It is specified using a restriction
element. The restriction
element is the only child of a simpleType
element and has one attribute, base
, that specifies the base type. The base type can be any of the XML Schema simple types.
For example, to define a new type by restricting the values of an xsd:int
you use a definition like the one shown in Example 2.14, “Using int as the base type”.
Example 2.14. Using int as the base type
<simpleType name="restrictedInt"> <restriction base="xsd:int"> ... </restriction> </simpleType>
Defining the restrictions
The rules defining the restrictions placed on the base type are called facets. Facets are elements with one attribute, value
, that defines how the facet is enforced. The available facets and their valid value
settings depend on the base type. For example, xsd:string
supports six facets, including:
-
length
-
minLength
-
maxLength
-
pattern
-
whitespace
-
enumeration
Each facet element is a child of the restriction
element.
Example
Example 2.15, “SSN simple type description” shows an example of a simple type, SSN
, which represents a social security number. The resulting type is a string of the form xxx-xx-xxxx
. <SSN>032-43-9876<SSN> is a valid value for an element of this type, but <SSN>032439876</SSN> is not.
Example 2.15. SSN simple type description
<simpleType name="SSN"> <restriction base="xsd:string"> <pattern value="\d{3}-\d{2}-\d{4}"/> </restriction> </simpleType>
2.5.5. Defining enumerated types
Overview
Enumerated types in XML Schema are a special case of definition by restriction. They are described by using the enumeration
facet which is supported by all XML Schema primitive types. As with enumerated types in most modern programming languages, a variable of this type can only have one of the specified values.
Defining an enumeration in XML Schema
The syntax for defining an enumeration is shown in Example 2.16, “Syntax for an enumeration”.
Example 2.16. Syntax for an enumeration
<simpleType name="EnumName"> <restriction base="EnumType"> <enumeration value="Case1Value"/> <enumeration value="Case2Value"/> ... <enumeration value="CaseNValue"/> </restriction> </simpleType>
EnumName specifies the name of the enumeration type. EnumType specifies the type of the case values. CaseNValue, where N is any number one or greater, specifies the value for each specific case of the enumeration. An enumerated type can have any number of case values, but because it is derived from a simple type, only one of the case values is valid at a time.
Example
For example, an XML document with an element defined by the enumeration widgetSize
, shown in Example 2.17, “widgetSize enumeration”, would be valid if it contained <widgetSize>big</widgetSize>, but it would not be valid if it contained <widgetSize>big,mungo</widgetSize>.
Example 2.17. widgetSize enumeration
<simpleType name="widgetSize"> <restriction base="xsd:string"> <enumeration value="big"/> <enumeration value="large"/> <enumeration value="mungo"/> </restriction> </simpleType>
2.6. Defining elements
Elements in XML Schema represent an instance of an element in an XML document generated from the schema. The most basic element consists of a single element
element. Like the element
element used to define the members of a complex type, they have three attributes:
-
name
— A required attribute that specifies the name of the element as it appears in an XML document. -
type
— Specifies the type of the element. The type can be any XML Schema primitive type or any named complex type defined in the contract. This attribute can be omitted if the type has an in-line definition. -
nillable
— Specifies whether an element can be omitted from a document entirely. Ifnillable
is set totrue
, the element can be omitted from any document generated using the schema.
An element can also have an in-line type definition. In-line types are specified using either a complexType
element or a simpleType
element. Once you specify if the type of data is complex or simple, you can define any type of data needed using the tools available for each type of data. In-line type definitions are discouraged because they are not reusable.
Chapter 3. Defining Logical Messages Used by a Service
Abstract
A service is defined by the messages exchanged when its operations are invoked. In a WSDL contract these messages are defined using message
element. The messages are made up of one or more parts that are defined using part
elements.
Overview
A service’s operations are defined by specifying the logical messages that are exchanged when an operation is invoked. These logical messages define the data that is passed over a network as an XML document. They contain all of the parameters that are a part of a method invocation. Logical messages are defined using the message
element in your contracts. Each logical message consists of one or more parts, defined in part
elements.
While your messages can list each parameter as a separate part, the recommended practice is to use only a single part that encapsulates the data needed for the operation.
Messages and parameter lists
Each operation exposed by a service can have only one input message and one output message. The input message defines all of the information the service receives when the operation is invoked. The output message defines all of the data that the service returns when the operation is completed. Fault messages define the data that the service returns when an error occurs.
In addition, each operation can have any number of fault messages. The fault messages define the data that is returned when the service encounters an error. These messages usually have only one part that provides enough information for the consumer to understand the error.
Message design for integrating with legacy systems
If you are defining an existing application as a service, you must ensure that each parameter used by the method implementing the operation is represented in a message. You must also ensure that the return value is included in the operation’s output message.
One approach to defining your messages is RPC style. When using RPC style, you define the messages using one part for each parameter in the method’s parameter list. Each message part is based on a type defined in the types
element of the contract. Your input message contains one part for each input parameter in the method. Your output message contains one part for each output parameter, plus a part to represent the return value, if needed. If a parameter is both an input and an output parameter, it is listed as a part for both the input message and the output message.
RPC style message definition is useful when service enabling legacy systems that use transports such as Tibco or CORBA. These systems are designed around procedures and methods. As such, they are easiest to model using messages that resemble the parameter lists for the operation being invoked. RPC style also makes a cleaner mapping between the service and the application it is exposing.
Message design for SOAP services
While RPC style is useful for modeling existing systems, the service’s community strongly favors the wrapped document style. In wrapped document style, each message has a single part. The message’s part references a wrapper element defined in the types
element of the contract. The wrapper element has the following characteristics:
- It is a complex type containing a sequence of elements. For more information see Section 2.5, “Defining complex data types”.
If it is a wrapper for an input message:
- It has one element for each of the method’s input parameters.
- Its name is the same as the name of the operation with which it is associated.
If it is a wrapper for an output message:
- It has one element for each of the method’s output parameters and one element for each of the method’s inout parameters.
- Its first element represents the method’s return parameter.
-
Its name would be generated by appending
Response
to the name of the operation with which the wrapper is associated.
Message naming
Each message in a contract must have a unique name within its namespace. It is recommended that you use the following naming conventions:
- Messages should only be used by a single operation.
-
Input message names are formed by appending
Request
to the name of the operation. -
Output message names are formed by appending
Response
to the name of the operation. - Fault message names should represent the reason for the fault.
Message parts
Message parts are the formal data units of the logical message. Each part is defined using a part
element, and is identified by a name
attribute and either a type
attribute or an element
attribute that specifies its data type. The data type attributes are listed in Table 3.1, “Part data type attributes”.
Attribute | Description |
---|---|
The data type of the part is defined by an element called elem_name. | |
The data type of the part is defined by a type called type_name. |
Messages are allowed to reuse part names. For instance, if a method has a parameter, foo
, that is passed by reference or is an in/out, it can be a part in both the request message and the response message, as shown in Example 3.1, “Reused part”.
Example 3.1. Reused part
<message name="fooRequest"> <part name="foo" type="xsd:int"/> <message> <message name="fooReply"> <part name="foo" type="xsd:int"/> <message>
Example
For example, imagine you had a server that stored personal information and provided a method that returned an employee’s data based on the employee’s ID number. The method signature for looking up the data is similar to Example 3.2, “personalInfo lookup method”.
Example 3.2. personalInfo lookup method
personalInfo lookup(long empId)
This method signature can be mapped to the RPC style WSDL fragment shown in Example 3.3, “RPC WSDL message definitions”.
Example 3.3. RPC WSDL message definitions
<message name="personalLookupRequest"> <part name="empId" type="xsd:int"/> <message/> <message name="personalLookupResponse> <part name="return" element="xsd1:personalInfo"/> <message/>
It can also be mapped to the wrapped document style WSDL fragment shown in Example 3.4, “Wrapped document WSDL message definitions”.
Example 3.4. Wrapped document WSDL message definitions
<wsdl:types> <xsd:schema ... > ... <element name="personalLookup"> <complexType> <sequence> <element name="empID" type="xsd:int" /> </sequence> </complexType> </element> <element name="personalLookupResponse"> <complexType> <sequence> <element name="return" type="personalInfo" /> </sequence> </complexType> </element> </schema> </types> <wsdl:message name="personalLookupRequest"> <wsdl:part name="empId" element="xsd1:personalLookup"/> <message/> <wsdl:message name="personalLookupResponse"> <wsdl:part name="return" element="xsd1:personalLookupResponse"/> <message/>
Chapter 4. Defining Your Logical Interfaces
Abstract
Logical service interfaces are defined using the portType
element.
Overview
Logical service interfaces are defined using the WSDL portType
element. The portType
element is a collection of abstract operation definitions. Each operation is defined by the input, output, and fault messages used to complete the transaction the operation represents. When code is generated to implement the service interface defined by a portType
element, each operation is converted into a method containing the parameters defined by the input, output, and fault messages specified in the contract.
Process
To define a logical interface in a WSDL contract you must do the following:
-
Create a
portType
element to contain the interface definition and give it a unique name. See the section called “Port types”. -
Create an
operation
element for each operation defined in the interface. See the section called “Operations”. - For each operation, specify the messages used to represent the operation’s parameter list, return type, and exceptions. See the section called “Operation messages”.
Port types
A WSDL portType
element is the root element in a logical interface definition. While many Web service implementations map portType
elements directly to generated implementation objects, a logical interface definition does not specify the exact functionality provided by the the implemented service. For example, a logical interface named ticketSystem can result in an implementation that either sells concert tickets or issues parking tickets.
The portType
element is the unit of a WSDL document that is mapped into a binding to define the physical data used by an endpoint exposing the defined service.
Each portType
element in a WSDL document must have a unique name, which is specified using the name
attribute, and is made up of a collection of operations, which are described in operation
elements. A WSDL document can describe any number of port types.
Operations
Logical operations, defined using WSDL operation
elements, define the interaction between two endpoints. For example, a request for a checking account balance and an order for a gross of widgets can both be defined as operations.
Each operation defined within a portType
element must have a unique name, specified using the name
attribute. The name
attribute is required to define an operation.
Operation messages
Logical operations are made up of a set of elements representing the logical messages communicated between the endpoints to execute the operation. The elements that can describe an operation are listed in Table 4.1, “Operation message elements”.
Element | Description |
---|---|
| Specifies the message the client endpoint sends to the service provider when a request is made. The parts of this message correspond to the input parameters of the operation. |
| Specifies the message that the service provider sends to the client endpoint in response to a request. The parts of this message correspond to any operation parameters that can be changed by the service provider, such as values passed by reference. This includes the return value of the operation. |
| Specifies a message used to communicate an error condition between the endpoints. |
An operation is required to have at least one input
or one output
element. An operation can have both input
and output
elements, but it can only have one of each. Operations are not required to have any fault
elements, but can, if required, have any number of fault
elements.
The elements have the two attributes listed in Table 4.2, “Attributes of the input and output elements”.
Attribute | Description |
---|---|
| Identifies the message so it can be referenced when mapping the operation to a concrete data format. The name must be unique within the enclosing port type. |
|
Specifies the abstract message that describes the data being sent or received. The value of the |
It is not necessary to specify the name
attribute for all input
and output
elements; WSDL provides a default naming scheme based on the enclosing operation’s name. If only one element is used in the operation, the element name defaults to the name of the operation. If both an input
and an output
element are used, the element name defaults to the name of the operation with either Request
or Response
respectively appended to the name.
Return values
Because the operation
element is an abstract definition of the data passed during an operation, WSDL does not provide for return values to be specified for an operation. If a method returns a value it will be mapped into the output
element as the last part of that message.
Example
For example, you might have an interface similar to the one shown in Example 4.1, “personalInfo lookup interface”.
Example 4.1. personalInfo lookup interface
interface personalInfoLookup { personalInfo lookup(in int empID) raises(idNotFound); }
This interface can be mapped to the port type in Example 4.2, “personalInfo lookup port type”.
Example 4.2. personalInfo lookup port type
<message name="personalLookupRequest"> <part name="empId" element="xsd1:personalLookup"/> <message/> <message name="personalLookupResponse"> <part name="return" element="xsd1:personalLookupResponse"/> <message/> <message name="idNotFoundException"> <part name="exception" element="xsd1:idNotFound"/> <message/> <portType name="personalInfoLookup"> <operation name="lookup"> <input name="empID" message="tns:personalLookupRequest"/> <output name="return" message="tns:personalLookupResponse"/> <fault name="exception" message="tns:idNotFoundException"/> </operation> </portType>
Part II. Web Services Bindings
This part describes how to add Apache CXF bindings to a WSDL document.
Chapter 5. Understanding Bindings in WSDL
Abstract
Bindings map the logical messages used to define a service into a concrete payload format that can be transmitted and received by an endpoint.
Overview
Bindings provide a bridge between the logical messages used by a service to a concrete data format that an endpoint uses in the physical world. They describe how the logical messages are mapped into a payload format that is used on the wire by an endpoint. It is within the bindings that details such as parameter order, concrete data types, and return values are specified. For example, the parts of a message can be reordered in a binding to reflect the order required by an RPC call. Depending on the binding type, you can also identify which of the message parts, if any, represent the return type of a method.
Port types and bindings
Port types and bindings are directly related. A port type is an abstract definition of a set of interactions between two logical services. A binding is a concrete definition of how the messages used to implement the logical services will be instantiated in the physical world. Each binding is then associated with a set of network details that finish the definition of one endpoint that exposes the logical service defined by the port type.
To ensure that an endpoint defines only a single service, WSDL requires that a binding can only represent a single port type. For example, if you had a contract with two port types, you could not write a single binding that mapped both of them into a concrete data format. You would need two bindings.
However, WSDL allows for a port type to be mapped to several bindings. For example, if your contract had a single port type, you could map it into two or more bindings. Each binding could alter how the parts of the message are mapped or they could specify entirely different payload formats for the message.
The WSDL elements
Bindings are defined in a contract using the WSDL binding
element. The binding element consists of attributes like, name
, that specifies a unique name for the binding and type
that provides reference to PortType. The value of this attribute is used to associate the binding with an endpoint as discussed in Chapter 4, Defining Your Logical Interfaces.
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.
Adding to a contract
Apache CXF provides command line tools that can generate bindings for predefined service interfaces.
The tools will add the proper elements to your contract for you. However, it is recommended that you have some knowledge of how the different types of bindings work.
You can also add a binding to a contract using any text editor. When hand editing a contract, you are responsible for ensuring that the contract is valid.
Supported bindings
Apache CXF supports the following bindings:
- SOAP 1.1
- SOAP 1.2
- CORBA
- Pure XML
Chapter 6. Using SOAP 1.1 Messages
Abstract
Apache CXF provides a tool to generate a SOAP 1.1 binding which does not use any SOAP headers. However, you can add SOAP headers to your binding using any text or XML editor.
6.1. Adding a SOAP 1.1 Binding
Using wsdl2soap
To generate a SOAP 1.1 binding using wsdl2soap
use the following command: wsdl2soap
-iport-type-name-bbinding-name-doutput-directory-ooutput-file-nsoap-body-namespace-style (document/rpc)-use (literal/encoded)-v-verbose-quietwsdlurl
To use wsdl2soap
you will need to download the Apache CXF distribution.
The command has the following options:
Option | Interpretation |
---|---|
|
Specifies the |
wsdlurl |
The path and name of the WSDL file containing the |
The tool has the following optional arguments:
Option | Interpretation |
---|---|
| Specifies the name of the generated SOAP binding. |
| Specifies the directory to place the generated WSDL file. |
| Specifies the name of the generated WSDL file. |
| Specifies the SOAP body namespace when the style is RPC. |
| Specifies the encoding style (document or RPC) to use in the SOAP binding. The default is document. |
| Specifies the binding use (encoded or literal) to use in the SOAP binding. The default is literal. |
| Displays the version number for the tool. |
| Displays comments during the code generation process. |
| Suppresses 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.
wsdl2soap
does not support the generation of document/encoded
SOAP bindings.
Example
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 6.1, “Ordering System Interface”.
Example 6.1. Ordering System Interface
<?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/"> <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> <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> ... </definitions>
The SOAP binding generated for orderWidgets
is shown in Example 6.2, “SOAP 1.1 Binding for orderWidgets
”.
Example 6.2. SOAP 1.1 Binding for orderWidgets
<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"/> </input> <output name="bill"> <soap:body use="literal"/> </output> <fault name="sizeFault"> <soap:body use="literal"/> </fault> </operation> </binding>
This binding specifies that messages are sent using the document/literal
message style.
6.2. Adding SOAP Headers to a SOAP 1.1 Binding
Overview
SOAP headers are defined by adding soap:header
elements to your default SOAP 1.1 binding. The soap:header
element is an optional child of the input
, output
, and fault
elements of the binding. The SOAP header becomes part of the parent message. A SOAP header is defined by specifying a message and a message part. Each SOAP header can only contain one message part, but you can insert as many SOAP headers as needed.
Syntax
The syntax for defining a SOAP header is shown in Example 6.3, “SOAP Header Syntax”. 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.
Example 6.3. SOAP Header Syntax
<binding name="headwig"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="weave"> <soap:operation soapAction="" style="document"/> <input name="grain"> <soap:body ... /> <soap:header message="QName" part="partName"/> </input> ... </binding>
As well as the mandatory message
and part
attributes, soap:header
also supports the namespace
, the use
, and the encodingStyle
attributes. These attributes function the same for soap:header
as they do for soap:body
.
Splitting messages between body and header
The message part inserted into the SOAP header can be any valid message part from the contract. It can even be a part from the parent message which is being used as the SOAP body. Because it is unlikely that you would want to send information twice in the same message, the SOAP binding provides a means for specifying the message parts that are inserted into the SOAP body.
The soap:body
element has an optional attribute, parts
, that takes a space delimited list of part names. When parts
is defined, only the message parts listed are inserted into the SOAP body. You can then insert the remaining parts into the SOAP header.
When you define a SOAP header using parts of the parent message, Apache CXF automatically fills in the SOAP headers for you.
Example
Example 6.4, “SOAP 1.1 Binding with a SOAP Header” shows a modified version of the orderWidgets
service shown in Example 6.1, “Ordering System Interface”. 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 6.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 also modify Example 6.4, “SOAP 1.1 Binding with a SOAP Header” so that the header value is a part of the input and output messages.
Chapter 7. Using SOAP 1.2 Messages
Abstract
Apache CXF provides tools to generate a SOAP 1.2 binding which does not use any SOAP headers. You can add SOAP headers to your binding using any text or XML editor.
7.1. Adding a SOAP 1.2 Binding to a WSDL Document
Using wsdl2soap
To use wsdl2soap you will need to download the Apache CXF distribution.
To generate a SOAP 1.2 binding using wsdl2soap
use the following command: wsdl2soap
-iport-type-name-bbinding-name-soap12-doutput-directory-ooutput-file-nsoap-body-namespace-style (document/rpc)-use (literal/encoded)-v-verbose-quietwsdlurl The tool has the following required arguments:
Option | Interpretation |
---|---|
|
Specifies the |
| Specifies that the generated binding uses SOAP 1.2. |
wsdlurl |
The path and name of the WSDL file containing the |
The tool has the following optional arguments:
Option | Interpretation |
---|---|
| Specifies the name of the generated SOAP binding. |
| Specifies that the generated binding will use SOAP 1.2. |
| Specifies the directory to place the generated WSDL file. |
| Specifies the name of the generated WSDL file. |
| Specifies the SOAP body namespace when the style is RPC. |
| Specifies the encoding style (document or RPC) to use in the SOAP binding. The default is document. |
| Specifies the binding use (encoded or literal) to use in the SOAP binding. The default is literal. |
| Displays the version number for the tool. |
| Displays comments during the code generation process. |
| Suppresses 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.
wsdl2soap
does not support the generation of document/encoded
SOAP 1.2 bindings.
Example
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 7.1, “Ordering System Interface”.
Example 7.1. Ordering System Interface
<?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/"> <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> <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> ... </definitions>
The SOAP binding generated for orderWidgets is shown in Example 7.2, “SOAP 1.2 Binding for orderWidgets”.
Example 7.2. SOAP 1.2 Binding for orderWidgets
<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"/> </input> <output name="bill"> <wsoap12:body use="literal"/> </output> <fault name="sizeFault"> <soap12:body use="literal"/> </fault> </operation> </binding>
This binding specifies that messages are sent using the document/literal
message style.
7.2. Adding Headers to a SOAP 1.2 Message
Overview
SOAP message headers are defined by adding soap12:header
elements to your SOAP 1.2 message. The soap12:header
element is an optional child of the input
, output
, and fault
elements of the binding. The SOAP header becomes part of the parent message. A SOAP header is defined by specifying a message and a message part. Each SOAP header can only contain one message part, but you can insert as many headers as needed.
Syntax
The syntax for defining a SOAP header is shown in Example 7.3, “SOAP Header Syntax”.
Example 7.3. SOAP Header Syntax
<binding name="headwig"> <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="weave"> <soap12:operation soapAction="" style="documment"/> <input name="grain"> <soap12:body ... /> <soap12:header message="QName" part="partName" use="literal|encoded" encodingStyle="encodingURI" namespace="namespaceURI" /> </input> ... </binding>
The soap12:header
element’s attributes are described in Table 7.1, “soap12:header
Attributes”.
Attribute | Description |
---|---|
A required attribute specifying the qualified name of the message from which the part being inserted into the header is taken. | |
A required attribute specifying the name of the message part inserted into the SOAP header. | |
Specifies if the message parts are to be encoded using encoding rules. If set to | |
Specifies the encoding rules used to construct the message. | |
Defines the namespace to be assigned to the header element serialized with |
Splitting messages between body and header
The message part inserted into the SOAP header can be any valid message part from the contract. It can even be a part from the parent message which is being used as the SOAP body. Because it is unlikely that you would send information twice in the same message, the SOAP 1.2 binding provides a means for specifying the message parts that are inserted into the SOAP body.
The soap12:body
element has an optional attribute, parts
, that takes a space delimited list of part names. When parts
is defined, only the message parts listed are inserted into the body of the SOAP 1.2 message. You can then insert the remaining parts into the message’s header.
When you define a SOAP header using parts of the parent message, Apache CXF automatically fills in the SOAP headers for you.
Example
Example 7.4, “SOAP 1.2 Binding with a SOAP Header” shows a modified version of the orderWidgets
service shown in Example 7.1, “Ordering System Interface”. 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 7.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 7.4, “SOAP 1.2 Binding with a SOAP Header” so that the header value is a part of the input and output messages, as shown in Example 7.5, “SOAP 1.2 Binding for orderWidgets with a SOAP Header”. 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 7.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>
Chapter 8. Sending Binary Data Using SOAP with Attachments
Abstract
SOAP attachments provide a mechanism for sending binary data as part of a SOAP message. Using SOAP with attachments requires that you define your SOAP messages as MIME multipart messages.
Overview
SOAP messages generally do not carry binary data. However, the W3C SOAP 1.1 specification allows for using MIME multipart/related messages to send binary data in SOAP messages. This technique is called using SOAP with attachments. SOAP attachments are defined in the W3C’s SOAP Messages with Attachments Note.
Namespace
The WSDL extensions used to define the MIME multipart/related messages are defined in the namespace http://schemas.xmlsoap.org/wsdl/mime/.
In the discussion that follows, it is assumed that this namespace is prefixed with mime
. The entry in the WSDL definitions
element to set this up is shown in Example 8.1, “MIME Namespace Specification in a Contract”.
Example 8.1. MIME Namespace Specification in a Contract
xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/"
Changing the message binding
In a default SOAP binding, the first child element of the input
, output
, and fault
elements is a soap:body
element describing the body of the SOAP message representing the data. When using SOAP with attachments, the soap:body
element is replaced with a mime:multipartRelated
element.
WSDL does not support using mime:multipartRelated
for fault
messages.
The mime:multipartRelated
element tells Apache CXF that the message body is a multipart message that potentially contains binary data. The contents of the element define the parts of the message and their contents. mime:multipartRelated
elements contain one or more mime:part
elements that describe the individual parts of the message.
The first mime:part
element must contain the soap:body
element that would normally appear in a default SOAP binding. The remaining mime:part
elements define the attachments that are being sent in the message.
Describing a MIME multipart message
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:
-
Inside the
input
oroutput
message you are sending as a MIME multipart message, add amime:mulipartRelated
element as the first child element of the enclosing message. -
Add a
mime:part
child element to themime:multipartRelated
element and set itsname
attribute to a unique string. Add a
soap:body
element as the child of themime:part
element and set its attributes appropriately.NoteIf 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.-
Add another
mime:part
child element to themime:multipartReleated
element and set itsname
attribute to a unique string. Add a
mime:content
child element to themime: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:Table 8.1. mime:content Attributes Attribute Description + Specifies the name of the WSDL message
part
, from the parent message definition, that is used as the content of this part of the MIME multipart message being placed on the wire.+
The MIME type of the data in this message part. MIME types are defined as a type and a subtype using the syntax type
/
subtype.+
There are a number of predefined MIME types such as
image/jpeg
andtext/plain
. The MIME types are maintained by the Internet Assigned Numbers Authority (IANA) and 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.+
- For each additional MIME part, repeat steps [i303819] and [i303821].
Example
Example 8.2, “Contract using SOAP with Attachments” 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 8.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>
Chapter 9. Sending Binary Data with SOAP MTOM
Abstract
SOAP Message Transmission Optimization Mechanism (MTOM) replaces SOAP with attachments as a mechanism for sending binary data as part of an XML message. Using MTOM with Apache CXF requires adding the correct schema types to a service’s contract and enabling the MTOM optimizations.
9.1. Overview of MTOM
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:
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.
Enable the runtime’s MTOM support.
This can be done either programmatically or through configuration.
Develop a
DataHandler
for the data being passed as an attachment.NoteDeveloping
DataHandler
s is beyond the scope of this book.
9.2. Annotating Data Types to use MTOM
Overview
In WSDL, when defining a data type for passing along a block of binary data, such as an image file or a sound file, you define the element for the data to be of type xsd:base64Binary
. By default, any element of type xsd:base64Binary
results in the generation of a byte[]
which can be serialized using MTOM. However, the default behavior of the code generators does not take full advantage of the serialization.
In order to fully take advantage of MTOM you must add annotations to either your service’s WSDL document or the JAXB class that implements the binary data structure. Adding the annotations to the WSDL document forces the code generators to generate streaming data handlers for the binary data. Annotating the JAXB class involves specifying the proper content types and might also involve changing the type specification of the field containing the binary data.
WSDL first
Example 9.1, “Message for MTOM” 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 9.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.
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.
For most uses you specify application/octet-stream
.
Example 9.2, “Binary Data for MTOM” shows how you can modify xRayType
from Example 9.1, “Message for MTOM” for using MTOM.
Example 9.2. Binary Data for MTOM
... <types> <schema targetNamespace="http://mediStor.org/types/" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:xmime="http://www.w3.org/2005/05/xmlmime"> <complexType name="xRayType"> <sequence> <element name="patientName" type="xsd:string" /> <element name="patientNumber" type="xsd:int" /> <element name="imageData" type="xsd:base64Binary" xmime:expectedContentTypes="application/octet-stream"/> </sequence> </complexType> <element name="xRay" type="xsd1:xRayType" /> </schema> </types> ...
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.
You do not need to change the binding
element to use MTOM. The runtime makes the appropriate changes when the data is sent.
Java first
If you are doing Java first development you can make your JAXB class MTOM ready by doing the following:
- Make sure the field holding the binary data is a DataHandler.
-
Add the
@XmlMimeType()
annotation to the field containing the data you want to stream as an MTOM attachment.
Example 9.3, “JAXB Class for MTOM” shows a JAXB class annotated for using MTOM.
Example 9.3. JAXB Class for MTOM
@XmlType
public class XRayType {
protected String patientName;
protected int patientNumber;
@XmlMimeType("application/octet-stream")
protected DataHandler imageData;
...
}
9.3. Enabling MTOM
By default the Apache CXF 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.
9.3.1. Using JAX-WS APIs
Overview
Both service providers and consumers must have the MTOM optimizations enabled. The JAX-WS APIs offer different mechanisms for each type of endpoint.
Service provider
If you published your service provider using the JAX-WS APIs you enable the runtime’s MTOM support as follows:
Access the
Endpoint
object for your published service.The easiest way to access the
Endpoint
object is when you publish the endpoint. For more information see Chapter 31, Publishing a Service.Get the SOAP binding from the
Endpoint
using itsgetBinding()
method, as shown in Example 9.4, “Getting the SOAP Binding from an Endpoint”.Example 9.4. Getting the SOAP Binding from an Endpoint
// Endpoint ep is declared previously SOAPBinding binding = (SOAPBinding)ep.getBinding();
You must cast the returned binding object to a
SOAPBinding
object to access the MTOM property.Set the binding’s MTOM enabled property to
true
using the binding’ssetMTOMEnabled()
method, as shown in Example 9.5, “Setting a Service Provider’s MTOM Enabled Property”.Example 9.5. Setting a Service Provider’s MTOM Enabled Property
binding.setMTOMEnabled(true);
Consumer
To MTOM enable a JAX-WS consumer you must do the following:
Cast the consumer’s proxy to a
BindingProvider
object.For information on getting a consumer proxy see Chapter 25, Developing a Consumer Without a WSDL Contract or Chapter 28, Developing a Consumer From a WSDL Contract.
Get the SOAP binding from the
BindingProvider
using itsgetBinding()
method, as shown in Example 9.6, “Getting a SOAP Binding from aBindingProvider
”.Example 9.6. Getting a SOAP Binding from a
BindingProvider
// BindingProvider bp declared previously SOAPBinding binding = (SOAPBinding)bp.getBinding();
Set the bindings MTOM enabled property to
true
using the binding’ssetMTOMEnabled()
method, as shown in Example 9.7, “Setting a Consumer’s MTOM Enabled Property”.Example 9.7. Setting a Consumer’s MTOM Enabled Property
binding.setMTOMEnabled(true);
9.3.2. Using configuration
Overview
If you publish your service using XML, such as when deploying to a container, you can enable your endpoint’s MTOM support in the endpoint’s configuration file. For more information on configuring endpoint’s see Part IV, “Configuring Web Service Endpoints”.
Procedure
The MTOM property is set inside the jaxws:endpoint
element for your endpoint. To enable MTOM do the following:
-
Add a
jaxws:property
child element to the endpoint’sjaxws:endpoint
element. -
Add a
entry
child element to thejaxws:property
element. -
Set the
entry
element’skey
attribute tomtom-enabled
. -
Set the
entry
element’svalue
attribute totrue
.
Example
Example 9.8, “Configuration for Enabling MTOM” shows an endpoint that is MTOM enabled.
Example 9.8. Configuration for Enabling MTOM
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schema/jaxws.xsd"> <jaxws:endpoint id="xRayStorage" implementor="demo.spring.xRayStorImpl" address="http://localhost/xRayStorage"> <jaxws:properties> <entry key="mtom-enabled" value="true"/> </jaxws:properties> </jaxws:endpoint> </beans>
Chapter 10. Using XML Documents
Abstract
The pure XML payload format provides an alternative to the SOAP binding by allowing services to exchange data using straight XML documents without the overhead of a SOAP envelope.
XML binding namespace
The extensions used to describe XML format bindings are defined in the namespace http://cxf.apache.org/bindings/xformat. Apache CXF tools use the prefix xformat
to represent the XML binding extensions. Add the following line to your contracts:
xmlns:xformat="http://cxf.apache.org/bindings/xformat"
Hand editing
To map an interface to a pure XML payload format do the following:
- Add the namespace declaration to include the extensions defining the XML binding. See the section called “XML binding namespace”.
-
Add a standard WSDL
binding
element to your contract to hold the XML binding, give the binding a uniquename
, and specify the name of the WSDLportType
element that represents the interface being bound. -
Add an
xformat:binding
child element to thebinding
element to identify that the messages are being handled as pure XML documents without SOAP envelopes. -
Optionally, set the
xformat:binding
element’srootNode
attribute to a valid QName. For more information on the effect of therootNode
attribute see the section called “XML messages on the wire”. -
For each operation defined in the bound interface, add a standard WSDL
operation
element to hold the binding information for the operation’s messages. For each operation added to the binding, add the
input
,output
, andfault
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.
-
Optionally add an
xformat:body
element with a validrootNode
attribute to the addedinput
,output
, andfault
elements to override the value ofrootNode
set at the binding level.
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.
XML messages on the wire
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-Apache CXF participants that receive the XML documents understand the messages generated by Apache CXF.
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 Apache CXF. When the rootNode
attribute is not set, Apache CXF 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 10.1, “Valid XML Binding Message” would generate an XML document with the root element lineNumber
.
Example 10.1. Valid XML Binding Message
<type ... > ... <element name="operatorID" type="xsd:int"/> ... </types> <message name="operator"> <part name="lineNumber" element="ns1:operatorID"/> </message>
For messages with one part, Apache CXF will always generate a valid XML document even if the rootNode
attribute is not set. However, the message in Example 10.2, “Invalid XML Binding Message” would generate an invalid XML document.
Example 10.2. Invalid XML Binding Message
<types> ... <element name="pairName" type="xsd:string"/> <element name="entryNum" type="xsd:int"/> ... </types> <message name="matildas"> <part name="dancing" element="ns1:pairName"/> <part name="number" element="ns1:entryNum"/> </message>
Without the rootNode
attribute specified in the XML binding, Apache CXF will generate an XML document similar to Example 10.3, “Invalid XML Document” for the message defined in Example 10.2, “Invalid XML Binding Message”. The generated XML document is invalid because it has two root elements: pairName
and entryNum
.
Example 10.3. Invalid XML Document
<pairName> Fred&Linda </pairName> <entryNum> 123 </entryNum>
If you set the rootNode
attribute, as shown in Example 10.4, “XML Binding with rootNode set” Apache CXF 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.
Example 10.4. XML Binding with rootNode set
<portType name="danceParty"> <operation name="register"> <input message="tns:matildas" name="contestant"/> </operation> </portType> <binding name="matildaXMLBinding" type="tns:dancingMatildas"> <xmlformat:binding rootNode="entrants"/> <operation name="register"> <input name="contestant"/> <output name="entered"/> </binding>
An XML document generated from the input message would be similar to Example 10.5, “XML Document generated using the rootNode attribute”. Notice that the XML document now only has one root element.
Example 10.5. XML Document generated using the rootNode attribute
<entrants> <pairName> Fred&Linda <entryNum> 123 </entryNum> </entrants>
Overriding the binding’s rootNode attribute setting
You can also set the rootNode
attribute for each individual message, or override the global setting for a particular message, by using the xformat:body
element inside of the message binding. For example, if you wanted the output message defined in Example 10.4, “XML Binding with rootNode set” to have a different root element from the input message, you could override the binding’s root element as shown in Example 10.6, “Using xformat:body
”.
Example 10.6. Using xformat:body
<binding name="matildaXMLBinding" type="tns:dancingMatildas"> <xmlformat:binding rootNode="entrants"/> <operation name="register"> <input name="contestant"/> <output name="entered"> <xformat:body rootNode="entryStatus" /> </output> </operation> </binding>
Part III. Web Services Transports
This part describes how to add Apache CXF transports to a WSDL document.
Chapter 11. Understanding How Endpoints are Defined in WSDL
Abstract
Endpoints represent an instantiated service. They are defined by combining a binding and the networking details used to expose the endpoint.
Overview
An endpoint can be thought of as a physical manifestation of a service. It combines a binding, which specifies the physical representation of the logical data used by a service, and a set of networking details that define the physical connection details used to make the service contactable by other endpoints.
CXF providers are servers for CXF consumers, which correspond to clients. If you are using the CXF (camel-cxf
) component as the starting endpoint in a route, then the endpoint is both a Camel consumer and a CXF provider. If you are using the Camel CXF component, as an ending endpoint in a route, then the endpoint is both a Camel producer and a CXF consumer.
Endpoints and services
In the same way a binding can only map a single interface, an endpoint can only map to a single service. However, a service can be manifested by any number of endpoints. For example, you could define a ticket selling service that was manifested by four different endpoints. However, you could not have a single endpoint that manifested both a ticket selling service and a widget selling service.
The WSDL elements
Endpoints are defined in a contract using a combination of the WSDL service
element and the WSDL port
element. The service
element is a collection of related port
elements. The port
elements define the actual endpoints.
The WSDL service
element has a single attribute, name
, that specifies a unique name. The service
element is used as the parent element of a collection of related port
elements. WSDL makes no specification about how the port
elements are related. You can associate the port
elements in any manner you see fit.
The WSDL port
element has a has a binding
attribute, that specifies the binding used by the endpoint and is a reference to the wsdl:binding
element. It also includes the name
attribute, which is a mandatory attribute that provides a unique name among all ports. The port
element is the parent element of the elements that specify the actual transport details used by the endpoint. The elements used to specify the transport details are discussed in the following sections.
Adding endpoints to a contract
Apache CXF provides command line tools that can generated endpoints for predefined service interface and binding combinations.
The tools will add the proper elements to your contract for you. However, it is recommended that you have some knowledge of how the different transports used in defining an endpoint work.
You can also add an endpoint to a contract using any text editor. When you hand edit a contract, you are responsible for ensuring that the contract is valid.
Supported transports
Endpoint definitions are built using extensions defined for each of the transports Apache CXF supports. This includes the following transports:
- HTTP
- CORBA
- Java Messaging Service
Chapter 12. Using HTTP
Abstract
HTTP is the underlying transport for the Web. It provides a standardized, robust, and flexible platform for communicating between endpoints. Because of these factors it is the assumed transport for most WS-* specifications and is integral to RESTful architectures.
12.1. Adding a Basic HTTP Endpoint
Alternative HTTP runtimes
Apache CXF supports the following alternative HTTP runtime implementations:
- Undertow, which is described in detail in Section 12.4, “Configuring the Undertow Runtime”.
- Netty, which is described in detail in Section 12.5, “Configuring the Netty Runtime”.
Netty HTTP URL
Normally, a HTTP endpoint uses whichever HTTP runtime is included on the classpath (either Undertow or Netty). If both the Undertow runtime and Netty runtime are included on the classpath, however, you need to specify explicitly when you want to use the Netty runtime, because the Undertow runtime will be used by default.
In the case where more than one HTTP runtime is available on the classpath, you can select the Undertow runtime by specifying the endpoint URL to have the following format:
netty://http://RestOfURL
Payload types
There are three ways of specifying an HTTP endpoint’s address depending on the payload format you are using.
-
SOAP 1.1 uses the standardized
soap:address
element. -
SOAP 1.2 uses the
soap12:address
element. -
All other payload formats use the
http:address element.
From Camel 2.16.0 release, Apache Camel CXF Payload supports stream cache out of box.
SOAP 1.1
When you are sending SOAP 1.1 messages over HTTP you must use the SOAP 1.1 address
element to specify the endpoint’s address. It has one attribute, location
, that specifies the endpoint’s address as a URL. The SOAP 1.1 address
element is defined in the namespace http://schemas.xmlsoap.org/wsdl/soap/.
Example 12.1, “SOAP 1.1 Port Element” shows a port
element used to send SOAP 1.1 messages over HTTP.
Example 12.1. SOAP 1.1 Port Element
<definitions ... xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" ...> ... <service name="SOAP11Service"> <port binding="SOAP11Binding" name="SOAP11Port"> <soap:address location="http://artie.com/index.xml"> </port> </service> ... <definitions>
SOAP 1.2
When you are sending SOAP 1.2 messages over HTTP you must use the SOAP 1.2 address
element to specify the endpoint’s address. It has one attribute, location
, that specifies the endpoint’s address as a URL. The SOAP 1.2 address
element is defined in the namespace http://schemas.xmlsoap.org/wsdl/soap12/.
Example 12.2, “SOAP 1.2 Port Element” shows a port
element used to send SOAP 1.2 messages over HTTP.
Example 12.2. SOAP 1.2 Port Element
<definitions ... xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" ... > <service name="SOAP12Service"> <port binding="SOAP12Binding" name="SOAP12Port"> <soap12:address location="http://artie.com/index.xml"> </port> </service> ... </definitions>
Other messages types
When your messages are mapped to any payload format other than SOAP you must use the HTTP address
element to specify the endpoint’s address. It has one attribute, location
, that specifies the endpoint’s address as a URL. The HTTP address
element is defined in the namespace http://schemas.xmlsoap.org/wsdl/http/.
Example 12.3, “HTTP Port Element” shows a port
element used to send an XML message.
Example 12.3. HTTP Port Element
<definitions ... xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" ... > <service name="HTTPService"> <port binding="HTTPBinding" name="HTTPPort"> <http:address location="http://artie.com/index.xml"> </port> </service> ... </definitions>
12.2. Configuring a Consumer
12.2.1. Mechanisms for HTTP Consumer Endpoints
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:
12.2.2. Using Configuration
Namespace
The elements used to configure an HTTP consumer endpoint are defined in the namespace http://cxf.apache.org/transports/http/configuration. It is commonly referred to using the prefix http-conf
. In order to use the HTTP configuration elements you must add the lines shown in Example 12.4, “HTTP Consumer Configuration Namespace” to the beans
element of your endpoint’s configuration file. In addition, you must add the configuration elements' namespace to the xsi:schemaLocation
attribute.
Example 12.4. HTTP Consumer Configuration Namespace
<beans ... xmlns:http-conf="http://cxf.apache.org/transports/http/configuration" ... xsi:schemaLocation="... http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd ...">
Undertow runtime or Netty runtime
You can use the elements from the http-conf
namespace to configure either the Undertow runtime or the Netty runtime.
The conduit element
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 12.5, “http-conf:conduit
Element” 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.
Example 12.5. http-conf:conduit
Element
... <http-conf:conduit name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-conduit"> ... </http-conf:conduit> ...
The http-conf:conduit
element has child elements that specify configuration information. They are described in Table 12.1, “Elements Used to Configure an HTTP Consumer Endpoint”.
Element | Description |
---|---|
| Specifies the HTTP connection properties such as timeouts, keep-alive requests, content types, etc. See the section called “The client element”. |
Specifies the parameters for configuring the basic authentication method that the endpoint uses preemptively. The preferred approach is to supply a | |
Specifies the parameters for configuring basic authentication against outgoing HTTP proxy servers. | |
Specifies the parameters used to configure SSL/TLS. | |
Specifies the bean reference or class name of the object that supplies the basic authentication information used by the endpoint, either preemptively or in response to a 401 HTTP challenge. | |
Specifies the bean reference or class name of the object that checks the HTTP(S) |
The client element
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 12.2, “HTTP Consumer Configuration Attributes”, specify the connection’s properties.
Attribute | Description |
---|---|
Specifies the amount of time, in milliseconds, that the consumer attempts to establish a connection before it times out. The default is
| |
Specifies the amount of time, in milliseconds, that the consumer will wait for a response before it times out. The default is
| |
Specifies if the consumer will automatically follow a server issued redirection. The default is | |
Specifies the maximum number of times a consumer will retransmit a request to satisfy a redirect. The default is | |
Specifies whether the consumer will send requests using chunking. The default is Chunking cannot be used if either of the following are true:
In both cases the value of | |
Specifies what media types the consumer is prepared to handle. The value is used as the value of the HTTP | |
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 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. | |
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 | |
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
For web services, this should be set to | |
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 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). | |
Specifies whether a particular connection is to be kept open or closed after each request/response dialog. There are two valid values:
| |
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 Section 12.2.4, “Consumer Cache Control Directives”. | |
Specifies a static cookie to be sent with all requests. | |
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. | |
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 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 | |
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, Section 12.6, “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. | |
Specifies the URL of the proxy server through which requests are routed. | |
Specifies the port number of the proxy server through which requests are routed. | |
Specifies the type of proxy server used to route requests. Valid values are:
|
Example
Example 12.6, “HTTP Consumer Endpoint Configuration” shows the configuration of an HTTP consumer endpoint that wants to keep its connection to the provider open between requests, that will only retransmit requests once per invocation, and that cannot use chunking streams.
Example 12.6. HTTP Consumer Endpoint Configuration
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:http-conf="http://cxf.apache.org/transports/http/configuration" xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <http-conf:conduit name="{http://apache.org/hello_world_soap_http}SoapPort.http-conduit"> <http-conf:client Connection="Keep-Alive" MaxRetransmits="1" AllowChunking="false" /> </http-conf:conduit> </beans>
More information
For more information on HTTP conduits see Chapter 16, Conduits.
12.2.3. Using WSDL
Namespace
The WSDL extension elements used to configure an HTTP consumer endpoint are defined in the namespace http://cxf.apache.org/transports/http/configuration. It is commonly referred to using the prefix http-conf
. In order to use the HTTP configuration elements you must add the line shown in Example 12.7, “HTTP Consumer WSDL Element’s Namespace” to the definitions
element of your endpoint’s WSDL document.
Example 12.7. HTTP Consumer WSDL Element’s Namespace
<definitions ... xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
Undertow runtime or Netty runtime
You can use the elements from the http-conf
namespace to configure either the Undertow runtime or the Netty runtime.
The client element
The http-conf:client
element is used to specify the connection properties of an HTTP consumer in a WSDL document. The http-conf:client
element is a child of the WSDL port
element. It has the same attributes as the client
element used in the configuration file. The attributes are described in Table 12.2, “HTTP Consumer Configuration Attributes”.
Example
Example 12.8, “WSDL to Configure an HTTP Consumer Endpoint” shows a WSDL fragment that configures an HTTP consumer endpoint to specify that it does not interact with caches.
Example 12.8. WSDL to Configure an HTTP Consumer Endpoint
<service ... > <port ... > <soap:address ... /> <http-conf:client CacheControl="no-cache" /> </port> </service>
12.2.4. Consumer Cache Control Directives
Table 12.3, “http-conf:client
Cache Control Directives” lists the cache control directives supported by an HTTP consumer.
Directive | Behavior |
---|---|
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. |
12.3. Configuring a Service Provider
12.3.1. Mechanisms for a HTTP Service Provider
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:
12.3.2. Using Configuration
Namespace
The elements used to configure an HTTP provider endpoint are defined in the namespace http://cxf.apache.org/transports/http/configuration. It is commonly referred to using the prefix http-conf
. In order to use the HTTP configuration elements you must add the lines shown in Example 12.9, “HTTP Provider Configuration Namespace” to the beans
element of your endpoint’s configuration file. In addition, you must add the configuration elements' namespace to the xsi:schemaLocation
attribute.
Example 12.9. HTTP Provider Configuration Namespace
<beans ... xmlns:http-conf="http://cxf.apache.org/transports/http/configuration" ... xsi:schemaLocation="... http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd ...">
Undertow runtime or Netty runtime
You can use the elements from the http-conf
namespace to configure either the Undertow runtime or the Netty runtime.
The destination element
You configure an HTTP service provider endpoint using the http-conf:destination
element and its children. The http-conf:destination
element takes a single attribute, name
, that specifies the WSDL port
element that corresponds to the endpoint. The value for the name
attribute takes the form portQName`.http-destination`. Example 12.10, “http-conf:destination
Element” shows the http-conf:destination
element that is 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.
Example 12.10. http-conf:destination
Element
... <http-conf:destination name="{http://widgets/widgetvendor.net}widgetSOAPPort.http-destination"> ... </http-conf:destination> ...
The http-conf:destination
element has a number of child elements that specify configuration information. They are described in Table 12.4, “Elements Used to Configure an HTTP Service Provider Endpoint”.
Element | Description |
---|---|
Specifies the HTTP connection properties. See the section called “The server element”. | |
Specifies the parameters that configure the context match strategy for processing HTTP requests. | |
Specifies whether the parameter order of an HTTP request handled by this destination is fixed. |
The server element
The http-conf:server
element is used to configure the properties of a service provider endpoint’s HTTP connection. Its attributes, described in Table 12.5, “HTTP Service Provider Configuration Attributes”, specify the connection’s properties.
Attribute | Description |
---|---|
Sets the length of time, in milliseconds, the service provider attempts to receive a request before the connection times out. The default is
| |
Specifies whether exceptions are to be thrown when an error is encountered on receiving a request. The default is | |
Specifies whether exceptions are to be thrown when an error is encountered on sending a response to a consumer. The default is | |
Specifies whether the service provider honors requests for a connection to remain open after a response has been sent. The default is | |
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. | |
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 Section 12.3.4, “Service Provider Cache Control Directives”. | |
Sets the URL where the resource being sent in a response is located. | |
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. | |
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. Apache CXF performs no validation on content codings. It is the user’s responsibility to ensure that a specified content coding is supported at application level. | |
Specifies what type of server is sending the response. Values take the form |
Example
Example 12.11, “HTTP Service Provider Endpoint Configuration” shows the configuration for an HTTP service provider endpoint that honors keep-alive requests and suppresses all communication errors.
Example 12.11. HTTP Service Provider Endpoint Configuration
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:http-conf="http://cxf.apache.org/transports/http/configuration" xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <http-conf:destination name="{http://apache.org/hello_world_soap_http}SoapPort.http-destination"> <http-conf:server SuppressClientSendErrors="true" SuppressClientReceiveErrors="true" HonorKeepAlive="true" /> </http-conf:destination> </beans>
12.3.3. Using WSDL
Namespace
The WSDL extension elements used to configure an HTTP provider endpoint are defined in the namespace http://cxf.apache.org/transports/http/configuration. It is commonly referred to using the prefix http-conf
. To use the HTTP configuration elements you must add the line shown in Example 12.12, “HTTP Provider WSDL Element’s Namespace” to the definitions
element of your endpoint’s WSDL document.
Example 12.12. HTTP Provider WSDL Element’s Namespace
<definitions ... xmlns:http-conf="http://cxf.apache.org/transports/http/configuration"
Undertow runtime or Netty runtime
You can use the elements from the http-conf
namespace to configure either the Undertow runtime or the Netty runtime.
The server element
The http-conf:server
element is used to specify the connection properties of an HTTP service provider in a WSDL document. The http-conf:server
element is a child of the WSDL port
element. It has the same attributes as the server
element used in the configuration file. The attributes are described in Table 12.5, “HTTP Service Provider Configuration Attributes”.
Example
Example 12.13, “WSDL to Configure an HTTP Service Provider Endpoint” shows a WSDL fragment that configures an HTTP service provider endpoint specifying that it will not interact with caches.
Example 12.13. WSDL to Configure an HTTP Service Provider Endpoint
<service ... > <port ... > <soap:address ... /> <http-conf:server CacheControl="no-cache" /> </port> </service>
12.3.4. Service Provider Cache Control Directives
Table 12.6, “http-conf:server
Cache Control Directives” lists the cache control directives supported by an HTTP service provider.
Directive | Behavior |
---|---|
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. |
12.4. Configuring the Undertow Runtime
Overview
The Undertow runtime is used by HTTP service providers and HTTP consumers using a decoupled endpoint. The runtime’s thread pool can be configured, and you can also set a number of the security settings for an HTTP service provider through the Undertow runtime.
Maven dependency
If you use Apache Maven as your build system, you can add the Undertow runtime to your project by including the following dependency in your project’s pom.xml
file:
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-undertow</artifactId> <version>${cxf-version}</version> </dependency>
Namespace
The elements used to configure the Undertow runtime are defined in the namespace http://cxf.apache.org/transports/http-undertow/configuration. In order to use the Undertow configuration elements you must add the lines shown in Example 12.14, “Undertow Runtime Configuration Namespace” to the beans
element of your endpoint’s configuration file. In this example, the namespace is assigned the prefix httpu. In addition, you must add the configuration element’s namespace to the xsi:schemaLocation
attribute.
Example 12.14. Undertow Runtime Configuration Namespace
<beans ... xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration" ... xsi:schemaLocation="... http://cxf.apache.org/transports/http-undertow/configuration http://cxf.apache.org/schemas/configuration/http-undertow.xsd ...">
The engine-factory element
The httpu:engine-factory
element is the root element used to configure the Undertow runtime used by an application. It has a single required attribute, bus
, whose value is the name of the Bus
that manages the Undertow instances being configured.
The value is typically cxf
which is the name of the default Bus
instance.
The http:engine-factory
element has three children that contain the information used to configure the HTTP ports instantiated by the Undertow runtime factory. The children are described in Table 12.7, “Elements for Configuring a Undertow Runtime Factory”.
Element | Description |
---|---|
| Specifies the configuration for a particular Undertow runtime instance. See the section called “The engine element”. |
Specifies a reusable set of properties for securing an HTTP service provider. It has a single attribute, | |
Specifies a reusable set of properties for controlling a Undertow instance’s thread pool. It has a single attribute, |
The engine element
The httpu:engine
element is used to configure specific instances of the Undertow runtime. It has a single attribute, port
, that specifies the number of the port being managed by the Undertow instance.
You can specify a value of 0
for the port
attribute. Any threading properties specified in an httpu:engine
element with its port
attribute set to 0
are used as the configuration for all Undertow listeners that are not explicitly configured.
Each httpu:engine
element can have two children: one for configuring security properties and one for configuring the Undertow 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 httpu:engine-factory
element.
The child elements used to provide the configuration properties are described in Table 12.8, “Elements for Configuring an Undertow Runtime Instance”.
Element | Description |
---|---|
Specifies a set of properties for configuring the security used for the specific Undertow instance. | |
Refers to a set of security properties defined by a | |
Specifies the size of the thread pool used by the specific Undertow instance. See the section called “Configuring the thread pool”. | |
Refers to a set of properties defined by a |
Configuring the thread pool
You can configure the size of an Undertow instance’s thread pool by either:
-
Specifying the size of the thread pool using a
identifiedThreadingParameters
element in theengine-factory
element. You then refer to the element using athreadingParametersRef
element. -
Specifying the size of the of the thread pool directly using a
threadingParameters
element.
The threadingParameters
has two attributes to specify the size of a thread pool. The attributes are described in Table 12.9, “Attributes for Configuring an Undertow Thread Pool”.
The httpu:identifiedThreadingParameters
element has a single child threadingParameters
element.
Attribute | Description |
---|---|
Specifies the number of I/O threads to be created for the worker. If not specified, the dafult value will be chosen. The default value is one I/O thread per CPU core. | |
Specifies the minimum number of threads available to the Undertow instance for processing requests. | |
Specifies the maximum number of threads available to the Undertow instance for processing requests. |
Example
Example 12.15, “Configuring an Undertow Instance” shows a configuration fragment that configures an Undertow instance on port number 9001.
Example 12.15. Configuring an Undertow Instance
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:sec="http://cxf.apache.org/configuration/security" xmlns:http="http://cxf.apache.org/transports/http/configuration" xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration" xmlns:jaxws="http://java.sun.com/xml/ns/jaxws" xsi:schemaLocation="http://cxf.apache.org/configuration/security http://cxf.apache.org/schemas/configuration/security.xsd http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://cxf.apache.org/transports/http-undertow/configuration http://cxf.apache.org/schemas/configuration/http-undertow.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd"> ... <httpu:engine-factory bus="cxf"> <httpu:identifiedTLSServerParameters id="secure"> <sec:keyManagers keyPassword="password"> <sec:keyStore type="JKS" password="password" file="certs/cherry.jks"/> </sec:keyManagers> </httpu:identifiedTLSServerParameters> <httpu:engine port="9001"> <httpu:tlsServerParametersRef id="secure" /> <httpu:threadingParameters minThreads="5" maxThreads="15" /> </httpu:engine> </httpu:engine-factory> </beans>
12.5. Configuring the Netty Runtime
Overview
The Netty runtime is used by HTTP service providers and HTTP consumers using a decoupled endpoint. The runtime’s thread pool can be configured, and you can also set a number of the security settings for an HTTP service provider through the Netty runtime.
Maven dependencies
If you use Apache Maven as your build system, you can add the server-side implementation of the Netty runtime (for defining Web service endpoints) to your project by including the following dependency in your project’s pom.xml
file:
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-netty-server</artifactId> <version>${cxf-version}</version> </dependency>
You can add the client-side implementation of the Netty runtime (for defining Web service clients) to your project by including the following dependency in your project’s pom.xml
file:
<dependency> <groupId>org.apache.cxf</groupId> <artifactId>cxf-rt-transports-http-netty-client</artifactId> <version>${cxf-version}</version> </dependency>
Namespace
The elements used to configure the Netty runtime are defined in the namespace http://cxf.apache.org/transports/http-netty-server/configuration. It is commonly referred to using the prefix httpn
. In order to use the Netty configuration elements you must add the lines shown in Example 12.16, “Netty Runtime Configuration Namespace” to the beans
element of your endpoint’s configuration file. In addition, you must add the configuration elements' namespace to the xsi:schemaLocation
attribute.
Example 12.16. Netty Runtime Configuration Namespace
<beans ... xmlns:httpn="http://cxf.apache.org/transports/http-netty-server/configuration" ... xsi:schemaLocation="... http://cxf.apache.org/transports/http-netty-server/configuration http://cxf.apache.org/schemas/configuration/http-netty-server.xsd ...">
The engine-factory element
The httpn:engine-factory
element is the root element used to configure the Netty runtime used by an application. It has a single required attribute, bus
, whose value is the name of the Bus
that manages the Netty instances being configured.
The value is typically cxf
, which is the name of the default Bus
instance.
The httpn:engine-factory
element has three children that contain the information used to configure the HTTP ports instantiated by the Netty runtime factory. The children are described in Table 12.10, “Elements for Configuring a Netty Runtime Factory”.
Element | Description |
---|---|
| Specifies the configuration for a particular Netty runtime instance. See the section called “The engine element”. |
Specifies a reusable set of properties for securing an HTTP service provider. It has a single attribute, | |
Specifies a reusable set of properties for controlling a Netty instance’s thread pool. It has a single attribute, |
The engine element
The httpn:engine
element is used to configure specific instances of the Netty runtime. Table 12.11, “Attributes for Configuring a Netty Runtime Instance” shows the attributes supported by the httpn:engine
element.
Attribute | Description |
---|---|
|
Specifies the port used by the Netty HTTP server instance. You can specify a value of |
| Specifies the listen address used by the Netty HTTP server instance. The value can be a hostname or an IP address. If not specified, Netty HTTP server will listen on all local addresses. |
| Specifies the maximum read idle time for a Netty connection. The timer is reset whenever there are any read actions on the underlying stream. |
| Specifies the maximum write idle time for a Netty connection. The timer is reset whenever there are any write actions on the underlying stream. |
| Specifies the maximum aggregated content size for a Netty connection. The default value is 10MB. |
A httpn:engine
element has one child element for configuring security properties and one child element for configuring the Netty 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 httpn:engine-factory
element.
The supported child elements of httpn:engine
are shown in Table 12.12, “Elements for Configuring a Netty Runtime Instance”.
Element | Description |
---|---|
Specifies a set of properties for configuring the security used for the specific Netty instance. | |
Refers to a set of security properties defined by a | |
Specifies the size of the thread pool used by the specific Netty instance. See the section called “Configuring the thread pool”. | |
Refers to a set of properties defined by a | |
|
When |
|
Specifies a boolean value to set the |
Configuring the thread pool
You can configure the size of a Netty instance’s thread pool by either:
-
Specifying the size of the thread pool using a
identifiedThreadingParameters
element in theengine-factory
element. You then refer to the element using athreadingParametersRef
element. -
Specifying the size of the of the thread pool directly using a
threadingParameters
element.
The threadingParameters
element has one attribute to specify the size of a thread pool, as described in Table 12.13, “Attributes for Configuring a Netty Thread Pool”.
The httpn:identifiedThreadingParameters
element has a single child threadingParameters
element.
Attribute | Description |
---|---|
| Specifies the number of threads available to the Netty instance for processing requests. |
Example
Example 12.17, “Configuring a Netty Instance” shows a configuration fragment that configures a variety of Netty ports.
Example 12.17. Configuring a Netty Instance
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:beans="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:h="http://cxf.apache.org/transports/http/configuration" xmlns:httpn="http://cxf.apache.org/transports/http-netty-server/configuration" xmlns:sec="http://cxf.apache.org/configuration/security" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://cxf.apache.org/configuration/security http://cxf.apache.org/schemas/configuration/security.xsd http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://cxf.apache.org/transports/http-netty-server/configuration http://cxf.apache.org/schemas/configuration/http-netty-server.xsd" > ... <httpn:engine-factory bus="cxf"> <httpn:identifiedTLSServerParameters id="sample1"> <httpn:tlsServerParameters jsseProvider="SUN" secureSocketProtocol="TLS"> <sec:clientAuthentication want="false" required="false"/> </httpn:tlsServerParameters> </httpn:identifiedTLSServerParameters> <httpn:identifiedThreadingParameters id="sampleThreading1"> <httpn:threadingParameters threadPoolSize="120"/> </httpn:identifiedThreadingParameters> <httpn:engine port="9000" readIdleTime="30000" writeIdleTime="90000"> <httpn:threadingParametersRef id="sampleThreading1"/> </httpn:engine> <httpn:engine port="0"> <httpn:threadingParameters threadPoolSize="400"/> </httpn:engine> <httpn:engine port="9001" readIdleTime="40000" maxChunkContentSize="10000"> <httpn:threadingParameters threadPoolSize="99" /> <httpn:sessionSupport>true</httpn:sessionSupport> </httpn:engine> <httpn:engine port="9002"> <httpn:tlsServerParameters> <sec:clientAuthentication want="true" required="true"/> </httpn:tlsServerParameters> </httpn:engine> <httpn:engine port="9003"> <httpn:tlsServerParametersRef id="sample1"/> </httpn:engine> </httpn:engine-factory> </beans>
12.6. Using the HTTP Transport in Decoupled Mode
Overview
In normal HTTP request/response scenarios, the request and the response are sent using the same HTTP connection. The service provider processes the request and responds with a response containing the appropriate HTTP status code and the contents of the response. In the case of a successful request, the HTTP status code is set to 200.
In some instances, such as when using WS-RM or when requests take an extended period of time to execute, it makes sense to decouple the request and response message. In this case the service providers sends the consumer a 202 Accepted response to the consumer over the back-channel of the HTTP connection on which the request was received. It then processes the request and sends the response back to the consumer using a new decoupled server→client HTTP connection. The consumer runtime receives the incoming response and correlates it with the appropriate request before returning to the application code.
Configuring decoupled interactions
Using the HTTP transport in decoupled mode requires that you do the following:
Configure the consumer to use WS-Addressing.
See the section called “Configuring an endpoint to use WS-Addressing”.
Configure the consumer to use a decoupled endpoint.
Configure any service providers that the consumer interacts with to use WS-Addressing.
See the section called “Configuring an endpoint to use WS-Addressing”.
Configuring an endpoint to use WS-Addressing
Specify that the consumer and any service provider with which the consumer interacts use WS-Addressing.
You can specify that an endpoint uses WS-Addressing in one of two ways:
Adding the
wswa:UsingAddressing
element to the endpoint’s WSDLport
element as shown in Example 12.18, “Activating WS-Addressing using WSDL”.Example 12.18. Activating WS-Addressing using WSDL
... <service name="WidgetSOAPService"> <port name="WidgetSOAPPort" binding="tns:WidgetSOAPBinding"> <soap:address="http://widgetvendor.net/widgetSeller" /> <wswa:UsingAddressing xmlns:wswa="http://www.w3.org/2005/02/addressing/wsdl"/> </port> </service> ...
Adding the WS-Addressing policy to the endpoint’s WSDL
port
element as shown in Example 12.19, “Activating WS-Addressing using a Policy”.Example 12.19. Activating WS-Addressing using a Policy
... <service name="WidgetSOAPService"> <port name="WidgetSOAPPort" binding="tns:WidgetSOAPBinding"> <soap:address="http://widgetvendor.net/widgetSeller" /> <wsp:Policy xmlns:wsp="http://www.w3.org/2006/07/ws-policy"> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy/> </wsam:Addressing> </wsp:Policy> </port> </service> ...
The WS-Addressing policy supersedes the wswa:UsingAddressing
WSDL element.
Configuring the consumer
Configure the consumer endpoint to use a decoupled endpoint using the DecoupledEndpoint
attribute of the http-conf:conduit
element.
Example 12.20, “Configuring a Consumer to Use a Decoupled HTTP Endpoint” shows the configuration for setting up the endpoint defined in Example 12.18, “Activating WS-Addressing using WSDL” to use use a decoupled endpoint. The consumer now receives all responses at http://widgetvendor.net/widgetSellerInbox.
Example 12.20. Configuring a Consumer to Use a Decoupled HTTP Endpoint
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:http="http://cxf.apache.org/transports/http/configuration" xsi:schemaLocation="http://cxf.apache.org/transports/http/configuration http://cxf.apache.org/schemas/configuration/http-conf.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <http:conduit name="{http://widgetvendor.net/services}WidgetSOAPPort.http-conduit"> <http:client DecoupledEndpoint="http://widgetvendor.net:9999/decoupled_endpoint" /> </http:conduit> </beans>
How messages are processed
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 12.1, “Message Flow in for a Decoupled HTTP Transport” shows the flow of messages when using HTTP in decoupled mode.
Figure 12.1. Message Flow in for a Decoupled HTTP Transport
A request starts the following process:
- The consumer implementation invokes an operation and a request message is generated.
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.
- The message is sent to the service provider.
- The service provider receives the message.
- The request message from the consumer is dispatched to the provider’s WS-A layer.
- 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.
- The HTTP layer sends a 202 Accepted message back to the consumer using the original connection’s back-channel.
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.
- The request is passed to the service provider’s implementation where the request is processed.
- When the response is ready, it is dispatched to the WS-A layer.
- The WS-A layer adds the WS-Addressing headers to the response message.
- The HTTP transport sends the response to the consumer’s decoupled endpoint.
- The consumer’s decoupled endpoint receives the response from the service provider.
- 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.
- The correlated response is returned to the client implementation and the invoking call is unblocked.
Chapter 13. Using SOAP Over JMS
Abstract
Apache CXF implements the W3C standard SOAP/JMS transport. This standard is intended to provide a more robust alternative to SOAP/HTTP services. Apache CXF applications using this transport should be able to interoperate with applications that also implement the SOAP/JMS standard. The transport is configured directly in an endpoint’s WSDL.
NOTE: Support for the JMS 1.0.2 APIs has been removed in CXF 3.0. If you are using RedHat JBoss Fuse 6.2 or higher (includes CXF 3.0), your JMS provider must support the JMS 1.1 APIs.
13.1. Basic configuration
Overview
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 Apache CXF 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:
- Specify that the transport type is SOAP/JMS.
- Specify the target destination using a JMS URI.
- Optionally, configure the JNDI connection.
- Optionally, add additional JMS configuration.
Specifying the JMS transport type
You configure a SOAP binding to use the JMS transport when specifying the WSDL binding. You set the soap:binding
element’s transport
attribute to http://www.w3.org/2010/soapjms/
. Example 13.1, “SOAP over JMS binding specification” shows a WSDL binding that uses SOAP/JMS.
Example 13.1. SOAP over JMS binding specification
<wsdl:binding ... > <soap:binding style="document" transport="http://www.w3.org/2010/soapjms/" /> ... </wsdl:binding>
Specifying the target destination
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 13.2, “JMS URI syntax” shows the syntax for a JMS URI.
Example 13.2. JMS URI syntax
jms:variant:destination?options
Table 13.1, “JMS URI variants” describes the available variants for the JMS URI.
Variant | Description |
---|---|
jndi | Specifies that the destination name is a JNDI queue name. When using this variant, you must provide the configuration for accessing the JNDI provider. |
jndi-topic | Specifies that the destination name is a JNDI topic name. When using this variant, you must provide the configuration for accessing the JNDI provider. |
queue |
Specifies that the destination is a queue name resolved using JMS. The string provided is passed into |
topic |
Specifies that the destination is a topic name resolved using JMS. The string provided is passed into |
The options portion of a JMS URI are used to configure the transport and are discussed in Section 13.2, “JMS URIs”.
Example 13.3, “SOAP/JMS endpoint address” shows the WSDL port entry for a SOAP/JMS endpoint whose target destination is looked up using JNDI.
Example 13.3. SOAP/JMS endpoint address
<wsdl:port ... > ... <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" /> </wsdl:port>
Configuring JNDI and the JMS transport
The SOAP/JMS provides several ways to configure the JNDI connection and the JMS transport:
13.2. JMS URIs
Overview
When using SOAP/JMS, a JMS URI is used to specify the endpoint’s target destination. The JMS URI can also be used to configure JMS connection by appending one or more options to the URI. These options are detailed in the IETF standard, URI Scheme for Java Message Service 1.0. They can be used to configure the JNDI system, the reply destination, the delivery mode to use, and other JMS properties.
Syntax
As shown in Example 13.4, “Syntax for JMS URI options”, 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 13.4, “Syntax for JMS URI options” shows the syntax for using multiple options in a JMS URI.
Example 13.4. Syntax for JMS URI options
jms:variant:jmsAddress?option1=value1&option2=value2&_optionN_=valueN
JMS properties
Table 13.2, “JMS properties settable as URI options” shows the URI options that affect the JMS transport layer.
Property | Default | Description |
---|---|---|
| [Optional] A string value that is prefixed to all correlation IDs that the conduit creates. The selector can use it to listen for replies. | |
|
|
Specifies whether to use JMS |
| [Optional] Specifies the client identifier for the connection. This property is used to associate a connection with a state that the provider maintains on behalf of the client. This enables subsequent subscribers with the same identity to resume the subscription in the state that the preceding subscriber left it. | |
| [Optional] Specifies the name of the subscription. | |
|
| Specifies the JMS message type used by CXF. Valid values are:
|
| [Optional] Specifies the password for creating the connection. Appending this property to the URI is discouraged. | |
|
| Specifies the JMS message priority, which ranges from 0 (lowest) to 9 (highest). |
|
| Specifies the time, in milliseconds, the client will wait for a reply when request/reply exchanges are used. |
|
| [Deprecated in CXF 3.0] Specifies whether the transport should reconnect when exceptions occur. As of 3.0, the transport will always reconnect when an exception occurs. |
|
[Optional] Specifies the reply destination for queue messages. The reply destination appears in the The value of this property is interpreted according to the variant specified in the JMS URI:
| |
|
| Specifies the transaction type. Valid values are:
|
|
|
Specifies the time, in milliseconds, after which the JMS provider will discard the message. A value of |
| [Optional] Specifies the reply destination for topic messages. The value of this property is interpreted according to the variant specified in the JMS URI:
| |
|
| Specifies whether the conduit’s UUID will be used as the prefix for all correlation IDs.
As all conduits are assigned a unique UUID, setting this property to |
| [Optional] Specifies the username to use to create the connection. |
JNDI properties
Table 13.3, “JNDI properties settable as URI options” shows the URI options that can be used to configure JNDI for this endpoint.
Property | Description |
---|---|
| Specifies the JNDI name of the JMS connection factory. |
|
Specifies the fully qualified Java class name of the JNDI provider (which must be of |
|
Specifies the name of the JTA transaction manager that will be searched for in Spring, Blueprint, or JNDI. If a transaction manager is found, JTA transactions will be enabled. See the |
|
Specifies the URL that initializes the JNDI provider. Equivalent to setting the |
Additional JNDI properties
The properties, java.naming.factory.initial
and java.naming.provider.url
, are standard properties, which are required to initialize any JNDI provider. Sometimes, however, a JNDI provider might support custom properties in addition to the standard ones. In this case, you can set an arbitrary JNDI property by setting a URI option of the form jndi-PropertyName
.
For example, if you were using SUN’s LDAP implementation of JNDI, you could set the JNDI property, java.naming.factory.control
, in a JMS URI as shown in Example 13.5, “Setting a JNDI property in a JMS URI”.
Example 13.5. Setting a JNDI property in a JMS URI
jms:queue:FOO.BAR?jndi-java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
Example
If the JMS provider is not already configured, it is possible to provide the requisite JNDI configuration details in the URI using options (see Table 13.3, “JNDI properties settable as URI options”). For example, to configure an endpoint to use the Apache ActiveMQ JMS provider and connect to the queue called test.cxf.jmstransport.queue
, use the URI shown in Example 13.6, “JMS URI that configures a JNDI connection”.
Example 13.6. JMS URI that configures a JNDI connection
jms:jndi:dynamicQueues/test.cxf.jmstransport.queue ?jndiInitialContextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory &jndiConnectionFactoryName=ConnectionFactory &jndiURL=tcp://localhost:61616
Publishing a service
The JAX-WS standard publish()
method cannot be used to publish a SOAP/JMS service. Instead, you must use the Apache CXF’s JaxWsServerFactoryBean
class as shown in Example 13.7, “Publishing a SOAP/JMS service”.
Example 13.7. Publishing a SOAP/JMS service
String address = "jms:jndi:dynamicQueues/test.cxf.jmstransport.queue3" + "?jndiInitialContextFactory" + "=org.apache.activemq.jndi.ActiveMQInitialContextFactory" + "&jndiConnectionFactoryName=ConnectionFactory" + "&jndiURL=tcp://localhost:61500"; Hello implementor = new HelloImpl(); JaxWsServerFactoryBean svrFactory = new JaxWsServerFactoryBean(); svrFactory.setServiceClass(Hello.class); svrFactory.setAddress(address); svrFactory.setTransportId(JMSSpecConstants.SOAP_JMS_SPECIFICIATION_TRANSPORTID); svrFactory.setServiceBean(implementor); svrFactory.create();
The code in Example 13.7, “Publishing a SOAP/JMS service” does the following:
Creates the JMS URI representing t he endpoint’s address.
Instantiates a JaxWsServerFactoryBean
to publish the service.
Sets the address
field of the factory bean with the JMS URI of the service.
Specifies that the service created by the factory will use the SOAP/JMS transport.
Consuming a service
The standard JAX-WS APIs cannot be used to consume a SOAP/JMS service. Instead, you must use the Apache CXF’s JaxWsProxyFactoryBean
class as shown in Example 13.8, “Consuming a SOAP/JMS service”.
Example 13.8. Consuming a SOAP/JMS service
// Java public void invoke() throws Exception { String address = "jms:jndi:dynamicQueues/test.cxf.jmstransport.queue3" + "?jndiInitialContextFactory" + "=org.apache.activemq.jndi.ActiveMQInitialContextFactory" + "&jndiConnectionFactoryName=ConnectionFactory&jndiURL=tcp://localhost:61500"; JaxWsProxyFactoryBean factory = new JaxWsProxyFactoryBean(); factory.setAddress(address); factory.setTransportId(JMSSpecConstants.SOAP_JMS_SPECIFICIATION_TRANSPORTID); factory.setServiceClass(Hello.class); Hello client = (Hello)factory.create(); String reply = client.sayHi(" HI"); System.out.println(reply); }
The code in Example 13.8, “Consuming a SOAP/JMS service” does the following:
Creates the JMS URI representing t he endpoint’s address.
Instantiates a JaxWsProxyFactoryBean
to create the proxy.
Sets the address
field of the factory bean with the JMS URI of the service.
Specifies that the proxy created by the factory will use the SOAP/JMS transport.
13.3. WSDL extensions
Overview
You can specify the basic configuration of the JMS transport by inserting WSDL extension elements into the contract, either at binding scope, service scope, or port scope. The WSDL extensions enable you to specify the properties for bootstrapping a JNDI InitialContext
, which can then be used to look up JMS destinations. You can also set some properties that affect the behavior of the JMS transport layer.
SOAP/JMS namespace
the SOAP/JMS WSDL extensions are defined in the http://www.w3.org/2010/soapjms/
namespace. To use them in your WSDL contracts add the following setting to the wsdl:definitions
element:
<wsdl:definitions ... xmlns:soapjms="http://www.w3.org/2010/soapjms/" ... >
WSDL extension elements
Table 13.4, “SOAP/JMS WSDL extension elements” shows all of the WSDL extension elements you can use to configure the JMS transport.
Element | Default | Description |
---|---|---|
|
Specifies the fully qualified Java class name of the JNDI provider. Equivalent to setting the | |
|
Specifies the URL that initializes the JNDI provider. Equivalent to setting the | |
|
Specifies an additional property for creating the JNDI | |
| Specifies the JNDI name of the JMS connection factory. | |
|
|
Specifies whether to use JMS |
|
[Optional] Specifies the reply destination for queue messages. The reply destination appears in the The value of this property is interpreted according to the variant specified in the JMS URI:
| |
|
| Specifies the JMS message priority, which ranges from 0 (lowest) to 9 (highest). |
|
|
Time, in milliseconds, after which the JMS provider will discard the message. A value of |
Configuration scopes
The WSDL elements placement in the WSDL contract effect the scope of the configuration changes on the endpoints defined in the contract. The SOAP/JMS WSDL elements can be placed as children of either the wsdl:binding
element, the wsdl:service
element, or the wsdl:port
element. The parent of the SOAP/JMS elements determine which of the following scopes the configuration is placed into.
- Binding scope
-
You can configure the JMS transport at the binding scope by placing extension elements inside the
wsdl:binding
element. Elements in this scope define the default configuration for all endpoints that use this binding. Any settings in the binding scope can be overridden at the service scope or the port scope. - Service scope
-
You can configure the JMS transport at the service scope by placing extension elements inside a
wsdl:service
element. Elements in this scope define the default configuration for all endpoints in this service. Any settings in the service scope can be overridden at the port scope. - Port scope
-
You can configure the JMS transport at the port scope by placing extension elements inside a
wsdl:port
element. Elements in the port scope define the configuration for this port. They override the defaults of the same extension elements defined at the service scope or at the binding scope.
Example
Example 13.9, “WSDL contract with SOAP/JMS configuration” 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 13.9. WSDL contract with SOAP/JMS configuration
<wsdl:definitions ... xmlns:soapjms="http://www.w3.org/2010/soapjms/" ... > ... <wsdl:binding name="JMSGreeterPortBinding" type="tns:JMSGreeterPortType"> ... <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"> ... <soapjms:deliveryMode>NON_PERSISTENT</soapjms:deliveryMode> <soapjms:timeToLive>60000</soapjms:timeToLive> ... <wsdl:port binding="tns:JMSGreeterPortBinding" name="GreeterPort"> <soap:address location="jms:jndi:dynamicQueues/test.cxf.jmstransport.queue" /> <soapjms:replyToName> dynamicQueues/greeterReply.queue </soapjms:replyToName> ... </wsdl:port> ... </wsdl:service> ... </wsdl:definitions>
The WSDL in Example 13.9, “WSDL contract with SOAP/JMS configuration” does the following:
Declares the namespace for the SOAP/JMS extensions.
Configures the JNDI connections in the binding scope.
Sets the JMS delivery style to non-persistent and each message to live for one minute.
Specifies the target destination.
Configures the JMS transport so that reply messages are delivered on the greeterReply.queue
queue.
Chapter 14. Using Generic JMS
Abstract
Apache CXF provides a generic implementation of a JMS transport. The generic JMS transport is not restricted to using SOAP messages and allows for connecting to any application that uses JMS.
NOTE: Support for the JMS 1.0.2 APIs has been removed in CXF 3.0. If you are using RedHat JBoss Fuse 6.2 or higher (includes CXF 3.0), your JMS provider must support the JMS 1.1 APIs.
14.1. Approaches to Configuring JMS
The Apache CXF 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:
14.2. Using the JMS configuration bean
Overview
To simplify JMS configuration and make it more powerful, Apache CXF uses a single JMS configuration bean to configure JMS endpoints. The bean is implemented by the org.apache.cxf.transport.jms.JMSConfiguration
class. It can be used to either configure endpoint’s directly or to configure the JMS conduits and destinations.
Configuration namespace
The JMS configuration bean uses the Spring p-namespace to make the configuration as simple as possible. To use this namespace you need to declare it in the configuration’s root element as shown in Example 14.1, “Declaring the Spring p-namespace”.
Example 14.1. Declaring the Spring p-namespace
<beans ... xmlns:p="http://www.springframework.org/schema/p" ... > ... </beans>
Specifying the configuration
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.
In CXF 3.0, the JMS transport no longer has a dependency on Spring JMS, so some Spring JMS-related options have been removed.
Table 14.1, “General JMS Configuration Properties” lists properties that are common to both providers and consumers.
Property | Default | Description |
---|---|---|
| [Required] Specifies a reference to a bean that defines a JMS ConnectionFactory. | |
|
| Removed in CXF 3.0
pre CXF 3.0 Specifies whether to wrap the ConnectionFactory with a Spring
Enable this property when using a ConnectionFactory that does not pool connections, as it will improve the performance of the JMS transport. This is so because the JMS transport creates a new connection for each message, and the |
|
| Deprecated in CXF 3.0 CXF always reconnects when an exception occurs. pre CXF 3.0 Specifies whether to create a new connection when an exception occurs.
When wrapping the ConnectionFactory with a Spring
|
| Specifies the JNDI name or provider-specific name of a destination. | |
| Specifies the JMS name of the JMS destination where replies are sent. This property allows the use of a user-defined destination for replies. For more details see Section 14.6, “Using a Named Reply Destination”. | |
| DynamicDestinationResolver |
Specifies a reference to a Spring This property allows you to define how destination names are resolved to JMS destinations. Valid values are:
|
| Specifies a reference to a Spring transaction manager. This enables the service to participate in JTA transactions. | |
|
| Removed in CXF 3.0 pre CXF 3.0 Specifies a reference to a Spring TaskExecutor. This is used in listeners to decide how to handle incoming messages. |
|
| Removed in CXF 3.0 CXF 3.0 supports JMS 1.1 features only. pre CXF 3.0 Specifies whether JMS 1.1 features are used. Valid values are:
|
|
| Removed in CXF 3.0 pre CXF 3.0 Specifies whether the JMS transport wants the JMS broker to provide message IDs. Valid values are:
|
|
| Removed in CXF 3.0 pre CXF 3.0 Specifies whether the JMS transport wants the JMS broker to provide message time stamps. Valid values are:
|
|
| Removed in CXF 3.0 pre CXF 3.0 Specifies the level of caching that the JMS listener container may apply. Valid values are:
For details, see Class DefaultMessageListenerContainer |
|
| Specifies whether to receive your own messages when using topics.
|
|
| Specifies the time, in milliseconds, to wait for response messages. |
|
|
Specifies whether the QoS settings (such as priority, persistence, time to live) are explicitly set for each message ( |
|
| Specifies whether a message is persistent. Valid values are:
|
|
|
Specifies message priority. JMS priority values range from |
|
| Specifies the time, in milliseconds, before a message that has been sent is discarded. |
|
| Specifies whether JMS transactions are used. |
|
| Removed in CXF 3.0 pre CXF 3.0 Specifies the minimum number of concurrent consumers for the listener. |
|
| Removed in CXF 3.0 pre CXF 3.0 Specifies the maximum number of concurrent consumers for the listener. |
| Specifies the string value of the selector used to filter incoming messages. This property enables multiple connections to share a queue. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification. | |
|
| Specifies whether the server uses durable subscriptions. |
| Specifies the name (string) used to register the durable subscription. | |
|
| Specifies how the message data will be packaged as a JMS message. Valid values are:
|
|
| Specifies whether the target destination is a topic or a queue. Valid values are:
|
|
| Specifies whether the JMS provider is Tibco EMS.
When set to |
|
| Removed in CXF 3.0 Specifies whether JMS will use the message ID to correlate messages.
When set to |
|
| CXF 3.0 Specifies the maximum number of suspended continuations the JMS destination may have. When the current number exceeds the specified maximum, the JMSListenerContainer is stopped. |
|
|
CXF 3.0 Specifies when to restart the JMSListenerContainer stopped for exceeding
The listener container is restarted when its current number of suspended continuations falls below the value of |
As shown in Example 14.2, “JMS configuration bean”, the bean’s properties are specified as attributes to the bean
element. They are all declared in the Spring p
namespace.
Example 14.2. JMS configuration bean
<bean id="jmsConfig" class="org.apache.cxf.transport.jms.JMSConfiguration" p:connectionFactory="jmsConnectionFactory" p:targetDestination="dynamicQueues/greeter.request.queue" p:pubSubDomain="false" />
Applying the configuration to an endpoint
The JMSConfiguration
bean can be applied directly to both server and client endpoints using the Apache CXF features mechanism. To do so:
-
Set the endpoint’s
address
attribute tojms://
. -
Add a
jaxws:feature
element to the endpoint’s configuration. -
Add a bean of type
org.apache.cxf.transport.jms.JMSConfigFeature
to the feature. -
Set the
bean
element’sp:jmsConfig-ref
attribute to the ID of theJMSConfiguration
bean.
Example 14.3, “Adding JMS configuration to a JAX-WS client” shows a JAX-WS client that uses the JMS configuration from Example 14.2, “JMS configuration bean”.
Example 14.3. Adding JMS configuration to a JAX-WS client
<jaxws:client id="CustomerService" xmlns:customer="http://customerservice.example.com/" serviceName="customer:CustomerServiceService" endpointName="customer:CustomerServiceEndpoint" address="jms://" serviceClass="com.example.customerservice.CustomerService"> <jaxws:features> <bean xmlns="http://www.springframework.org/schema/beans" class="org.apache.cxf.transport.jms.JMSConfigFeature" p:jmsConfig-ref="jmsConfig"/> </jaxws:features> </jaxws:client>
Applying the configuration to the transport
The JMSConfiguration
bean can be applied to JMS conduits and JMS destinations using the jms:jmsConfig-ref
element. The jms:jmsConfig-ref
element’s value is the ID of the JMSConfiguration
bean.
Example 14.4, “Adding JMS configuration to a JMS conduit” shows a JMS conduit that uses the JMS configuration from Example 14.2, “JMS configuration bean”.
Example 14.4. Adding JMS configuration to a JMS conduit
<jms:conduit name="{http://cxf.apache.org/jms_conf_test}HelloWorldQueueBinMsgPort.jms-conduit"> ... <jms:jmsConfig-ref>jmsConf</jms:jmsConfig-ref> </jms:conduit>
14.3. Optimizing Client-Side JMS Performance
Overview
Two major settings affect the JMS performance of clients: pooling and synchronous receives.
Pooling
On the client side, CXF creates a new JMS session and JMS producer for each message. This is so because neither session nor producer objects are thread safe. Creating a producer is especially time intensive because it requires communicating with the server.
Pooling connection factories improves performance by caching the connection, session, and producer.
For ActiveMQ, configuring pooling is simple; for example:
import org.apache.activemq.ActiveMQConnectionFactory; import org.apache.activemq.pool.PooledConnectionFactory; ConnectionFactory cf = new ActiveMQConnectionFactory("tcp://localhost:61616"); PooledConnectionFactory pcf = new PooledConnectionFactory(); //Set expiry timeout because the default (0) prevents reconnection on failure pcf.setExpiryTimeout(5000); pcf.setConnectionFactory(cf); JMSConfiguration jmsConfig = new JMSConfiguration(); jmsConfig.setConnectionFactory(pdf);
For more information on pooling, see "Appendix A Optimizing Performance of JMS Single- and Multiple-Resource Transactions" in the Red Hat JBoss Fuse Transaction Guide
Avoiding synchronous receives
For request/reply exchanges, the JMS transport sends a request and then waits for a reply. Whenever possible, request/reply messaging is implemented asynchronously using a JMS MessageListener
.
However, CXF must use a synchronous Consumer.receive()
method when it needs to share queues between endpoints. This scenario requires the MessageListener
to use a message selector to filter the messages. The message selector must be known in advance, so the MessageListener
is opened only once.
Two cases in which the message selector cannot be known in advance should be avoided:
When
JMSMessageID
is used as theJMSCorrelationID
If the JMS properties
useConduitIdSelector
andconduitSelectorPrefix
are not set on the JMS transport, the client does not set aJMSCorrelationId
. This causes the server to use theJMSMessageId
of the request message as theJMSCorrelationId
. AsJMSMessageID
cannot be known in advance, the client has to use a synchronousConsumer.receive()
method.Note that you must use the
Consumer.receive()
method with IBM JMS endpoints (their default).The user sets the
JMStype
in the request message and then sets a customJMSCorrelationID
.Again, as the custom
JMSCorrelationID
cannot be known in advance, the client has to use a synchronousConsumer.receive()
method.
So the general rule is to avoid using settings that require using a synchronous receive.
14.4. Configuring JMS Transactions
Overview
CXF 3.0 supports both local JMS transactions and JTA transactions on CXF endpoints, when using one-way messaging.
Local transactions
Transactions using local resources roll back the JMS message only when an exception occurs. They do not directly coordinate other resources, such as database transactions.
To set up a local transaction, configure the endpoint as you normally would, and set the property sessionTrasnsacted
to true
.
For more information on transactions and pooling, see the Red Hat JBoss Fuse Transaction Guide.
JTA transactions
Using JTA transactions, you can coordinate any number of XA resources. If a CXF endpoint is configured for JTA transactions, it starts a transaction before calling the service implementation. The transaction will be committed if no exception occurs. Otherwise, it will be rolled back.
In JTA transactions, a JMS message is consumed and the data written to a database. When an exception occurs, both resources are rolled back, so either the message is consumed and the data is written to the database, or the message is rolled back and the data is not written to the database.
Configuring JTA transactions requires two steps:
Defining a transaction manager
bean method
Define a transaction manager
<bean id="transactionManager" class="org.apache.geronimo.transaction.manager.GeronimoTransactionManager"/>
Set the name of the transaction manager in the JMS URI
jms:queue:myqueue?jndiTransactionManager=TransactionManager
This example finds a bean with the ID
TransactionManager
.
OSGi reference method
Look up the transaction manager as an OSGi service using Blueprint
<reference id="TransactionManager" interface="javax.transaction.TransactionManager"/>
Set the name of the transaction manager in the JMS URI
jms:jndi:myqueue?jndiTransactionManager=java:comp/env/TransactionManager
This example looks up the transaction manager in JNDI.
Configuring a JCA pooled connection factory
Using Spring to define the JCA pooled connection factory:
<bean id="xacf" class="org.apache.activemq.ActiveMQXAConnectionFactory"> <property name="brokerURL" value="tcp://localhost:61616" /> </bean> <bean id="ConnectionFactory" class="org.apache.activemq.jms.pool.JcaPooledConnectionFactory"> <property name="transactionManager" ref="transactionManager" /> <property name="connectionFactory" ref="xacf" /> </bean>
In this example, the first bean defines an ActiveMQ XA connection factory, which is given to a
JcaPooledConnectionFactory
. TheJcaPooledConnectionFactory
is then provided as the default bean with idConnectionFactory
.Note that the
JcaPooledConnectionFactory
looks like a normal ConnectionFactory. But when a new connection and session are opened, it checks for an XA transaction and, if found, automatically registers the JMS session as an XA resource. This allows the JMS session to participate in the JMS transaction.ImportantDirectly setting an XA ConnectionFactory on the JMS transport will not work!
14.5. Using WSDL to configure JMS
14.5.1. JMS WSDL Extension Namespance
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 14.5, “JMS WSDL extension namespace” to the definitions element of your contract.
Example 14.5. JMS WSDL extension namespace
xmlns:jms="http://cxf.apache.org/transports/jms"
14.5.2. Basic JMS configuration
Overview
The JMS address information is provided using the jms:address
element and its child, the jms:JMSNamingProperties
element. The jms:address
element’s attributes specify the information needed to identify the JMS broker and the destination. The jms:JMSNamingProperties
element specifies the Java properties used to connect to the JNDI service.
Information specified using the JMS feature will override the information in the endpoint’s WSDL file.
Specifying the JMS address
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 14.2, “JMS endpoint attributes”.
Attribute | Description |
---|---|
Specifies if the JMS destination is a JMS queue or a JMS topic. | |
Specifies the JNDI name bound to the JMS connection factory to use when connecting to the JMS destination. | |
Specifies the JMS name of the JMS destination to which requests are sent. | |
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 Section 14.6, “Using a Named Reply Destination”. | |
Specifies the JNDI name bound to the JMS destination to which requests are sent. | |
Specifies the JNDI name bound to the JMS destinations where replies are sent. This attribute allows you to use a user defined destination for replies. For more details see Section 14.6, “Using a Named Reply Destination”. | |
Specifies the user name to use when connecting to a JMS broker. | |
Specifies the password to use when connecting to a JMS broker. |
The jms:address
WSDL element uses a jms:JMSNamingProperties
child element to specify additional information needed to connect to a JNDI provider.
Specifying JNDI properties
To increase interoperability with JMS and JNDI providers, the jms:address
element has a child element, jms:JMSNamingProperties
, that allows you to specify the values used to populate the properties used when connecting to the JNDI provider. The jms:JMSNamingProperties
element has two attributes: name
and value
. name
specifies the name of the property to set. value
attribute specifies the value for the specified property. jms:JMSNamingProperties
element can also be used for specification of provider specific properties.
The following is a list of common JNDI properties that can be set:
-
java.naming.factory.initial
-
java.naming.provider.url
-
java.naming.factory.object
-
java.naming.factory.state
-
java.naming.factory.url.pkgs
-
java.naming.dns.url
-
java.naming.authoritative
-
java.naming.batchsize
-
java.naming.referral
-
java.naming.security.protocol
-
java.naming.security.authentication
-
java.naming.security.principal
-
java.naming.security.credentials
-
java.naming.language
-
java.naming.applet
For more details on what information to use in these attributes, check your JNDI provider’s documentation and consult the Java API reference material.
Example
Example 14.6, “JMS WSDL port specification” shows an example of a JMS WSDL port
specification.
Example 14.6. JMS WSDL port specification
<service name="JMSService"> <port binding="tns:Greeter_SOAPBinding" name="SoapPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> </port> </service>
14.5.3. JMS client configuration
Overview
JMS consumer endpoints specify the type of messages they use. JMS consumer endpoint can use either a JMS ByteMessage
or a JMS TextMessage
.
When using an ByteMessage
the consumer endpoint uses a byte[]
as the method for storing data into and retrieving data from the JMS message body. When messages are sent, the message data, including any formating information, is packaged into a byte[]
and placed into the message body before it is placed on the wire. When messages are received, the consumer endpoint will attempt to unmarshall the data stored in the message body as if it were packed in a byte[]
.
When using a TextMessage
, the consumer endpoint uses a string as the method for storing and retrieving data from the message body. When messages are sent, the message information, including any format-specific information, is converted into a string and placed into the JMS message body. When messages are received the consumer endpoint will attempt to unmarshall the data stored in the JMS message body as if it were packed into a string.
When native JMS applications interact with Apache CXF consumers, the JMS application is responsible for interpreting the message and the formatting information. For example, if the Apache CXF contract specifies that the binding used for a JMS endpoint is SOAP, and the messages are packaged as TextMessage
, the receiving JMS application will get a text message containing all of the SOAP envelope information.
Specifying the message type
The type of messages accepted by a JMS consumer endpoint is configured using the optional jms:client
element. The jms:client
element is a child of the WSDL port
element and has one attribute:
Specifies how the message data will be packaged as a JMS message. |
Example
Example 14.7, “WSDL for a JMS consumer endpoint” shows the WSDL for configuring a JMS consumer endpoint.
Example 14.7. WSDL for a JMS consumer endpoint
<service name="JMSService"> <port binding="tns:Greeter_SOAPBinding" name="SoapPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> <jms:client messageType="binary" /> </port> </service>
14.5.4. JMS provider configuration
Overview
JMS provider endpoints have a number of behaviors that are configurable. These include:
- how messages are correlated
- the use of durable subscriptions
- if the service uses local JMS transactions
- the message selectors used by the endpoint
Specifying the configuration
Provider endpoint behaviors are configured using the optional jms:server
element. The jms:server
element is a child of the WSDL wsdl:port
element and has the following attributes:
Attribute | Description |
---|---|
Specifies whether JMS will use the message ID to correlate messages. The default is | |
Specifies the name used to register a durable subscription. | |
Specifies the string value of a message selector to use. For more information on the syntax used to specify message selectors, see the JMS 1.1 specification. | |
Specifies whether the local JMS broker will create transactions around message processing. The default is | |
Example
Example 14.8, “WSDL for a JMS provider endpoint” shows the WSDL for configuring a JMS provider endpoint.
Example 14.8. WSDL for a JMS provider endpoint
<service name="JMSService"> <port binding="tns:Greeter_SOAPBinding" name="SoapPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/test.Celtix.jmstransport" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> <jms:server messageSelector="cxf_message_selector" useMessageIDAsCorrelationID="true" transactional="true" durableSubscriberName="cxf_subscriber" /> </port> </service>
14.6. Using a Named Reply Destination
Overview
By default, Apache CXF endpoints using JMS create a temporary queue for sending replies back and forth. If you prefer to use named queues, you can configure the queue used to send replies as part of an endpoint’s JMS configuration.
Setting the reply destination name
You specify the reply destination using either the jmsReplyDestinationName
attribute or the jndiReplyDestinationName
attribute in the endpoint’s JMS configuration. A client endpoint will listen for replies on the specified destination and it will specify the value of the attribute in the ReplyTo
field of all outgoing requests. A service endpoint will use the value of the jndiReplyDestinationName
attribute as the location for placing replies if there is no destination specified in the request’s ReplyTo
field.
Example
Example 14.9, “JMS Consumer Specification Using a Named Reply Queue” shows the configuration for a JMS client endpoint.
Example 14.9. JMS Consumer Specification Using a Named Reply Queue
<jms:conduit name="{http://cxf.apache.org/jms_endpt}HelloWorldJMSPort.jms-conduit">
<jms:address destinationStyle="queue"
jndiConnectionFactoryName="myConnectionFactory"
jndiDestinationName="myDestination"
jndiReplyDestinationName="myReplyDestination" >
<jms:JMSNamingProperty name="java.naming.factory.initial"
value="org.apache.cxf.transport.jms.MyInitialContextFactory" />
<jms:JMSNamingProperty name="java.naming.provider.url"
value="tcp://localhost:61616" />
</jms:address>
</jms:conduit>
Chapter 15. Integrating with Apache ActiveMQ
Overview
If you are using Apache ActiveMQ as your JMS provider, the JNDI name of your destinations can be specified in a special format that dynamically creates JNDI bindings for queues or topics. This means that it is not necessary to configure the JMS provider in advance with the JNDI bindings for your queues or topics.
The initial context factory
The key to integrating Apache ActiveMQ with JNDI is the ActiveMQInitialContextFactory
class. This class is used to create a JNDI InitialContext
instance, which you can then use to access JMS destinations in the JMS broker.
Example 15.1, “SOAP/JMS WSDL to connect to Apache ActiveMQ” shows SOAP/JMS WSDL extensions to create a JNDI InitialContext
that is integrated with Apache ActiveMQ.
Example 15.1. SOAP/JMS WSDL to connect to Apache ActiveMQ
<soapjms:jndiInitialContextFactory> org.apache.activemq.jndi.ActiveMQInitialContextFactory </soapjms:jndiInitialContextFactory> <soapjms:jndiURL>tcp://localhost:61616</soapjms:jndiURL>
In Example 15.1, “SOAP/JMS WSDL to connect to Apache ActiveMQ”, the Apache ActiveMQ client connects to the broker port located at tcp://localhost:61616
.
Looking up the connection factory
As well as creating a JNDI InitialContext
instance, you must specify the JNDI name that is bound to a javax.jms.ConnectionFactory
instance. In the case of Apache ActiveMQ, there is a predefined binding in the InitialContext
instance, which maps the JNDI name ConnectionFactory
to an ActiveMQConnectionFactory
instance. Example 15.2, “SOAP/JMS WSDL for specifying the Apache ActiveMQ connection factory” shaows the SOAP/JMS extension element for specifying the Apache ActiveMQ connection factory.
Example 15.2. SOAP/JMS WSDL for specifying the Apache ActiveMQ connection factory
<soapjms:jndiConnectionFactoryName> ConnectionFactory </soapjms:jndiConnectionFactoryName>
Syntax for dynamic destinations
To access queues or topics dynamically, specify the destination’s JNDI name as a JNDI composite name in either of the following formats:
dynamicQueues/QueueName dynamicTopics/TopicName
QueueName and TopicName are the names that the Apache ActiveMQ broker uses. They are not abstract JNDI names.
Example 15.3, “WSDL port specification with a dynamically created queue” shows a WSDL port that uses a dynamically created queue.
Example 15.3. WSDL port specification with a dynamically created queue
<service name="JMSService"> <port binding="tns:GreeterBinding" name="JMSPort"> <jms:address jndiConnectionFactoryName="ConnectionFactory" jndiDestinationName="dynamicQueues/greeter.request.queue" > <jms:JMSNamingProperty name="java.naming.factory.initial" value="org.activemq.jndi.ActiveMQInitialContextFactory" /> <jms:JMSNamingProperty name="java.naming.provider.url" value="tcp://localhost:61616" /> </jms:address> </port> </service>
When the application attempts to open the JMS connection, Apache ActiveMQ will check to see if a queue with the JNDI name greeter.request.queue
exists. If it does not exist, it will create a new queue and bind it to the JNDI name greeter.request.queue
.
Chapter 16. Conduits
Abstract
Conduits are a low-level piece of the transport architecture that are used to implement outbound connections. Their behavior and life-cycle can effect system performance and processing load.
Overview
Conduits manage the client-side, or outbound, transport details in the Apache CXF runtime. They are responsible for opening ports, establishing outbound connections, sending messages, and listening for any responses between an application and a single external endpoint. If an application connects to multiple endpoints, it will have one conduit instance for each endpoint.
Each transport type implements its own conduit using the Conduit interface. This allows for a standardized interface between the application level functionality and the transports.
In general, you only need to worry about the conduits being used by your application when configuring the client-side transport details. The underlying semantics of how the runtime handles conduits is, generally, not something a developer needs to worry about.
However, there are cases when an understanding of conduit’s can prove helpful:
- Implementing a custom transport
- Advanced application tuning to manage limited resources
Conduit life-cycle
Conduits are managed by the client implementation object. Once created, a conduit lives for the duration of the client implementation object. The conduit’s life-cycle is:
-
When the client implementation object is created, it is given a reference to a
ConduitSelector
object. When the client needs to send a message is request’s a reference to a conduit from the conduit selector.
If the message is for a new endpoint, the conduit selector creates a new conduit and passes it to the client implementation. Otherwise, it passes the client a reference to the conduit for the target endpoint.
- The conduit sends messages when needed.
- When the client implementation object is destroyed, all of the conduits associated with it are destroyed.
Conduit weight
The weight of a conduit object depends on the transport implementation. HTTP conduits are extremely light weight. JMS conduits are heavy because they are associated with the JMS Session
object and one or more JMSListenerContainer
objects.
Part IV. Configuring Web Service Endpoints
This guide describes how to create Apache CXF endpoints in Red Hat Fuse.
Chapter 17. Configuring JAX-WS Endpoints
Abstract
JAX-WS endpoints are configured using one of three Spring configuration elements. The correct element depends on what type of endpoint you are configuring and which features you wish to use. For consumers you use the jaxws:client
element. For service providers you can use either the jaxws:endpoint
element or the jaxws:server
element.
The information used to define an endpoint is typically defined in the endpoint’s contract. You can use the configuration element’s to override the information in the contract. You can also use the configuration elements to provide information that is not provided in the contract.
You must use the configuration elements to activate advanced features such as WS-RM. This is done by providing child elements to the endpoint’s configuration element. Note that when dealing with endpoints developed using a Java-first approach it is likely that the SEI serving as the endpoint’s contract is lacking information about the type of binding and transport to use.
17.1. Configuring Service Providers
17.1.1. Elements for Configuring Service Providers
Apache CXF has two elements that can be used to configure a service provider:
The differences between the two elements are largely internal to the runtime. The jaxws:endpoint
element injects properties into the org.apache.cxf.jaxws.EndpointImpl
object created to support a service endpoint. The jaxws:server
element injects properties into the org.apache.cxf.jaxws.support.JaxWsServerFactoryBean
object created to support the endpoint. The EndpointImpl
object passes the configuration data to the JaxWsServerFactoryBean
object. The JaxWsServerFactoryBean
object is used to create the actual service object. Because either configuration element will configure a service endpoint, you can choose based on the syntax you prefer.
17.1.2. Using the jaxws:endpoint Element
Overview
The jaxws:endpoint
element is the default element for configuring JAX-WS service providers. Its attributes and children specify all of the information needed to instantiate a service provider. Many of the attributes map to information in the service’s contract. The children are used to configure interceptors and other advanced features.
Identifying the endpoint being configured
For the runtime to apply the configuration to the proper service provider, it must be able to identify it. The basic means for identifying a service provider is to specify the class that implements the endpoint. This is done using the jaxws:endpoint
element’s implementor
attribute.
For instances where different endpoint’s share a common implementation, it is possible to provide different configuration for each endpoint. There are two approaches for distinguishing a specific endpoint in configuration:
a combination of the
serviceName
attribute and theendpointName
attributeThe
serviceName
attribute specifies thewsdl:service
element defining the service’s endpoint. TheendpointName
attribute specifies the specificwsdl:port
element defining the service’s endpoint. Both attributes are specified as QNames using the formatns:name
. ns is the namespace of the element and name is the value of the element’sname
attribute.NoteIf the
wsdl:service
element only has onewsdl:port
element, theendpointName
attribute can be omitted.the
name
attributeThe
name
attribute specifies the QName of the specificwsdl:port
element defining the service’s endpoint. The QName is provided in the format{ns}localPart
. ns is the namespace of thewsdl:port
element and localPart is the value of thewsdl:port
element’sname
attribute.
Attributes
The attributes of the jaxws:endpoint
element configure the basic properties of the endpoint. These properties include the address of the endpoint, the class that implements the endpoint, and the bus
that hosts the endpoint.
Table 17.1, “Attributes for Configuring a JAX-WS Service Provider Using the jaxws:endpoint Element” describes the attribute of the jaxws:endpoint
element.
Attribute | Description |
---|---|
Specifies a unique identifier that other configuration elements can use to refer to the endpoint. | |
Specifies the class implementing the service. You can specify the implementation class using either the class name or an ID reference to a Spring bean configuring the implementation class. This class must be on the classpath. | |
Specifies the class implementing the service. This attribute is useful when the value provided to the | |
Specifies the address of an HTTP endpoint. This value overrides the value specified in the services contract. | |
Specifies the location of the endpoint’s WSDL contract. The WSDL contract’s location is relative to the folder from which the service is deployed. | |
Specifies the value of the service’s | |
Specifies the value of the service’s | |
Specifies if the service should be automatically published. If this is set to | |
Specifies the ID of the Spring bean configuring the bus used to manage the service endpoint. This is useful when configuring several endpoints to use a common set of features. | |
Specifies the ID of the message binding the service uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs. | |
Specifies the stringified QName of the service’s | |
Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is | |
Specifies a list of beans that the endpoint depends on being instantiated before it can be instantiated. | |
Specifies that the user created that bean using Apache CXF APIs, such as
The default is
Setting this to
| |
The URL that is placed in the |
In addition to the attributes listed in Table 17.1, “Attributes for Configuring a JAX-WS Service Provider Using the jaxws:endpoint Element”, you might need to use multiple xmlns:shortName
attributes to declare the namespaces used by the endpointName
and serviceName
attributes.
Example
Example 17.1, “Simple JAX-WS Endpoint Configuration” shows the configuration for a JAX-WS endpoint that specifies the address where the endpoint is published. The example assumes that you want to use the defaults for all other values or that the implementation has specified values in the annotations.
Example 17.1. Simple JAX-WS Endpoint Configuration
<beans ... xmlns:jaxws="http://cxf.apache.org/jaxws" ... schemaLocation="... http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd ..."> <jaxws:endpoint id="example" implementor="org.apache.cxf.example.DemoImpl" address="http://localhost:8080/demo" /> </beans>
Example 17.2, “JAX-WS Endpoint Configuration with a Service Name” shows the configuration for a JAX-WS endpoint whose contract contains two service definitions. In this case, you must specify which service definition to instantiate using the serviceName
attribute.
Example 17.2. JAX-WS Endpoint Configuration with a Service Name
<beans ... xmlns:jaxws="http://cxf.apache.org/jaxws" ... schemaLocation="... http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd ..."> <jaxws:endpoint id="example2" implementor="org.apache.cxf.example.DemoImpl" serviceName="samp:demoService2" xmlns:samp="http://org.apache.cxf/wsdl/example" /> </beans>
The xmlns:samp
attribute specifies the namespace in which the WSDL service
element is defined.
Example 17.3, “JAX-WS Endpoint Configuration with with HTTP/2 enabled” shows the configuration for a JAX-WS endpoint that specifies the address with HTTP/2 enabled.
Configuring HTTP/2 for Apache CXF
HTTP/2 is supported when using the standalone Apache CXF Undertow transport (http-undertow
) on Apache Karaf. To enable the HTTP/2 protocol you must set the jaxws:endpoint
element’s address
attribute as an absolute URL and set the org.apache.cxf.transports.http_undertow.EnableHttp2
property as true
.
This HTTP/2 implementation only supports server side HTTP/2 transport with plain HTTP or HTTPS.
Example 17.3. JAX-WS Endpoint Configuration with with HTTP/2 enabled
<beans ... xmlns:jaxws="http://cxf.apache.org/jaxws" ... schemaLocation="... http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd ..."> <cxf:bus> <cxf:properties> <entry key="org.apache.cxf.transports.http_undertow.EnableHttp2" value="true"/> </cxf:properties> </cxf:bus> <jaxws:endpoint id="example3" implementor="org.apache.cxf.example.DemoImpl" address="http://localhost:8080/demo" /> </jaxws:endpoint> </beans>
For improved performance, Red Hat recommends using the servlet transport on Apache Karaf (pax-web-undertow
) which enables centralized configuration and tuning of the web container, however, pax-web-undertow
does not support the HTTP/2 transport protocol.
17.1.3. Using the jaxws:server Element
Overview
The jaxws:server
element is an element for configuring JAX-WS service providers. It injects the configuration information into the org.apache.cxf.jaxws.support.JaxWsServerFactoryBean
. This is a Apache CXF specific object. If you are using a pure Spring approach to building your services, you will not be forced to use Apache CXF specific APIs to interact with the service.
The attributes and children of the jaxws:server
element specify all of the information needed to instantiate a service provider. The attributes specify the information that is required to instantiate an endpoint. The children are used to configure interceptors and other advanced features.
Identifying the endpoint being configured
In order for the runtime to apply the configuration to the proper service provider, it must be able to identify it. The basic means for identifying a service provider is to specify the class that implements the endpoint. This is done using the jaxws:server
element’s serviceBean
attribute.
For instances where different endpoint’s share a common implementation, it is possible to provide different configuration for each endpoint. There are two approaches for distinguishing a specific endpoint in configuration:
a combination of the
serviceName
attribute and theendpointName
attributeThe
serviceName
attribute specifies thewsdl:service
element defining the service’s endpoint. TheendpointName
attribute specifies the specificwsdl:port
element defining the service’s endpoint. Both attributes are specified as QNames using the formatns:name
. ns is the namespace of the element and name is the value of the element’sname
attribute.NoteIf the
wsdl:service
element only has onewsdl:port
element, theendpointName
attribute can be omitted.the
name
attributeThe
name
attribute specifies the QName of the specificwsdl:port
element defining the service’s endpoint. The QName is provided in the format{ns}localPart
. ns is the namespace of thewsdl:port
element and localPart is the value of thewsdl:port
element’sname
attribute.
Attributes
The attributes of the jaxws:server
element configure the basic properties of the endpoint. These properties include the address of the endpoint, the class that implements the endpoint, and the bus
that hosts the endpoint.
Table 17.2, “Attributes for Configuring a JAX-WS Service Provider Using the jaxws:server Element” describes the attribute of the jaxws:server
element.
Attribute | Description |
---|---|
Specifies a unique identifier that other configuration elements can use to refer to the endpoint. | |
Specifies the class implementing the service. You can specify the implementation class using either the class name or an ID reference to a Spring bean configuring the implementation class. This class must be on the classpath. | |
Specifies the class implementing the service. This attribute is useful when the value provided to the | |
Specifies the address of an HTTP endpoint. This value will override the value specified in the services contract. | |
Specifies the location of the endpoint’s WSDL contract. The WSDL contract’s location is relative to the folder from which the service is deployed. | |
Specifies the value of the service’s | |
Specifies the value of the service’s | |
Specifies if the service should be automatically published. If this is set to | |
Specifies the ID of the Spring bean configuring the bus used to manage the service endpoint. This is useful when configuring several endpoints to use a common set of features. | |
Specifies the ID of the message binding the service uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs. | |
Specifies the stringified QName of the service’s | |
Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is | |
Specifies a list of beans that the endpoint depends on being instantiated before the endpoint can be instantiated. | |
Specifies that the user created that bean using Apache CXF APIs, such as
The default is
Setting this to
|
In addition to the attributes listed in Table 17.2, “Attributes for Configuring a JAX-WS Service Provider Using the jaxws:server Element”, you might need to use multiple xmlns:shortName
attributes to declare the namespaces used by the endpointName
and serviceName
attributes.
Example
Example 17.4, “Simple JAX-WS Server Configuration” shows the configuration for a JAX-WS endpoint that specifies the address where the endpoint is published.
Example 17.4. Simple JAX-WS Server Configuration
<beans ... xmlns:jaxws="http://cxf.apache.org/jaxws" ... schemaLocation="... http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd ..."> <jaxws:server id="exampleServer" serviceBean="org.apache.cxf.example.DemoImpl" address="http://localhost:8080/demo" /> </beans>
17.1.4. Adding Functionality to Service Providers
Overview
The jaxws:endpoint
and the jaxws:server
elements provide the basic configuration information needed to instantiate a service provider. To add functionality to your service provider or to perform advanced configuration you must add child elements to the configuration.
Child elements allow you to do the following:
Elements
Table 17.3, “Elements Used to Configure JAX-WS Service Providers” describes the child elements that jaxws:endpoint
supports.
Element | Description |
---|---|
Specifies a list of JAX-WS Handler implementations for processing messages. For more information on JAX-WS Handler implementations see Chapter 43, Writing Handlers. | |
Specifies a list of interceptors that process inbound requests. For more information see Part VII, “Developing Apache CXF Interceptors”. | |
Specifies a list of interceptors that process inbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”. | |
Specifies a list of interceptors that process outbound replies. For more information see Part VII, “Developing Apache CXF Interceptors”. | |
Specifies a list of interceptors that process outbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”. | |
Specifies a bean configuring the message binding used by the endpoint. Message bindings are configured using implementations of the | |
| Specifies the class implementing the data binding used by the endpoint. This is specified using an embedded bean definition. |
Specifies a Java executor that is used for the service. This is specified using an embedded bean definition. | |
Specifies a list of beans that configure advanced features of Apache CXF. You can provide either a list of bean references or a list of embedded beans. | |
Specifies an implementation of the org.apache.cxf.service.Invoker interface used by the service. [c] | |
Specifies a Spring map of properties that are passed along to the endpoint. These properties can be used to control features like enabling MTOM support. | |
Specifies a bean configuring the | |
[a]
The SOAP binding is configured using the soap:soapBinding bean.
[c]
The Invoker implementation controls how a service is invoked. For example, it controls whether each request is handled by a new instance of the service implementation or if state is preserved across invocations.
|
17.1.5. Enable Schema Validation on a JAX-WS Endpoint
Overview
You can set the schema-validation-enabled
property to enable schema validation on a jaxws:endpoint
element or on a jaxws:server
element. When schema validation is enabled, the messages sent between client and server are checked for conformity to the schema. By default, schema validation is turned off, because it has a significant impact on performance.
Example
To enable schema validation on a JAX-WS endpoint, set the schema-validation-enabled
property in the jaxws:properties
child element of the jaxws:endpoint
element or of the jaxws:server
element. For example, to enable schema validation on a jaxws:endpoint
element:
<jaxws:endpoint name="{http://apache.org/hello_world_soap_http}SoapPort" wsdlLocation="wsdl/hello_world.wsdl" createdFromAPI="true"> <jaxws:properties> <entry key="schema-validation-enabled" value="BOTH" /> </jaxws:properties> </jaxws:endpoint>
For the list of allowed values of the schema-validation-enabled
property, see Section 24.3.4.7, “Schema Validation Type Values”.
17.2. Configuring Consumer Endpoints
Overview
JAX-WS consumer endpoints are configured using the jaxws:client
element. The element’s attributes provide the basic information necessary to create a consumer.
To add other functionality, like WS-RM, to the consumer you add children to the jaxws:client
element. Child elements are also used to configure the endpoint’s logging behavior and to inject other properties into the endpoint’s implementation.
Basic Configuration Properties
The attributes described in Table 17.4, “Attributes Used to Configure a JAX-WS Consumer” provide the basic information necessary to configure a JAX-WS consumer. You only need to provide values for the specific properties you want to configure. Most of the properties have sensible defaults, or they rely on information provided by the endpoint’s contract.
Attribute | Description |
---|---|
Specifies the HTTP address of the endpoint where the consumer will make requests. This value overrides the value set in the contract. | |
Specifies the ID of the message binding the consumer uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs. | |
Specifies the ID of the Spring bean configuring the bus managing the endpoint. | |
Specifies the value of the | |
Specifies the value of the | |
Specifies the username used for simple username/password authentication. | |
Specifies the password used for simple username/password authentication. | |
Specifies the name of the service endpoint interface(SEI). | |
Specifies the location of the endpoint’s WSDL contract. The WSDL contract’s location is relative to the folder from which the client is deployed. | |
Specifies the stringified QName of the | |
Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is | |
Specifies a list of beans that the endpoint depends on being instantiated before it can be instantiated. | |
Specifies that the user created that bean using Apache CXF APIs like
The default is
Setting this to
|
In addition to the attributes listed in Table 17.4, “Attributes Used to Configure a JAX-WS Consumer”, it might be necessary to use multiple xmlns:shortName
attributes to declare the namespaces used by the endpointName
and the serviceName
attributes.
Adding functionality
To add functionality to your consumer or to perform advanced configuration, you must add child elements to the configuration.
Child elements allow you to do the following:
Table 17.5, “Elements For Configuring a Consumer Endpoint” describes the child element’s you can use to configure a JAX-WS consumer.
Element | Description |
---|---|
Specifies a bean configuring the message binding used by the endpoint. Message bindings are configured using implementations of the | |
Specifies the class implementing the data binding used by the endpoint. You specify this using an embedded bean definition. The class implementing the JAXB data binding is | |
Specifies a list of beans that configure advanced features of Apache CXF. You can provide either a list of bean references or a list of embedded beans. | |
Specifies a list of JAX-WS Handler implementations for processing messages. For more information in JAX-WS Handler implementations see Chapter 43, Writing Handlers. | |
Specifies a list of interceptors that process inbound responses. For more information see Part VII, “Developing Apache CXF Interceptors”. | |
Specifies a list of interceptors that process inbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”. | |
Specifies a list of interceptors that process outbound requests. For more information see Part VII, “Developing Apache CXF Interceptors”. | |
Specifies a list of interceptors that process outbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”. | |
Specifies a map of properties that are passed to the endpoint. | |
Specifies an org.apache.cxf.endpoint.ConduitSelector implementation for the client to use. A ConduitSelector implementation will override the default process used to select the | |
[a]
The SOAP binding is configured using the soap:soapBinding bean.
|
Example
Example 17.5, “Simple Consumer Configuration” shows a simple consumer configuration.
Example 17.5. Simple Consumer Configuration
<beans ... xmlns:jaxws="http://cxf.apache.org/jaxws" ... schemaLocation="... http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd ..."> <jaxws:client id="bookClient" serviceClass="org.apache.cxf.demo.BookClientImpl" address="http://localhost:8080/books"/> ... </beans>
Enable schema validation on a JAX-WS consumer
To enable schema validation on a JAX-WS consumer, set the schema-validation-enabled
property in the jaxws:properties
child element of the jaxws:client
element—for example:
<jaxws:client name="{http://apache.org/hello_world_soap_http}SoapPort" createdFromAPI="true"> <jaxws:properties> <entry key="schema-validation-enabled" value="BOTH" /> </jaxws:properties> </jaxws:client>
For the list of allowed values of the schema-validation-enabled
property, see Section 24.3.4.7, “Schema Validation Type Values”.
Chapter 18. Configuring JAX-RS Endpoints
Abstract
This chapter explains how to instantiate and configure JAX-RS server endpoints in Blueprint XML and in Spring XML, and also how to instantiate and configure JAX-RS client endpoints (client proxy beans) in XML
18.1. Configuring JAX-RS Server Endpoints
18.1.1. Defining a JAX-RS Server Endpoint
Basic server endpoint definition
To define a JAX-RS server endpoint in XML, you need to specify at least the following:
-
A
jaxrs:server
element, which is used to define the endpoint in XML. Note that thejaxrs:
namespace prefix maps to different namespaces in Blueprint and in Spring respectively. The base URL of the JAX-RS service, using the
address
attribute of thejaxrs:server
element. Note that there are two different ways of specifying the address URL, which affects how the endpoint gets deployed:As a relative URL—for example,
/customers
. In this case, the endpoint is deployed into the default HTTP container, and the endpoint’s base URL is implicitly obtained by combining the CXF servlet base URL with the specified relative URL.For example, if you deploy a JAX-RS endpoint to the Fuse container, the specified
/customers
URL would get resolved to the URL,http://Hostname:8181/cxf/customers
(assuming that the container is using the default8181
port).-
As an absolute URL — for example,
http://0.0.0.0:8200/cxf/customers
. In this case, a new HTTP listener port is opened for the JAX-RS endpoint (if it is not already open). For example, in the context of Fuse, a new Undertow container would implicitly be created to host the JAX-RS endpoint. The special IP address,0.0.0.0
, acts as a wildcard, matching any of the hostnames assigned to the current host (which can be useful on multi-homed host machines).
-
One or more JAX-RS root resource classes, which provide the implementation of the JAX-RS service. The simplest way to specify the resource classes is to list them inside a
jaxrs:serviceBeans
element.
Blueprint example
The following Blueprint XML example shows how to define a JAX-RS endpoint, which specifies the relative address, /customers
(so that it deploys into the default HTTP container) and is implemented by the service.CustomerService
resource class:
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs" xmlns:cxf="http://cxf.apache.org/blueprint/core" xsi:schemaLocation=" http://www.osgi.org/xmlns/blueprint/v1.0.0 https://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd "> <cxf:bus> <cxf:features> <cxf:logging/> </cxf:features> </cxf:bus> <jaxrs:server id="customerService" address="/customers"> <jaxrs:serviceBeans> <ref component-id="serviceBean" /> </jaxrs:serviceBeans> </jaxrs:server> <bean id="serviceBean" class="service.CustomerService"/> </blueprint>
Blueprint XML namespaces
To define a JAX-RS endpoint in Blueprint, you typically require at least the following XML namespaces:
Prefix | Namespace |
---|---|
(default) | |
| |
|
Spring example
The following Spring XML example shows how to define a JAX-RS endpoint, which specifies the relative address, /customers
(so that it deploys into the default HTTP container) and is implemented by the service.CustomerService
resource class:
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxrs="http://cxf.apache.org/jaxrs" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd"> <jaxrs:server id="customerService" address="/customers"> <jaxrs:serviceBeans> <ref bean="serviceBean"/> </jaxrs:serviceBeans> </jaxrs:server> <bean id="serviceBean" class="service.CustomerService"/> </beans>
Spring XML namespaces
To define a JAX-RS endpoint in Spring, you typically require at least the following XML namespaces:
Prefix | Namespace |
---|---|
(default) | |
| |
|
Auto-discovery in Spring XML
(Spring only) Instead of specifying the JAX-RS root resource classes explicitly, Spring XML enables you to configure auto-discovery, so that specific Java packages are searched for resource classes (classes annotated by @Path
) and all of the discovered resource classes are automatically attached to the endpoint. In this case, you need to specify just the address
attribute and the basePackages
attribute in the jaxrs:server
element.
For example, to define a JAX-RS endpoint which uses all of the JAX-RS resource classes under the a.b.c
Java package, you can define the endpoint in Spring XML, as follows:
<jaxrs:server address="/customers" basePackages="a.b.c"/>
The auto-discovery mechanism also discovers and installs into the endpoint any JAX-RS provider classes that it finds under the specified Java packages.
Lifecycle management in Spring XML
(Spring only) Spring XML enables you to control the lifecycle of beans by setting the scope
attribute on a bean
element. The following scope values are supported by Spring:
singleton
- (Default) Creates a single bean instance, which is used everywhere and lasts for the entire lifetime of the Spring container.
prototype
-
Creates a new bean instance every time the bean is injected into another bean or when a bean is obtained by invoking
getBean()
on the bean registry. request
- (Only available in a Web-aware container) Creates a new bean instance for every request invoked on the bean.
session
- (Only available in a Web-aware container) Creates a new bean for the lifetime of a single HTTP session.
globalSession
- (Only available in a Web-aware container) Creates a new bean for the lifetime of a single HTTP session that is shared between portlets.
For more details about Spring scopes, please consult the Spring framework documentation on Bean scopes.
Note that Spring scopes do not work properly, if you specify JAX-RS resource beans through the jaxrs:serviceBeans
element. If you specify the scope
attribute on the resource beans in this case, the scope
attribute is effectively ignored.
In order to make bean scopes work properly within a JAX-RS server endpoint, you require a level of indirection that is provided by a service factory. The simplest way to configure bean scopes is to specify resource beans using the beanNames
attribute on the jaxrs:server
element, as follows:
<beans ... > <jaxrs:server id="customerService" address="/service1" beanNames="customerBean1 customerBean2"/> <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/> <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2" scope="prototype"/> </beans>
Where the preceding example configures two resource beans, customerBean1
and customerBean2
. The beanNames
attribute is specified as a space-separated list of resource bean IDs.
For the ultimate degree of flexibility, you have the option of defining service factory objects explicitly, when you configure the JAX-RS server endpoint, using the jaxrs:serviceFactories
element. This more verbose approach has the advantage that you can replace the default service factory implementation with your custom implementation, thus giving you ultimate control over the bean lifecycle. The following example shows how to configure the two resource beans, customerBean1
and customerBean2
, using this approach:
<beans ... > <jaxrs:server id="customerService" address="/service1"> <jaxrs:serviceFactories> <ref bean="sfactory1" /> <ref bean="sfactory2" /> </jaxrs:serviceFactories> </jaxrs:server> <bean id="sfactory1" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory"> <property name="beanId" value="customerBean1"/> </bean> <bean id="sfactory2" class="org.apache.cxf.jaxrs.spring.SpringResourceFactory"> <property name="beanId" value="customerBean2"/> </bean> <bean id="customerBean1" class="demo.jaxrs.server.CustomerRootResource1" scope="prototype"/> <bean id="customerBean2" class="demo.jaxrs.server.CustomerRootResource2" scope="prototype"/> </beans>
If you specify a non-singleton lifecycle, it is often a good idea to implement and register a org.apache.cxf.service.Invoker bean (where the instance can be registered by referencing it from a jaxrs:server/jaxrs:invoker
element).
Attaching a WADL document
You can optionally associate a WADL document with the JAX-RS server endpoint using the docLocation
attribute on the jaxrs:server
element. For example:
<jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl"> <jaxrs:serviceBeans> <bean class="org.bar.generated.BookStore"/> </jaxrs:serviceBeans> </jaxrs:server>
Schema validation
If you have some external XML schemas, for describing message content in JAX-B format, you can associate these external schemas with the JAX-RS server endpoint through the jaxrs:schemaLocations
element.
For example, if you have associated the server endpoint with a WADL document and you also want to enable schema validation on incoming messages, you can specify associated XML schema files as follows:
<jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl"> <jaxrs:serviceBeans> <bean class="org.bar.generated.BookStore"/> </jaxrs:serviceBeans> <jaxrs:schemaLocations> <jaxrs:schemaLocation>classpath:/schemas/a.xsd</jaxrs:schemaLocation> <jaxrs:schemaLocation>classpath:/schemas/b.xsd</jaxrs:schemaLocation> </jaxrs:schemaLocations> </jaxrs:server>
Alternatively, if you want to include all of the schema files, *.xsd
, in a given directory, you can just specify the directory name, as follows:
<jaxrs:server address="/rest" docLocation="wadl/bookStore.wadl"> <jaxrs:serviceBeans> <bean class="org.bar.generated.BookStore"/> </jaxrs:serviceBeans> <jaxrs:schemaLocations> <jaxrs:schemaLocation>classpath:/schemas/</jaxrs:schemaLocation> </jaxrs:schemaLocations> </jaxrs:server>
Specifying schemas in this way is generally useful for any kind of functionality that requires access to the JAX-B schemas.
Specifying the data binding
You can use the jaxrs:dataBinding
element to specify the data binding that encodes the message body in request and reply messages. For example, to specify the JAX-B data binding, you could configure a JAX-RS endpoint as follows:
<jaxrs:server id="jaxbbook" address="/jaxb"> <jaxrs:serviceBeans> <ref bean="serviceBean" /> </jaxrs:serviceBeans> <jaxrs:dataBinding> <bean class="org.apache.cxf.jaxb.JAXBDataBinding"/> </jaxrs:dataBinding> </jaxrs:server>>
Or to specify the Aegis data binding, you could configure a JAX-RS endpoint as follows:
<jaxrs:server id="aegisbook" address="/aegis"> <jaxrs:serviceBeans> <ref bean="serviceBean" /> </jaxrs:serviceBeans> <jaxrs:dataBinding> <bean class="org.apache.cxf.aegis.databinding.AegisDatabinding"> <property name="aegisContext"> <bean class="org.apache.cxf.aegis.AegisContext"> <property name="writeXsiTypes" value="true"/> </bean> </property> </bean> </jaxrs:dataBinding> </jaxrs:server>
Using the JMS transport
It is possible to configure JAX-RS to use a JMS messaging library as a transport protocol, instead of HTTP. Because JMS itself is not a transport protocol, the actual messaging protocol depends on the particular JMS implementation that you configure.
For example, the following Spring XML example shows how to configure a JAX-RS server endpoint to use the JMS transport protocol:
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jms="http://cxf.apache.org/transports/jms" xmlns:jaxrs="http://cxf.apache.org/jaxrs" xsi:schemaLocation=" http://cxf.apache.org/transports/jms http://cxf.apache.org/schemas/configuration/jms.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://cxf.apache.org/jaxrs http://cxf.apache.org/schemas/jaxrs.xsd"> <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"/> <bean id="ConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory"> <property name="brokerURL" value="tcp://localhost:${testutil.ports.EmbeddedJMSBrokerLauncher}" /> </bean> <jaxrs:server xmlns:s="http://books.com" serviceName="s:BookService" transportId= "http://cxf.apache.org/transports/jms" address="jms:queue:test.jmstransport.text?replyToName=test.jmstransport.response"> <jaxrs:serviceBeans> <bean class="org.apache.cxf.systest.jaxrs.JMSBookStore"/> </jaxrs:serviceBeans> </jaxrs:server> </beans>
Note the following points about the preceding example:
-
JMS implementation—the JMS implementation is provided by the
ConnectionFactory
bean, which instantiates an Apache ActiveMQ connection factory object. After you instantiate the connection factory, it is automatically installed as the default JMS implementation layer. -
JMS conduit or destination object—Apache CXF implicitly instantiates a JMS conduit object (to represent a JMS consumer) or a JMS destination object (to represent a JMS provider). This object must be uniquely identified by a QName, which is defined through the attribute setttings
xmlns:s="http://books.com"
(defining the namespace prefix) andserviceName="s:BookService"
(defining the QName). -
Transport ID—to select the JMS transport, the
transportId
attribute must be set tohttp://cxf.apache.org/transports/jms
. -
JMS address—the
jaxrs:server/@address
attribute uses a standardized syntax to specify the JMS queue or JMS topic to send to. For details of this syntax, see https://tools.ietf.org/id/draft-merrick-jms-uri-06.txt.
Extension mappings and language mappings
A JAX-RS server endpoint can be configured so that it automatically maps a file suffix (appearing in the URL) to a MIME content type header, and maps a language suffix to a language type header. For example, consider a HTTP request of the following form:
GET /resource.xml
You can configure the JAX-RS server endpoint to map the .xml
suffix automatically, as follows:
<jaxrs:server id="customerService" address="/"> <jaxrs:serviceBeans> <bean class="org.apache.cxf.jaxrs.systests.CustomerService" /> </jaxrs:serviceBeans> <jaxrs:extensionMappings> <entry key="json" value="application/json"/> <entry key="xml" value="application/xml"/> </jaxrs:extensionMappings> </jaxrs:server>
When the preceding server endpoint receives the HTTP request, it automatically creates a new content type header of type, application/xml
, and strips the .xml
suffix from the resource URL.
For the language mapping, consider a HTTP request of the following form:
GET /resource.en
You can configure the JAX-RS server endpoint to map the .en
suffix automatically, as follows:
<jaxrs:server id="customerService" address="/"> <jaxrs:serviceBeans> <bean class="org.apache.cxf.jaxrs.systests.CustomerService" /> </jaxrs:serviceBeans> <jaxrs:languageMappings> <entry key="en" value="en-gb"/> </jaxrs:languageMappings> </jaxrs:server>
When the preceding server endpoint receives the HTTP request, it automatically creates a new accept language header with the value, en-gb
, and strips the .en
suffix from the resource URL.
18.1.2. jaxrs:server Attributes
Attributes
Table 18.1, “JAX-RS Server Endpoint Attributes” describes the attributes available on the jaxrs:server
element.
Attribute | Description |
---|---|
| Specifies a unique identifier that other configuration elements can use to refer to the endpoint. |
| Specifies the address of an HTTP endpoint. This value will override the value specified in the services contract. |
| (Spring only) Enables auto-discovery, by specifying a comma-separated list of Java packages, which are searched to discover JAX-RS root resource classes and/or JAX-RS provider classes. |
|
Specifies a space-separated list of bean IDs of JAX-RS root resource beans. In the context of Spring XML, it is possible to define a root resource beans' lifecycle by setting the |
| Specifies the ID of the message binding the service uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs. |
| Specifies the ID of the Spring bean configuring the bus used to manage the service endpoint. This is useful when configuring several endpoints to use a common set of features. |
| Specifies the location of an external WADL document. |
|
Specifies a model schema as a classpath resource (for example, a URL of the form |
|
Specifies if the service should be automatically published. If set to |
|
Specifies the URL base address, which gets inserted into the |
|
(Spring only) Specifies the service annotation class name for auto-discovery in Spring. When used in combination with the |
|
Specifies the name of a JAX-RS root resource class (which implements a JAX-RS service). In this case, the class is instantiated by Apache CXF, not by Blueprint or Spring. If you want to instantiate the class in Blueprint or Spring, use the |
|
Specifies the service QName (using the format |
|
If |
|
For selecting a non-standard transport layer (in place of HTTP). In particular, you can select the JMS transport by setting this property to |
|
(Spring only) Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is |
| (Spring only) Specifies a list of beans that the endpoint depends on being instantiated before the endpoint can be instantiated. |
18.1.3. jaxrs:server Child Elements
Child elements
Table 18.2, “JAX-RS Server Endpoint Child Elements” describes the child elements of the jaxrs:server
element.
Element | Description |
---|---|
|
Specifies a Java |
| Specifies a list of beans that configure advanced features of Apache CXF. You can provide either a list of bean references or a list of embedded beans. |
| Not used. |
| Specifies the class implementing the data binding used by the endpoint. This is specified using an embedded bean definition. For more details, see the section called “Specifying the data binding”. |
| Specifies a list of interceptors that process inbound requests. For more information see Part VII, “Developing Apache CXF Interceptors”. |
| Specifies a list of interceptors that process inbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”. |
| Specifies a list of interceptors that process outbound replies. For more information see Part VII, “Developing Apache CXF Interceptors”. |
| Specifies a list of interceptors that process outbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”. |
| Specifies an implementation of the org.apache.cxf.service.Invoker interface used by the service. [a] |
|
Provides you with the maximum degree of control over the lifecycle of the JAX-RS root resources associated with this endpoint. The children of this element (which must be instances of |
| Specifies a Spring map of properties that are passed along to the endpoint. These properties can be used to control features like enabling MTOM support. |
|
The children of this element are instances of ( |
|
Consists of a list of references to one or more |
|
Defines a resource model directly in this endpoint (that is, this |
|
Enables you to register one or more custom JAX-RS providers with this endpoint. The children of this element are instances of ( |
|
When the URL of a REST invocation ends in a file extension, you can use this element to associate it automatically with a particular content type. For example, the |
|
When the URL of a REST invocation ends in a language suffix, you can use this element to map this to a particular language. For example, the |
|
Specifies one or more XML schemas used for validating XML message content. This element can contain one or more |
| Enables you to register a custom resource comparator, which implements the algorithm used to match an incoming URL path to a particular resource class or method. |
|
(Blueprint only) Can be used instead of the |
[a]
The Invoker implementation controls how a service is invoked. For example, it controls whether each request is handled by a new instance of the service implementation or if state is preserved across invocations.
|
18.2. Configuring JAX-RS Client Endpoints
18.2.1. Defining a JAX-RS Client Endpoint
Injecting client proxies
The main point of instantiating a client proxy bean in an XML language (Blueprint XML or Spring XML) is in order to inject it into another bean, which can then use the client proxy to invoke the REST service. To create a client proxy bean in XML, use the jaxrs:client
element.
Namespaces
The JAX-RS client endpoint is defined using a different XML namespace from the server endpoint. The following table shows which namespace to use for which XML language:
XML Language | Namespace for client endpoint |
---|---|
Blueprint | |
Spring |
Basic client endpoint definition
The following example shows how to create a client proxy bean in Blueprint XML or Spring XML:
<jaxrs:client id="restClient" address="http://localhost:8080/test/services/rest" serviceClass="org.apache.cxf.systest.jaxrs.BookStoreJaxrsJaxws"/>
Where you must set the following attributes to define the basic client endpoint:
id
- The bean ID of the client proxy can be used to inject the client proxy into other beans in your XML configuration.
address
- The address attribute specifies the base URL of the REST invocations.
serviceClass
-
The
serviceClass
attribute provides a description of the REST service by specifying a root resource class (annotated by@Path
). In fact, this is a server class, but it is not used directly by the client. The specified class is used only for its metadata (through Java reflection and JAX-RS annotations), which is used to construct the client proxy dynamically.
Specifying headers
You can add HTTP headers to the client proxy’s invocations using the jaxrs:headers
child elements, as follows:
<jaxrs:client id="restClient" address="http://localhost:8080/test/services/rest" serviceClass="org.apache.cxf.systest.jaxrs.BookStoreJaxrsJaxws" inheritHeaders="true"> <jaxrs:headers> <entry key="Accept" value="text/xml"/> </jaxrs:headers> </jaxrs:client>
18.2.2. jaxrs:client Attributes
Attributes
Table 18.3, “JAX-RS Client Endpoint Attributes” describes the attributes available on the jaxrs:client
element.
Attribute | Description |
---|---|
| Specifies the HTTP address of the endpoint where the consumer will make requests. This value overrides the value set in the contract. |
| Specifies the ID of the message binding the consumer uses. A list of valid binding IDs is provided in Chapter 23, Apache CXF Binding IDs. |
| Specifies the ID of the Spring bean configuring the bus managing the endpoint. |
|
Specifies whether the headers set for this proxy will be inherited, if a subresource proxy is created from this proxy. Default is |
| Specifies the username used for simple username/password authentication. |
| Specifies the password used for simple username/password authentication. |
|
Specifies a model schema as a classpath resource (for example, a URL of the form |
|
Specifies the name of a service interface or a resource class (that is annotated with |
|
Specifies the service QName (using the format |
|
Specifies whether or not the client proxy is thread-safe. Default is |
|
For selecting a non-standard transport layer (in place of HTTP). In particular, you can select the JMS transport by setting this property to |
|
(Spring only) Specifies if the bean is an abstract bean. Abstract beans act as parents for concrete bean definitions and are not instantiated. The default is |
| (Spring only) Specifies a list of beans that the endpoint depends on being instantiated before it can be instantiated. |
18.2.3. jaxrs:client Child Elements
Child elements
Table 18.4, “JAX-RS Client Endpoint Child Elements” describes the child elements of the jaxrs:client
element.
Element | Description |
---|---|
| |
| Specifies a list of beans that configure advanced features of Apache CXF. You can provide either a list of bean references or a list of embedded beans. |
| Not used. |
| Specifies the class implementing the data binding used by the endpoint. This is specified using an embedded bean definition. For more details, see the section called “Specifying the data binding”. |
| Specifies a list of interceptors that process inbound responses. For more information see Part VII, “Developing Apache CXF Interceptors”. |
| Specifies a list of interceptors that process inbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”. |
| Specifies a list of interceptors that process outbound requests. For more information see Part VII, “Developing Apache CXF Interceptors”. |
| Specifies a list of interceptors that process outbound fault messages. For more information see Part VII, “Developing Apache CXF Interceptors”. |
| Specifies a map of properties that are passed to the endpoint. |
|
Enables you to register one or more custom JAX-RS providers with this endpoint. The children of this element are instances of ( |
|
Consists of a list of references to one or more |
|
Defines a resource model directly in this endpoint (that is, a |
| Used for setting headers on the outgoing message. For details, see the section called “Specifying headers”. |
|
Specifies one or more XML schemas used for validating XML message content. This element can contain one or more |
18.3. Defining REST Services with the Model Schema
RESTful services without annotations
The JAX-RS model schema makes it possible to define RESTful services without annotating Java classes. That is, instead of adding annotations like @Path
, @PathParam
, @Consumes
, @Produces
, and so on, directly to a Java class (or interface), you can provide all of the relevant REST metadata in a separate XML file, using the model schema. This can be useful, for example, in cases where you are unable to modify the Java source that implements the service.
Example model schema
Example 18.1, “Sample JAX-RS Model Schema” shows an example of a model schema that defines service metadata for the BookStoreNoAnnotations
root resource class.
Example 18.1. Sample JAX-RS Model Schema
<model xmlns="http://cxf.apache.org/jaxrs"> <resource name="org.apache.cxf.systest.jaxrs.BookStoreNoAnnotations" path="bookstore" produces="application/json" consumes="application/json"> <operation name="getBook" verb="GET" path="/books/{id}" produces="application/xml"> <param name="id" type="PATH"/> </operation> <operation name="getBookChapter" path="/books/{id}/chapter"> <param name="id" type="PATH"/> </operation> <operation name="updateBook" verb="PUT"> <param name="book" type="REQUEST_BODY"/> </operation> </resource> <resource name="org.apache.cxf.systest.jaxrs.ChapterNoAnnotations"> <operation name="getItself" verb="GET"/> <operation name="updateChapter" verb="PUT" consumes="application/xml"> <param name="content" type="REQUEST_BODY"/> </operation> </resource> </model>
Namespaces
The XML namespace that you use to define a model schema depends on whether you are defining the corresponding JAX-RS endpoint in Blueprint XML or in Spring XML. The following table shows which namespace to use for which XML language:
XML Language | Namespace |
---|---|
Blueprint | |
Spring |
How to attach a model schema to an endpoint
To define and attach a model schema to an endpoint, perform the following steps:
- Define the model schema, using the appropriate XML namespace for your chosen injection platform (Blueprint XML or Spring XML).
Add the model schema file to your project’s resources, so that the schema file is available on the classpath in the final package (JAR, WAR, or OSGi bundle file).
NoteAlternatively, it is also possible to embed a model schema directly into a JAX-RS endpoint, using the endpoint’s
jaxrs:model
child element.-
Configure the endpoint to use the model schema, by setting the endpoint’s
modelRef
attribute to the location of the model schema on the classpath (using a classpath URL). -
If necessary, instantiate the root resources explicitly, using the
jaxrs:serviceBeans
element. You can skip this step, if the model schema references root resource classes directly (instead of referencing base interfaces).
Configuration of model schema referencing a class
If the model schema applies directly to root resource classes, there is no need to define any root resource beans using the jaxrs:serviceBeans
element, because the model schema automatically instantiates the root resource beans.
For example, given that customer-resources.xml
is a model schema that associates metadata with customer resource classes, you could instantiate a customerService
service endpoint as follows:
<jaxrs:server id="customerService" address="/customers" modelRef="classpath:/org/example/schemas/customer-resources.xml" />
Configuration of model schema referencing an interface
If the model schema applies to Java interfaces (which are the base interfaces of the root resources), you must instantiate the root resource classes using the jaxrs:serviceBeans
element in the endpoint.
For example, given that customer-interfaces.xml
is a model schema that associates metadata with customer interfaces, you could instantiate a customerService
service endpoint as follows:
<jaxrs:server id="customerService" address="/customers" modelRef="classpath:/org/example/schemas/customer-interfaces.xml"> <jaxrs:serviceBeans> <ref component-id="serviceBean" /> </jaxrs:serviceBeans> </jaxrs:server> <bean id="serviceBean" class="service.CustomerService"/>
Model Schema Reference
A model schema is defined using the following XML elements:
model
-
Root element of the model schema. If you need to reference the model schema (for example, from a JAX-RS endpoint using the
modelRef
attribute), you should set theid
attribute on this element. model/resource
The
resource
element is used to associate metadata with a specific root resource class (or with a corresponding interface). You can define the following attributes on theresource
element:Attribute Description + name
The name of the resource class (or corresponding interface) to which this resource model is applied.
+
path
The component of the REST URL path that maps to this resource.
+
consumes
Specifies the content type (Internet media type) consumed by this resource—for example,
application/xml
orapplication/json
.+
produces
Specifies the content type (Internet media type) produced by this resource—for example,
application/xml
orapplication/json
.+
model/resource/operation
The
operation
element is used to associate metadata with Java methods. You can define the following attributes on anoperation
element:Attribute Description + name
The name of the Java method to which this element is applied.
+
path
The component of the REST URL path that maps to this method. This attribute value can include parameter references, for example:
path="/books/{id}/chapter"
, where{id}
extracts the value of theid
parameter from the path.+
verb
Specifies the HTTP verb that maps to this method. Typically one of:
GET
,POST
,PUT
, orDELETE
. If the HTTP verb is not specified, it is assumed that the Java method is a sub-resource locater, which returns a reference to a sub-resource object (where the sub-resource class must also be provided with metadata using aresource
element).+
consumes
Specifies the content type (Internet media type) consumed by this operation—for example,
application/xml
orapplication/json
.+
produces
Specifies the content type (Internet media type) produced by this operation—for example,
application/xml
orapplication/json
.+
oneway
If
true
, configures the operation to be oneway, meaning that no reply message is needed. Defaults tofalse
.+
model/resource/operation/param
The
param
element is used extract a value from the REST URL and inject it into one of the method parameters. You can define the following attributes on aparam
element:Attribute Description + name
The name of the Java method parameter to which this element is applied.
+
type
Specifies how the parameter value is extracted from the REST URL or message. It can be set to one of the following values:
PATH
,QUERY
,MATRIX
,HEADER
,COOKIE
,FORM
,CONTEXT
,REQUEST_BODY
.+
defaultValue
Default value to inject into the parameter, in case a value could not be extracted from the REST URL or message.
+
encoded
If
true
, the parameter value is injected in its URI encoded form (that is, using%nn
encoding). Default isfalse
. For example, when extracting a parameter from the URL path,/name/Joe%20Bloggs
with encoded set totrue
, the parameter is injected asJoe%20Bloggs
; otherwise, the parameter would be injected asJoe Bloggs
.+
Chapter 19. Apache CXF Logging
Abstract
This chapter describes how to configure logging in the Apache CXF runtime.
19.1. Overview of Apache CXF Logging
Overview
Apache CXF uses the Java logging utility, java.util.logging
. Logging is configured in a logging configuration file that is written using the standard java.util.Properties
format. To run logging on an application, you can specify logging programmatically or by defining a property at the command that points to the logging configuration file when you start the application.
Default properties file
Apache CXF comes with a default logging.properties
file, which is located in your InstallDir/etc
directory. This file configures both the output destination for the log messages and the message level that is published. The default configuration sets the loggers to print message flagged with the WARNING
level to the console. You can either use the default file without changing any of the configuration settings or you can change the configuration settings to suit your specific application.
Logging feature
Apache CXF includes a logging feature that can be plugged into your client or your service to enable logging. Example 19.1, “Configuration for Enabling Logging” shows the configuration to enable the logging feature.
Example 19.1. Configuration for Enabling Logging
<jaxws:endpoint...> <jaxws:features> <bean class="org.apache.cxf.feature.LoggingFeature"/> </jaxws:features> </jaxws:endpoint>
For more information, see Section 19.6, “Logging Message Content”.
Where to begin?
To run a simple example of logging follow the instructions outlined in a Section 19.2, “Simple Example of Using Logging”.
For more information on how logging works in Apache CXF, read this entire chapter.
More information on java.util.logging
The java.util.logging
utility is one of the most widely used Java logging frameworks. There is a lot of information available online that describes how to use and extend this framework. As a starting point, however, the following documents gives a good overview of java.util.logging
:
19.2. Simple Example of Using Logging
Changing the log levels and output destination
To change the log level and output destination of the log messages in the wsdl_first sample application, complete the following steps:
Run the sample server as described in the Running the demo using java section of the
README.txt
file in theInstallDir/samples/wsdl_first
directory. Note that theserver start
command specifies the defaultlogging.properties
file, as follows:Platform Command + Windows
start java -Djava.util.logging.config.file=%CXF_HOME%\etc\logging.properties demo.hw.server.Server
+
UNIX
java -Djava.util.logging.config.file=$CXF_HOME/etc/logging.properties demo.hw.server.Server &
+
The default
logging.properties
file is located in theInstallDir/etc
directory. It configures the Apache CXF loggers to printWARNING
level log messages to the console. As a result, you see very little printed to the console.-
Stop the server as described in the
README.txt
file. -
Make a copy of the default
logging.properties
file, name itmylogging.properties
file, and save it in the same directory as the defaultlogging.properties
file. Change the global logging level and the console logging levels in your
mylogging.properties
file toINFO
by editing the following lines of configuration:.level= INFO java.util.logging.ConsoleHandler.level = INFO
Restart the server using the following command:
Platform Command + Windows
start java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.server.Server
+
UNIX
java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.server.Server &
+
Because you configured the global logging and the console logger to log messages of level
INFO
, you see a lot more log messages printed to the console.
19.3. Default logging configuration file
19.3.1. Overview of Logging Configuration
The default logging configuration file, logging.properties
, is located in the InstallDir/etc
directory. It configures the Apache CXF loggers to print WARNING
level messages to the console. If this level of logging is suitable for your application, you do not have to make any changes to the file before using it. You can, however, change the level of detail in the log messages. For example, you can change whether log messages are sent to the console, to a file or to both. In addition, you can specify logging at the level of individual packages.
This section discusses the configuration properties that appear in the default logging.properties
file. There are, however, many other java.util.logging
configuration properties that you can set. For more information on the java.util.logging
API, see the java.util.logging
javadoc at: http://download.oracle.com/javase/1.5/docs/api/java/util/logging/package-summary.html.
19.3.2. Configuring Logging Output
Overview
The Java logging utility, java.util.logging
, uses handler classes to output log messages. Table 19.1, “Java.util.logging Handler Classes” shows the handlers that are configured in the default logging.properties
file.
Handler Class | Outputs to |
---|---|
| Outputs log messages to the console |
| Outputs log messages to a file |
The handler classes must be on the system classpath in order to be installed by the Java VM when it starts. This is done when you set the Apache CXF environment.
Configuring the console handler
Example 19.2, “Configuring the Console Handler” shows the code for configuring the console logger.
Example 19.2. Configuring the Console Handler
handlers= java.util.logging.ConsoleHandler
The console handler also supports the configuration properties shown in Example 19.3, “Console Handler Properties”.
Example 19.3. Console Handler Properties
java.util.logging.ConsoleHandler.level = WARNING java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
The configuration properties shown in Example 19.3, “Console Handler Properties” can be explained as follows:
The console handler supports a separate log level configuration property. This allows you to limit the log messages printed to the console while the global logging setting can be different (see Section 19.3.3, “Configuring Logging Levels”). The default setting is WARNING
.
Specifies the java.util.logging
formatter class that the console handler class uses to format the log messages. The default setting is the java.util.logging.SimpleFormatter
.
Configuring the file handler
Example 19.4, “Configuring the File Handler” shows code that configures the file handler.
Example 19.4. Configuring the File Handler
handlers= java.util.logging.FileHandler
The file handler also supports the configuration properties shown in Example 19.5, “File Handler Configuration Properties”.
Example 19.5. File Handler Configuration Properties
java.util.logging.FileHandler.pattern = %h/java%u.log java.util.logging.FileHandler.limit = 50000 java.util.logging.FileHandler.count = 1 java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
The configuration properties shown in Example 19.5, “File Handler Configuration Properties” can be explained as follows:
Specifies the location and pattern of the output file. The default setting is your home directory.
Specifies, in bytes, the maximum amount that the logger writes to any one file. The default setting is 50000
. If you set it to zero, there is no limit on the amount that the logger writes to any one file.
Specifies how many output files to cycle through. The default setting is 1
.
Specifies the java.util.logging
formatter class that the file handler class uses to format the log messages. The default setting is the java.util.logging.XMLFormatter
.
Configuring both the console handler and the file handler
You can set the logging utility to output log messages to both the console and to a file by specifying the console handler and the file handler, separated by a comma, as shown in Configuring Both Console Logging and File.
Configuring Both Console Logging and File
Logging
handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler
19.3.3. Configuring Logging Levels
Logging levels
The java.util.logging
framework supports the following levels of logging, from the least verbose to the most verbose:
-
SEVERE
-
WARNING
-
INFO
-
CONFIG
-
FINE
-
FINER
-
FINEST
Configuring the global logging level
To configure the types of event that are logged across all loggers, configure the global logging level as shown in Example 19.6, “Configuring Global Logging Levels”.
Example 19.6. Configuring Global Logging Levels
.level= WARNING
Configuring logging at an individual package
level
The java.util.logging
framework supports configuring logging at the level of an individual package. For example, the line of code shown in Example 19.7, “Configuring Logging at the Package Level” configures logging at a SEVERE
level on classes in the com.xyz.foo package.
Example 19.7. Configuring Logging at the Package Level
com.xyz.foo.level = SEVERE
19.4. Enabling Logging at the Command Line
Overview
You can run the logging utility on an application by defining a java.util.logging.config.file
property when you start the application. You can either specify the default logging.properties
file or a logging.properties
file that is unique to that application.
Specifying the log configuration file on application
start-up
To specify logging on application start-up add the flag shown in Example 19.8, “Flag to Start Logging on the Command Line” when starting the application.
Example 19.8. Flag to Start Logging on the Command Line
-Djava.util.logging.config.file=myfile
19.5. Logging for Subsystems and Services
Overview
You can use the com.xyz.foo.level
configuration property described in the section called “Configuring logging at an individual package” to set fine-grained logging for specified Apache CXF logging subsystems.
Apache CXF logging subsystems
Table 19.2, “Apache CXF Logging Subsystems” shows a list of available Apache CXF logging subsystems.
Subsystem | Description |
---|---|
| Aegis binding |
| colocated binding |
| HTTP binding |
| JBI binding |
| Java Object binding |
| SOAP binding |
| XML binding |
| Apache CXF bus |
| configuration framework |
| server and client endpoints |
| interceptors |
| Front-end for JAX-WS style message exchange, JAX-WS handler processing, and interceptors relating to JAX-WS and configuration |
| JBI container integration classes |
| JCA container integration classes |
| JavaScript front-end |
| HTTP transport |
| secure version of HTTP transport, using HTTPS |
| JBI transport |
| JMS transport |
| transport implementation using local file system |
| HTTP transport and servlet implementation for loading JAX-WS endpoints into a servlet container |
| WS-Addressing implementation |
| WS-Policy implementation |
| WS-ReliableMessaging (WS-RM) implementation |
| WSS4J security implementation |
Example
The WS-Addressing sample is contained in the InstallDir/samples/ws_addressing
directory. Logging is configured in the logging.properties
file located in that directory. The relevant lines of configuration are shown in Example 19.9, “Configuring Logging for WS-Addressing”.
Example 19.9. Configuring Logging for WS-Addressing
java.util.logging.ConsoleHandler.formatter = demos.ws_addressing.common.ConciseFormatter ... org.apache.cxf.ws.addressing.soap.MAPCodec.level = INFO
The configuration in Example 19.9, “Configuring Logging for WS-Addressing” enables the snooping of log messages relating to WS-Addressing headers, and displays them to the console in a concise form.
For information on running this sample, see the README.txt
file located in the InstallDir/samples/ws_addressing
directory.
19.6. Logging Message Content
Overview
You can log the content of the messages that are sent between a service and a consumer. For example, you might want to log the contents of SOAP messages that are being sent between a service and a consumer.
Configuring message content logging
To log the messages that are sent between a service and a consumer, and vice versa, complete the following steps:
Adding the logging feature to an endpoint
Add the logging feature your endpoint’s configuration as shown in Example 19.10, “Adding Logging to Endpoint Configuration”.
Example 19.10. Adding Logging to Endpoint Configuration
<jaxws:endpoint ...> <jaxws:features> <bean class="org.apache.cxf.feature.LoggingFeature"/> </jaxws:features> </jaxws:endpoint>
The example XML shown in Example 19.10, “Adding Logging to Endpoint Configuration” enables the logging of SOAP messages.
Adding the logging feature to a consumer
Add the logging feature your client’s configuration as shown in Example 19.11, “Adding Logging to Client Configuration”.
Example 19.11. Adding Logging to Client Configuration
<jaxws:client ...> <jaxws:features> <bean class="org.apache.cxf.feature.LoggingFeature"/> </jaxws:features> </jaxws:client>
The example XML shown in Example 19.11, “Adding Logging to Client Configuration” enables the logging of SOAP messages.
Set logging to log INFO level messages
Ensure that the logging.properties
file associated with your service is configured to log INFO
level messages, as shown in Example 19.12, “Setting the Logging Level to INFO”.
Example 19.12. Setting the Logging Level to INFO
.level= INFO java.util.logging.ConsoleHandler.level = INFO
Logging SOAP messages
To see the logging of SOAP messages modify the wsdl_first sample application located in the InstallDir/samples/wsdl_first
directory, as follows:
Add the
jaxws:features
element shown in Example 19.13, “Endpoint Configuration for Logging SOAP Messages” to thecxf.xml
configuration file located in the wsdl_first sample’s directory:Example 19.13. Endpoint Configuration for Logging SOAP Messages
<jaxws:endpoint name="{http://apache.org/hello_world_soap_http}SoapPort" createdFromAPI="true"> <jaxws:properties> <entry key="schema-validation-enabled" value="true" /> </jaxws:properties> <jaxws:features> <bean class="org.apache.cxf.feature.LoggingFeature"/> </jaxws:features> </jaxws:endpoint>
-
The sample uses the default
logging.properties
file, which is located in theInstallDir/etc
directory. Make a copy of this file and name itmylogging.properties
. In the
mylogging.properties
file, change the logging levels toINFO
by editing the.level
and thejava.util.logging.ConsoleHandler.level
configuration properties as follows:.level= INFO java.util.logging.ConsoleHandler.level = INFO
Start the server using the new configuration settings in both the
cxf.xml
file and themylogging.properties
file as follows:Platform Command + Windows
start java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.server.Server
+
UNIX
java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.server.Server &
+
Start the hello world client using the following command:
Platform Command + Windows
java -Djava.util.logging.config.file=%CXF_HOME%\etc\mylogging.properties demo.hw.client.Client .\wsdl\hello_world.wsdl
+
UNIX
java -Djava.util.logging.config.file=$CXF_HOME/etc/mylogging.properties demo.hw.client.Client ./wsdl/hello_world.wsdl
+
The SOAP messages are logged to the console.
Chapter 20. Deploying WS-Addressing
Abstract
Apache CXF supports WS-Addressing for JAX-WS applications. This chapter explains how to deploy WS-Addressing in the Apache CXF runtime environment.
20.1. Introduction to WS-Addressing
Overview
WS-Addressing is a specification that allows services to communicate addressing information in a transport neutral way. It consists of two parts:
- A structure for communicating a reference to a Web service endpoint
- A set of Message Addressing Properties (MAP) that associate addressing information with a particular message
Supported specifications
Apache CXF supports both the WS-Addressing 2004/08 specification and the WS-Addressing 2005/03 specification.
Further information
For detailed information on WS-Addressing, see the 2004/08 submission at http://www.w3.org/Submission/ws-addressing/.
20.2. WS-Addressing Interceptors
Overview
In Apache CXF, WS-Addressing functionality is implemented as interceptors. The Apache CXF runtime uses interceptors to intercept and work with the raw messages that are being sent and received. When a transport receives a message, it creates a message object and sends that message through an interceptor chain. If the WS-Addressing interceptors are added to the application’s interceptor chain, any WS-Addressing information included with a message is processed.
WS-Addressing Interceptors
The WS-Addressing implementation consists of two interceptors, as described in Table 20.1, “WS-Addressing Interceptors”.
Interceptor | Description |
---|---|
| A logical interceptor responsible for aggregating the Message Addressing Properties (MAPs) for outgoing messages. |
| A protocol-specific interceptor responsible for encoding and decoding the Message Addressing Properties (MAPs) as SOAP headers. |
20.3. Enabling WS-Addressing
Overview
To enable WS-Addressing the WS-Addressing interceptors must be added to the inbound and outbound interceptor chains. This is done in one of the following ways:
- Apache CXF Features
- RMAssertion and WS-Policy Framework
- Using Policy Assertion in a WS-Addressing Feature
Adding WS-Addressing as a Feature
WS-Addressing can be enabled by adding the WS-Addressing feature to the client and the server configuration as shown in Example 20.1, “client.xml and Adding WS-Addressing Feature to Client Configuration” and Example 20.2, “server.xml and Adding WS-Addressing Feature to Server Configuration” respectively.
Example 20.1. client.xml and Adding WS-Addressing Feature to Client Configuration
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws" xmlns:wsa="http://cxf.apache.org/ws/addressing" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://cxf.apache.org/ws/addressing http://cxf.apache.org/schemas/ws-addr-conf.xsd"> <jaxws:client ...> <jaxws:features> <wsa:addressing/> </jaxws:features> </jaxws:client> </beans>
Example 20.2. server.xml and Adding WS-Addressing Feature to Server Configuration
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws" xmlns:wsa="http://cxf.apache.org/ws/addressing" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <jaxws:endpoint ...> <jaxws:features> <wsa:addressing/> </jaxws:features> </jaxws:endpoint> </beans>
20.4. Configuring WS-Addressing Attributes
Overview
The Apache CXF WS-Addressing feature element is defined in the namespace http://cxf.apache.org/ws/addressing
. It supports the two attributes described in Table 20.2, “WS-Addressing Attributes”.
Attribute Name | Value |
---|---|
|
A boolean that determines if duplicate MessageIDs are tolerated. The default setting is |
|
A boolean that indicates if the presence of the |
Configuring WS-Addressing attributes
Configure WS-Addressing attributes by adding the attribute and the value you want to set it to the WS-Addressing feature in your server or client configuration file. For example, the following configuration extract sets the allowDuplicates
attribute to false
on the server endpoint:
<beans ... xmlns:wsa="http://cxf.apache.org/ws/addressing" ...> <jaxws:endpoint ...> <jaxws:features> <wsa:addressing allowDuplicates="false"/> </jaxws:features> </jaxws:endpoint> </beans>
Using a WS-Policy assertion embedded in a feature
In Example 20.3, “Using the Policies to Configure WS-Addressing” an addressing policy assertion to enable non-anonymous responses is embedded in the policies
element.
Example 20.3. Using the Policies to Configure WS-Addressing
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsa="http://cxf.apache.org/ws/addressing" xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:policy="http://cxf.apache.org/policy-config" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:jaxws="http://cxf.apache.org/jaxws" xsi:schemaLocation=" http://www.w3.org/2006/07/ws-policy http://www.w3.org/2006/07/ws-policy.xsd http://cxf.apache.org/ws/addressing http://cxf.apache.org/schema/ws/addressing.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <jaxws:endpoint name="{http://cxf.apache.org/greeter_control}GreeterPort" createdFromAPI="true"> <jaxws:features> <policy:policies> <wsp:Policy xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsam:Addressing> <wsp:Policy> <wsam:NonAnonymousResponses/> </wsp:Policy> </wsam:Addressing> </wsp:Policy> <policy:policies> </jaxws:features> </jaxws:endpoint> </beans>
Chapter 21. Enabling Reliable Messaging
Abstract
Apache CXF supports WS-Reliable Messaging(WS-RM). This chapter explains how to enable and configure WS-RM in Apache CXF.
21.1. Introduction to WS-RM
Overview
WS-ReliableMessaging (WS-RM) is a protocol that ensures the reliable delivery of messages in a distributed environment. It enables messages to be delivered reliably between distributed applications in the presence of software, system, or network failures.
For example, WS-RM can be used to ensure that the correct messages have been delivered across a network exactly once, and in the correct order.
How WS-RM works
WS-RM ensures the reliable delivery of messages between a source and a destination endpoint. The source is the initial sender of the message and the destination is the ultimate receiver, as shown in Figure 21.1, “Web Services Reliable Messaging”.
Figure 21.1. Web Services Reliable Messaging
The flow of WS-RM messages can be described as follows:
-
The RM source sends a
CreateSequence
protocol message to the RM destination. This contains a reference for the endpoint that receives acknowledgements (thewsrm:AcksTo
endpoint). -
The RM destination sends a
CreateSequenceResponse
protocol message back to the RM source. This message contains the sequence ID for the RM sequence session. -
The RM source adds an RM
Sequence
header to each message sent by the application source. This header contains the sequence ID and a unique message ID. - The RM source transmits each message to the RM destination.
-
The RM destination acknowledges the receipt of the message from the RM source by sending messages that contain the RM
SequenceAcknowledgement
header. - The RM destination delivers the message to the application destination in an exactly-once-in-order fashion.
The RM source retransmits a message that it has not yet received an acknowledgement.
The first retransmission attempt is made after a base retransmission interval. Successive retransmission attempts are made, by default, at exponential back-off intervals or, alternatively, at fixed intervals. For more details, see Section 21.5, “Configuring WS-RM”.
This entire process occurs symmetrically for both the request and the response message; that is, in the case of the response message, the server acts as the RM source and the client acts as the RM destination.
WS-RM delivery assurances
WS-RM guarantees reliable message delivery in a distributed environment, regardless of the transport protocol used. Either the source or the destination endpoint logs an error if reliable delivery can not be assured.
Supported specifications
Apache CXF supports the following versions of the WS-RM specification:
- WS-ReliableMessaging 1.0
(Default) Corresponds to the February 2005 submission version, which is now out of date. For reasons of backward compatibility, however, this version is used as the default.
Version 1.0 of WS-RM uses the following namespace:
http://schemas.xmlsoap.org/ws/2005/02/rm/
This version of WS-RM can be used with either of the following WS-Addressing versions:
http://schemas.xmlsoap.org/ws/2004/08/addressing (default) http://www.w3.org/2005/08/addressing
Strictly speaking, in order to comply with the February 2005 submission version of WS-RM, you ought to use the first of these WS-Addressing versions (which is the default in Apache CXF). But most other Web service implementations have switched to the more recent WS-Addressing specification, so Apache CXF allows you to choose the WS-A version, to facilitate interoperability (see Section 21.4, “Runtime Control”).
- WS-ReliableMessaging 1.1/1.2
Corresponds to the official 1.1/1.2 Web Services Reliable Messaging specification.
Versions 1.1 and 1.2 of WS-RM uses the following namespace:
http://docs.oasis-open.org/ws-rx/wsrm/200702
The 1.1 and 1.2 versions of WS-RM use the following WS-Addressing version:
http://www.w3.org/2005/08/addressing
Selecting the WS-RM version
You can select which WS-RM specification version to use, as follows:
- Server side
- On the provider side, Apache CXF adapts to whichever version of WS-ReliableMessaging is used by the client and responds appropriately.
- Client side
- On the client side, the WS-RM version is determined either by the namespace that you use in the client configuration (see Section 21.5, “Configuring WS-RM”) or by overriding the WS-RM version at run time, using the runtime control options (see Section 21.4, “Runtime Control”).
21.2. WS-RM Interceptors
Overview
In Apache CXF, WS-RM functionality is implemented as interceptors. The Apache CXF runtime uses interceptors to intercept and work with the raw messages that are being sent and received. When a transport receives a message, it creates a message object and sends that message through an interceptor chain. If the application’s interceptor chain includes the WS-RM interceptors, the application can participate in reliable messaging sessions. The WS-RM interceptors handle the collection and aggregation of the message chunks. They also handle all of the acknowledgement and retransmission logic.
Apache CXF WS-RM Interceptors
The Apache CXF WS-RM implementation consists of four interceptors, which are described in Table 21.1, “Apache CXF WS-ReliableMessaging Interceptors”.
Interceptor | Description |
---|---|
| Deals with the logical aspects of providing reliability guarantees for outgoing messages.
Responsible for sending the Also responsible for aggregating the sequence properties—ID and message number—for an application message. |
|
Responsible for intercepting and processing RM protocol messages and |
| Caching incoming messages for persistent storage. |
| Assuring InOrder delivery of messages to the application. |
| Responsible for encoding and decoding the reliability properties as SOAP headers. |
| Responsible for creating copies of application messages for future resending. |
Enabling WS-RM
The presence of the WS-RM interceptors on the interceptor chains ensures that WS-RM protocol messages are exchanged when necessary. For example, when intercepting the first application message on the outbound interceptor chain, the RMOutInterceptor
sends a CreateSequence
request and waits to process the original application message until it receives the CreateSequenceResponse
response. In addition, the WS-RM interceptors add the sequence headers to the application messages and, on the destination side, extract them from the messages. It is not necessary to make any changes to your application code to make the exchange of messages reliable.
For more information on how to enable WS-RM, see Section 21.3, “Enabling WS-RM”.
Configuring WS-RM Attributes
You control sequence demarcation and other aspects of the reliable exchange through configuration. For example, by default Apache CXF attempts to maximize the lifetime of a sequence, thus reducing the overhead incurred by the out-of-band WS-RM protocol messages. To enforce the use of a separate sequence per application message configure the WS-RM source’s sequence termination policy (setting the maximum sequence length to 1
).
For more information on configuring WS-RM behavior, see Section 21.5, “Configuring WS-RM”.
21.3. Enabling WS-RM
Overview
To enable reliable messaging, the WS-RM interceptors must be added to the interceptor chains for both inbound and outbound messages and faults. Because the WS-RM interceptors use WS-Addressing, the WS-Addressing interceptors must also be present on the interceptor chains.
You can ensure the presence of these interceptors in one of two ways:
- Explicitly, by adding them to the dispatch chains using Spring beans
- Implicitly, using WS-Policy assertions, which cause the Apache CXF runtime to transparently add the interceptors on your behalf.
Spring beans: explicitly adding interceptors
To enable WS-RM add the WS-RM and WS-Addressing interceptors to the Apache CXF bus, or to a consumer or service endpoint using Spring bean configuration. This is the approach taken in the WS-RM sample that is found in the InstallDir/samples/ws_rm
directory. The configuration file, ws-rm.cxf
, shows the WS-RM and WS-Addressing interceptors being added one-by-one as Spring beans (see Example 21.1, “Enabling WS-RM Using Spring Beans”).
Example 21.1. Enabling WS-RM Using Spring Beans
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/ beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <bean id="mapAggregator" class="org.apache.cxf.ws.addressing.MAPAggregator"/> <bean id="mapCodec" class="org.apache.cxf.ws.addressing.soap.MAPCodec"/> <bean id="rmLogicalOut" class="org.apache.cxf.ws.rm.RMOutInterceptor"> <property name="bus" ref="cxf"/> </bean> <bean id="rmLogicalIn" class="org.apache.cxf.ws.rm.RMInInterceptor"> <property name="bus" ref="cxf"/> </bean> <bean id="rmCodec" class="org.apache.cxf.ws.rm.soap.RMSoapInterceptor"/> <bean id="cxf" class="org.apache.cxf.bus.CXFBusImpl"> <property name="inInterceptors"> <list> <ref bean="mapAggregator"/> <ref bean="mapCodec"/> <ref bean="rmLogicalIn"/> <ref bean="rmCodec"/> </list> </property> <property name="inFaultInterceptors"> <list> <ref bean="mapAggregator"/> <ref bean="mapCodec"/> <ref bean="rmLogicalIn"/> <ref bean="rmCodec"/> </list> </property> <property name="outInterceptors"> <list> <ref bean="mapAggregator"/> <ref bean="mapCodec"/> <ref bean="rmLogicalOut"/> <ref bean="rmCodec"/> </list> </property> <property name="outFaultInterceptors"> <list> <ref bean="mapAggregator"> <ref bean="mapCodec"/> <ref bean="rmLogicalOut"/> <ref bean="rmCodec"/> </list> </property> </bean> </beans>
The code shown in Example 21.1, “Enabling WS-RM Using Spring Beans” can be explained as follows:
A Apache CXF configuration file is a Spring XML file. You must include an opening Spring beans
element that declares the namespaces and schema files for the child elements that are encapsulated by the beans
element.
Configures each of the WS-Addressing interceptors—MAPAggregator
and MAPCodec
. For more information on WS-Addressing, see Chapter 20, Deploying WS-Addressing.
Configures each of the WS-RM interceptors—RMOutInterceptor
, RMInInterceptor
, and RMSoapInterceptor
.
Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for inbound messages.
Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for inbound faults.
Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for outbound messages.
Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for outbound faults.
WS-Policy framework: implicitly adding interceptors
The WS-Policy framework provides the infrastructure and APIs that allow you to use WS-Policy. It is compliant with the November 2006 draft publications of the Web Services Policy 1.5—Framework and Web Services Policy 1.5—Attachment specifications.
To enable WS-RM using the Apache CXF WS-Policy framework, do the following:
Add the policy feature to your client and server endpoint. Example 21.2, “Configuring WS-RM using WS-Policy” shows a reference bean nested within a
jaxws:feature
element. The reference bean specifies theAddressingPolicy
, which is defined as a separate element within the same configuration file.Example 21.2. Configuring WS-RM using WS-Policy
<jaxws:client> <jaxws:features> <ref bean="AddressingPolicy"/> </jaxws:features> </jaxws:client> <wsp:Policy wsu:Id="AddressingPolicy" xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsam:Addressing> <wsp:Policy> <wsam:NonAnonymousResponses/> </wsp:Policy> </wsam:Addressing> </wsp:Policy>
Add a reliable messaging policy to the
wsdl:service
element—or any other WSDL element that can be used as an attachment point for policy or policy reference elements—to your WSDL file, as shown in Example 21.3, “Adding an RM Policy to Your WSDL File”.Example 21.3. Adding an RM Policy to Your WSDL File
<wsp:Policy wsu:Id="RM" xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy/> </wsam:Addressing> <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"> <wsrmp:BaseRetransmissionInterval Milliseconds="10000"/> </wsrmp:RMAssertion> </wsp:Policy> ... <wsdl:service name="ReliableGreeterService"> <wsdl:port binding="tns:GreeterSOAPBinding" name="GreeterPort"> <soap:address location="http://localhost:9020/SoapContext/GreeterPort"/> <wsp:PolicyReference URI="#RM" xmlns:wsp="http://www.w3.org/2006/07/ws-policy"/> </wsdl:port> </wsdl:service>
21.4. Runtime Control
Overview
Several message context property values can be set in client code to control WS-RM at runtime, with key values defined by public constants in the org.apache.cxf.ws.rm.RMManager
class.
Runtime control options
The following table lists the keys defined by the org.apache.cxf.ws.rm.RMManager
class.
Key | Description |
---|---|
|
String WS-RM version namespace ( |
|
String WS-Addressing version namespace ( |
|
Boolean value |
| Long inactivity timeout in milliseconds. |
| Long base retransmission interval in milliseconds. |
| Boolean exponential back-off flag. |
| Long acknowledgement interval in milliseconds. |
Controlling WS-RM through JMX
You can also monitor and control many aspects of WS-RM using the JMX Management features of Apache CXF. The full list of JMX operations is defined by org.apache.cxf.ws.rm.ManagedRMManager
and org.apache.cxf.ws.rm.ManagedRMEndpoint
, but these operations include viewing the current RM state down to the individual message level. You can also use JXM to close or terminate a WS-RM sequence, and to receive notification of when previously-sent messages are acknowledged by the remote RM endpoint.
Example of JMX control
For example, if you have the JMX server enabled in your client configuration, you could use the following code to track the last acknowledgement number received:
// Java private static class AcknowledgementListener implements NotificationListener { private volatile long lastAcknowledgement; @Override public void handleNotification(Notification notification, Object handback) { if (notification instanceof AcknowledgementNotification) { AcknowledgementNotification ack = (AcknowledgementNotification)notification; lastAcknowledgement = ack.getMessageNumber(); } } // initialize client ... // attach to JMX bean for notifications // NOTE: you must have sent at least one message to initialize RM before executing this code Endpoint ep = ClientProxy.getClient(client).getEndpoint(); InstrumentationManager im = bus.getExtension(InstrumentationManager.class); MBeanServer mbs = im.getMBeanServer(); RMManager clientManager = bus.getExtension(RMManager.class); ObjectName name = RMUtils.getManagedObjectName(clientManager, ep); System.out.println("Looking for endpoint name " + name); AcknowledgementListener listener = new AcknowledgementListener(); mbs.addNotificationListener(name, listener, null, null); // send messages using RM with acknowledgement status reported to listener ...
21.5. Configuring WS-RM
21.5.1. Configuring Apache CXF-Specific WS-RM Attributes
Overview
To configure the Apache CXF-specific attributes, use the rmManager
Spring bean. Add the following to your configuration file:
-
The
http://cxf.apache.org/ws/rm/manager
namespace to your list of namespaces. -
An
rmManager
Spring bean for the specific attribute that your want to configure.
Example 21.4, “Configuring Apache CXF-Specific WS-RM Attributes” shows a simple example.
Example 21.4. Configuring Apache CXF-Specific WS-RM Attributes
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://cxf.apache.org/ws/rm/manager http://cxf.apache.org/schemas/configuration/wsrm-manager.xsd"> ... <wsrm-mgr:rmManager> <!-- ...Your configuration goes here --> </wsrm-mgr:rmManager>
Children of the rmManager Spring bean
Table 21.2, “Children of the rmManager Spring Bean” shows the child elements of the rmManager
Spring bean, defined in the http://cxf.apache.org/ws/rm/manager
namespace.
Element | Description |
---|---|
|
An element of type |
|
An element of type |
|
An element of type |
|
An element of type |
Example
For an example, see the section called “Maximum unacknowledged messages threshold”.
21.5.2. Configuring Standard WS-RM Policy Attributes
Overview
You can configure standard WS-RM policy attributes in one of the following ways:
WS-Policy RMAssertion Children
Table 21.3, “Children of the WS-Policy RMAssertion Element” shows the elements defined in the http://schemas.xmlsoap.org/ws/2005/02/rm/policy
namespace:
Name | Description |
---|---|
| Specifies the amount of time that must pass without receiving a message before an endpoint can consider an RM sequence to have been terminated due to inactivity. |
|
Sets the interval within which an acknowledgement must be received by the RM Source for a given message. If an acknowledgement is not received within the time set by the |
| Indicates the retransmission interval will be adjusted using the commonly known exponential backoff algorithm (Tanenbaum). For more information, see Computer Networks, Andrew S. Tanenbaum, Prentice Hall PTR, 2003. |
| In WS-RM, acknowledgements are sent on return messages or sent stand-alone. If a return message is not available to send an acknowledgement, an RM Destination can wait for up to the acknowledgement interval before sending a stand-alone acknowledgement. If there are no unacknowledged messages, the RM Destination can choose not to send an acknowledgement. |
More detailed reference information
For more detailed reference information, including descriptions of each element’s sub-elements and attributes, please refer to http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd.
RMAssertion in rmManager Spring bean
You can configure standard WS-RM policy attributes by adding an RMAssertion
within a Apache CXF rmManager
Spring bean. This is the best approach if you want to keep all of your WS-RM configuration in the same configuration file; that is, if you want to configure Apache CXF-specific attributes and standard WS-RM policy attributes in the same file.
For example, the configuration in Example 21.5, “Configuring WS-RM Attributes Using an RMAssertion in an rmManager Spring Bean” shows:
-
A standard WS-RM policy attribute,
BaseRetransmissionInterval
, configured using anRMAssertion
within anrmManager
Spring bean. -
An Apache CXF-specific RM attribute,
intraMessageThreshold
, configured in the same configuration file.
Example 21.5. Configuring WS-RM Attributes Using an RMAssertion in an rmManager Spring Bean
<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy" xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager" ...> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <wsrm-policy:RMAssertion> <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/> </wsrm-policy:RMAssertion> <wsrm-mgr:destinationPolicy> <wsrm-mgr:acksPolicy intraMessageThreshold="0" /> </wsrm-mgr:destinationPolicy> </wsrm-mgr:rmManager> </beans>
Policy within a feature
You can configure standard WS-RM policy attributes within features, as shown in Example 21.6, “Configuring WS-RM Attributes as a Policy within a Feature”.
Example 21.6. Configuring WS-RM Attributes as a Policy within a Feature
<xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wsa="http://cxf.apache.org/ws/addressing" xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:jaxws="http://cxf.apache.org/jaxws" xsi:schemaLocation=" http://www.w3.org/2006/07/ws-policy http://www.w3.org/2006/07/ws-policy.xsd http://cxf.apache.org/ws/addressing http://cxf.apache.org/schema/ws/addressing.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <jaxws:endpoint name="{http://cxf.apache.org/greeter_control}GreeterPort" createdFromAPI="true"> <jaxws:features> <wsp:Policy> <wsrm:RMAssertion xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"> <wsrm:AcknowledgementInterval Milliseconds="200" /> </wsrm:RMAssertion> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy> <wsam:NonAnonymousResponses/> </wsp:Policy> </wsam:Addressing> </wsp:Policy> </jaxws:features> </jaxws:endpoint> </beans>
WSDL file
If you use the WS-Policy framework to enable WS-RM, you can configure standard WS-RM policy attributes in a WSDL file. This is a good approach if you want your service to interoperate and use WS-RM seamlessly with consumers deployed to other policy-aware Web services stacks.
For an example, see the section called “WS-Policy framework: implicitly adding interceptors” where the base retransmission interval is configured in the WSDL file.
External attachment
You can configure standard WS-RM policy attributes in an external attachment file. This is a good approach if you cannot, or do not want to, change your WSDL file.
Example 21.7, “Configuring WS-RM in an External Attachment” shows an external attachment that enables both WS-A and WS-RM (base retransmission interval of 30 seconds) for a specific EPR.
Example 21.7. Configuring WS-RM in an External Attachment
<attachments xmlns:wsp="http://www.w3.org/2006/07/ws-policy" xmlns:wsa="http://www.w3.org/2005/08/addressing"> <wsp:PolicyAttachment> <wsp:AppliesTo> <wsa:EndpointReference> <wsa:Address>http://localhost:9020/SoapContext/GreeterPort</wsa:Address> </wsa:EndpointReference> </wsp:AppliesTo> <wsp:Policy> <wsam:Addressing xmlns:wsam="http://www.w3.org/2007/02/addressing/metadata"> <wsp:Policy/> </wsam:Addressing> <wsrmp:RMAssertion xmlns:wsrmp="http://schemas.xmlsoap.org/ws/2005/02/rm/policy"> <wsrmp:BaseRetransmissionInterval Milliseconds="30000"/> </wsrmp:RMAssertion> </wsp:Policy> </wsp:PolicyAttachment> </attachments>/
21.5.3. WS-RM Configuration Use Cases
Overview
This subsection focuses on configuring WS-RM attributes from a use case point of view. Where an attribute is a standard WS-RM policy attribute, defined in the http://schemas.xmlsoap.org/ws/2005/02/rm/policy/ namespace, only the example of setting it in an RMAssertion
within an rmManager
Spring bean is shown. For details of how to set such attributes as a policy within a feature; in a WSDL file, or in an external attachment, see Section 21.5.2, “Configuring Standard WS-RM Policy Attributes”.
The following use cases are covered:
- the section called “Base retransmission interval”
- the section called “Exponential backoff for retransmission”
- the section called “Acknowledgement interval”
- the section called “Maximum unacknowledged messages threshold”
- the section called “Maximum length of an RM sequence”
- the section called “Message delivery assurance policies”
Base retransmission interval
The BaseRetransmissionInterval
element specifies the interval at which an RM source retransmits a message that has not yet been acknowledged. It is defined in the http://schemas.xmlsoap.org/ws/2005/02/rm/wsrm-policy.xsd schema file. The default value is 3000 milliseconds.
Example 21.8, “Setting the WS-RM Base Retransmission Interval” shows how to set the WS-RM base retransmission interval.
Example 21.8. Setting the WS-RM Base Retransmission Interval
<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy ...> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <wsrm-policy:RMAssertion> <wsrm-policy:BaseRetransmissionInterval Milliseconds="4000"/> </wsrm-policy:RMAssertion> </wsrm-mgr:rmManager> </beans>
Exponential backoff for retransmission
The ExponentialBackoff
element determines if successive retransmission attempts for an unacknowledged message are performed at exponential intervals.
The presence of the ExponentialBackoff
element enables this feature. An exponential backoff ratio of 2
is used by default. ExponentialBackoff
is a flag. When the element is present, exponential backoff is enabled. When the element is absent, exponential backoff is disabled. No value is required.
Example 21.9, “Setting the WS-RM Exponential Backoff Property” shows how to set the WS-RM exponential backoff for retransmission.
Example 21.9. Setting the WS-RM Exponential Backoff Property
<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy ...> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <wsrm-policy:RMAssertion> <wsrm-policy:ExponentialBackoff/> </wsrm-policy:RMAssertion> </wsrm-mgr:rmManager> </beans>
Acknowledgement interval
The AcknowledgementInterval
element specifies the interval at which the WS-RM destination sends asynchronous acknowledgements. These are in addition to the synchronous acknowledgements that it sends on receipt of an incoming message. The default asynchronous acknowledgement interval is 0
milliseconds. This means that if the AcknowledgementInterval
is not configured to a specific value, acknowledgements are sent immediately (that is, at the first available opportunity).
Asynchronous acknowledgements are sent by the RM destination only if both of the following conditions are met:
-
The RM destination is using a non-anonymous
wsrm:acksTo
endpoint. - The opportunity to piggyback an acknowledgement on a response message does not occur before the expiry of the acknowledgement interval.
Example 21.10, “Setting the WS-RM Acknowledgement Interval” shows how to set the WS-RM acknowledgement interval.
Example 21.10. Setting the WS-RM Acknowledgement Interval
<beans xmlns:wsrm-policy="http://schemas.xmlsoap.org/ws/2005/02/rm/policy ...> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <wsrm-policy:RMAssertion> <wsrm-policy:AcknowledgementInterval Milliseconds="2000"/> </wsrm-policy:RMAssertion> </wsrm-mgr:rmManager> </beans>
Maximum unacknowledged messages threshold
The maxUnacknowledged
attribute sets the maximum number of unacknowledged messages that can accrue per sequence before the sequence is terminated.
Example 21.11, “Setting the WS-RM Maximum Unacknowledged Message Threshold” shows how to set the WS-RM maximum unacknowledged messages threshold.
Example 21.11. Setting the WS-RM Maximum Unacknowledged Message Threshold
<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager ...> <wsrm-mgr:reliableMessaging> <wsrm-mgr:sourcePolicy> <wsrm-mgr:sequenceTerminationPolicy maxUnacknowledged="20" /> </wsrm-mgr:sourcePolicy> </wsrm-mgr:reliableMessaging> </beans>
Maximum length of an RM sequence
The maxLength
attribute sets the maximum length of a WS-RM sequence. The default value is 0
, which means that the length of a WS-RM sequence is unbound.
When this attribute is set, the RM endpoint creates a new RM sequence when the limit is reached, and after receiving all of the acknowledgements for the previously sent messages. The new message is sent using a newsequence.
Example 21.12, “Setting the Maximum Length of a WS-RM Message Sequence” shows how to set the maximum length of an RM sequence.
Example 21.12. Setting the Maximum Length of a WS-RM Message Sequence
<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager ...> <wsrm-mgr:reliableMessaging> <wsrm-mgr:sourcePolicy> <wsrm-mgr:sequenceTerminationPolicy maxLength="100" /> </wsrm-mgr:sourcePolicy> </wsrm-mgr:reliableMessaging> </beans>
Message delivery assurance policies
You can configure the RM destination to use the following delivery assurance policies:
-
AtMostOnce
— The RM destination delivers the messages to the application destination only once. If a message is delivered more than once an error is raised. It is possible that some messages in a sequence may not be delivered. -
AtLeastOnce
— The RM destination delivers the messages to the application destination at least once. Every message sent will be delivered or an error will be raised. Some messages might be delivered more than once. -
InOrder
— The RM destination delivers the messages to the application destination in the order that they are sent. This delivery assurance can be combined with theAtMostOnce
orAtLeastOnce
assurances.
Example 21.13, “Setting the WS-RM Message Delivery Assurance Policy” shows how to set the WS-RM message delivery assurance.
Example 21.13. Setting the WS-RM Message Delivery Assurance Policy
<beans xmlns:wsrm-mgr="http://cxf.apache.org/ws/rm/manager ...> <wsrm-mgr:reliableMessaging> <wsrm-mgr:deliveryAssurance> <wsrm-mgr:AtLeastOnce /> </wsrm-mgr:deliveryAssurance> </wsrm-mgr:reliableMessaging> </beans>
21.6. Configuring WS-RM Persistence
Overview
The Apache CXF WS-RM features already described in this chapter provide reliability for cases such as network failures. WS-RM persistence provides reliability across other types of failure such as an RM source or an RM destination crash.
WS-RM persistence involves storing the state of the various RM endpoints in persistent storage. This enables the endpoints to continue sending and receiving messages when they are reincarnated.
Apache CXF enables WS-RM persistence in a configuration file. The default WS-RM persistence store is JDBC-based. For convenience, Apache CXF includes Derby for out-of-the-box deployment. In addition, the persistent store is also exposed using a Java API. To implement your own persistence mechanism, you can implement one using this API with your preferred DB.
WS-RM persistence is supported for oneway calls only, and it is disabled by default.
How it works
Apache CXF WS-RM persistence works as follows:
- At the RM source endpoint, an outgoing message is persisted before transmission. It is evicted from the persistent store after the acknowledgement is received.
- After a recovery from crash, it recovers the persisted messages and retransmits until all the messages have been acknowledged. At that point, the RM sequence is closed.
- At the RM destination endpoint, an incoming message is persisted, and upon a successful store, the acknowledgement is sent. When a message is successfully dispatched, it is evicted from the persistent store.
- After a recovery from a crash, it recovers the persisted messages and dispatches them. It also brings the RM sequence to a state where new messages are accepted, acknowledged, and delivered.
Enabling WS-persistence
To enable WS-RM persistence, you must specify the object implementing the persistent store for WS-RM. You can develop your own or you can use the JDBC based store that comes with Apache CXF.
The configuration shown in Example 21.14, “Configuration for the Default WS-RM Persistence Store” enables the JDBC-based store that comes with Apache CXF.
Example 21.14. Configuration for the Default WS-RM Persistence Store
<bean id="RMTxStore" class="org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore"/> <wsrm-mgr:rmManager id="org.apache.cxf.ws.rm.RMManager"> <property name="store" ref="RMTxStore"/> </wsrm-mgr:rmManager>
Configuring WS-persistence
The JDBC-based store that comes with Apache CXF supports the properties shown in Table 21.4, “JDBC Store Properties”.
Attribute Name | Type | Default Setting |
---|---|---|
|
| |
| null | |
| null | |
| jdbc:derby:rmdb;create=true |
The configuration shown in Example 21.15, “Configuring the JDBC Store for WS-RM Persistence” enables the JDBC-based store that comes with Apache CXF, while setting the driverClassName
and url
to non-default values.
Example 21.15. Configuring the JDBC Store for WS-RM Persistence
<bean id="RMTxStore" class="org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore"> <property name="driverClassName" value="com.acme.jdbc.Driver"/> <property name="url" value="jdbc:acme:rmdb;create=true"/> </bean>
Chapter 22. Enabling High Availability
Abstract
This chapter explains how to enable and configure high availability in the Apache CXF runtime.
22.1. Introduction to High Availability
Overview
Scalable and reliable applications require high availability to avoid any single point of failure in a distributed system. You can protect your system from single points of failure using replicated services.
A replicated service is comprised of multiple instances, or replicas, of the same service. Together these act as a single logical service. Clients invoke requests on the replicated service, and Apache CXF delivers the requests to one of the member replicas. The routing to a replica is transparent to the client.
HA with static failover
Apache CXF supports high availability (HA) with static failover in which replica details are encoded in the service WSDL file. The WSDL file contains multiple ports, and can contain multiple hosts, for the same service. The number of replicas in the cluster remains static as long as the WSDL file remains unchanged. Changing the cluster size involves editing the WSDL file.
22.2. Enabling HA with Static Failover
Overview
To enable HA with static failover, you must do the following:
Encode replica details in your service WSDL file
You must encode the details of the replicas in your cluster in your service WSDL file. Example 22.1, “Enabling HA with Static Failover: WSDL File” shows a WSDL file extract that defines a service cluster of three replicas.
Example 22.1. Enabling HA with Static Failover: WSDL File
<wsdl:service name="ClusteredService"> <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica1"> <soap:address location="http://localhost:9001/SoapContext/Replica1"/> </wsdl:port> <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica2"> <soap:address location="http://localhost:9002/SoapContext/Replica2"/> </wsdl:port> <wsdl:port binding="tns:Greeter_SOAPBinding" name="Replica3"> <soap:address location="http://localhost:9003/SoapContext/Replica3"/> </wsdl:port> </wsdl:service>
The WSDL extract shown in Example 22.1, “Enabling HA with Static Failover: WSDL File” can be explained as follows:
Defines a service, ClusterService
, which is exposed on three ports:
-
Replica1
-
Replica2
-
Replica3
Defines Replica1
to expose the ClusterService
as a SOAP over HTTP endpoint on port 9001
.
Defines Replica2
to expose the ClusterService
as a SOAP over HTTP endpoint on port 9002
.
Defines Replica3
to expose the ClusterService
as a SOAP over HTTP endpoint on port 9003
.
Add the clustering feature to your client configuration
In your client configuration file, add the clustering feature as shown in Example 22.2, “Enabling HA with Static Failover: Client Configuration”.
Example 22.2. Enabling HA with Static Failover: Client Configuration
<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws" xmlns:clustering="http://cxf.apache.org/clustering" xsi:schemaLocation="http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd"> <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica1" createdFromAPI="true"> <jaxws:features> <clustering:failover/> </jaxws:features> </jaxws:client> <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica2" createdFromAPI="true"> <jaxws:features> <clustering:failover/> </jaxws:features> </jaxws:client> <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica3" createdFromAPI="true"> <jaxws:features> <clustering:failover/> </jaxws:features> </jaxws:client> </beans>
22.3. Configuring HA with Static Failover
Overview
By default, HA with static failover uses a sequential strategy when selecting a replica service if the original service with which a client is communicating becomes unavailable, or fails. The sequential strategy selects a replica service in the same sequential order every time it is used. Selection is determined by Apache CXF’s internal service model and results in a deterministic failover pattern.
Configuring a random strategy
You can configure HA with static failover to use a random strategy instead of the sequential strategy when selecting a replica. The random strategy selects a random replica service each time a service becomes unavailable, or fails. The choice of failover target from the surviving members in a cluster is entirely random.
To configure the random strategy, add the configuration shown in Example 22.3, “Configuring a Random Strategy for Static Failover” to your client configuration file.
Example 22.3. Configuring a Random Strategy for Static Failover
<beans ...> <bean id="Random" class="org.apache.cxf.clustering.RandomStrategy"/> <jaxws:client name="{http://apache.org/hello_world_soap_http}Replica3" createdFromAPI="true"> <jaxws:features> <clustering:failover> <clustering:strategy> <ref bean="Random"/> </clustering:strategy> </clustering:failover> </jaxws:features> </jaxws:client> </beans>
The configuration shown in Example 22.3, “Configuring a Random Strategy for Static Failover” can be explained as follows:
Defines a Random
bean and implementation class that implements the random strategy.
Specifies that the random strategy is used when selecting a replica.
Chapter 23. Apache CXF Binding IDs
Table of Binding IDs
Binding | ID |
---|---|
CORBA | |
HTTP/REST | |
SOAP 1.1 | |
SOAP 1.1 w/ MTOM | |
SOAP 1.2 | |
SOAP 1.2 w/ MTOM | |
XML |
Appendix A. Using the Maven OSGi Tooling
Abstract
Manually creating a bundle, or a collection of bundles, for a large project can be cumbersome. The Maven bundle plug-in makes the job easier by automating the process and providing a number of shortcuts for specifying the contents of the bundle manifest.
A.1. The Maven Bundle Plug-In
The Red Hat Fuse OSGi tooling uses the Maven bundle plug-in from Apache Felix. The bundle plug-in is based on the bnd tool from Peter Kriens. It automates the construction of OSGi bundle manifests by introspecting the contents of the classes being packaged in the bundle. Using the knowledge of the classes contained in the bundle, the plug-in can calculate the proper values to populate the Import-Packages
and the Export-Package
properties in the bundle manifest. The plug-in also has default values that are used for other required properties in the bundle manifest.
To use the bundle plug-in, do the following:
- Section A.2, “Setting up a Red Hat Fuse OSGi project” the bundle plug-in to your project’s POM file.
- Section A.3, “Configuring the Bundle Plug-In” the plug-in to correctly populate your bundle’s manifest.
A.2. Setting up a Red Hat Fuse OSGi project
Overview
A Maven project for building an OSGi bundle can be a simple single level project. It does not require any sub-projects. However, it does require that you do the following:
There are several Maven archetypes you can use to set up your project with the appropriate settings.
Directory structure
A project that constructs an OSGi bundle can be a single level project. It only requires that you have a top-level POM file and a src
folder. As in all Maven projects, you place all Java source code in the src/java
folder, and you place any non-Java resources in the src/resources
folder.
Non-Java resources include Spring configuration files, JBI endpoint configuration files, and WSDL contracts.
Red Hat Fuse OSGi projects that use Apache CXF, Apache Camel, or another Spring configured bean also include a beans.xml
file located in the src/resources/META-INF/spring
folder.
Adding a bundle plug-in
Before you can use the bundle plug-in you must add a dependency on Apache Felix. After you add the dependency, you can add the bundle plug-in to the plug-in portion of the POM.
Example A.1, “Adding an OSGi bundle plug-in to a POM” shows the POM entries required to add the bundle plug-in to your project.
Example A.1. Adding an OSGi bundle plug-in to a POM
... <dependencies> <dependency> <groupId>org.apache.felix</groupId> <artifactId>org.osgi.core</artifactId> <version>1.0.0</version> </dependency> ... </dependencies> ... <build> <plugins> <plugin> <groupId>org.apache.felix</groupId> <artifactId>maven-bundle-plugin</artifactId> <configuration> <instructions> <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName> <Import-Package>*,org.apache.camel.osgi</Import-Package> <Private-Package>org.apache.servicemix.examples.camel</Private-Package> </instructions> </configuration> </plugin> </plugins> </build> ...
The entries in Example A.1, “Adding an OSGi bundle plug-in to a POM” do the following:
Adds the dependency on Apache Felix
Adds the bundle plug-in to your project
Configures the plug-in to use the project’s artifact ID as the bundle’s symbolic name
Configures the plug-in to include all Java packages imported by the bundled classes; also imports the org.apache.camel.osgi package
Configures the plug-in to bundle the listed class, but not to include them in the list of exported packages
Edit the configuration to meet the requirements of your project.
For more information on configuring the bundle plug-in, see Section A.3, “Configuring the Bundle Plug-In”.
Activating a bundle plug-in
To have Maven use the bundle plug-in, instruct it to package the results of the project as a bundle. Do this by setting the POM file’s packaging
element to bundle
.
Useful Maven archetypes
There are several Maven archetypes available to generate a project that is preconfigured to use the bundle plug-in:
Spring OSGi archetype
The Spring OSGi archetype creates a generic project for building an OSGi project using Spring DM, as shown:
org.springframework.osgi/spring-bundle-osgi-archetype/1.1.2
You invoke the archetype using the following command:
mvn archetype:generate -DarchetypeGroupId=org.springframework.osgi -DarchetypeArtifactId=spring-osgi-bundle-archetype -DarchetypeVersion=1.1.2 -DgroupId=groupId -DartifactId=artifactId -Dversion=version
Apache CXF code-first archetype
The Apache CXF code-first archetype creates a project for building a service from Java, as shown:
org.apache.servicemix.tooling/servicemix-osgi-cxf-code-first-archetype/2010.02.0-fuse-02-00
You invoke the archetype using the following command:
mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-cxf-code-first-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version
Apache CXF wsdl-first archetype
The Apache CXF wsdl-first archetype creates a project for creating a service from WSDL, as shown:
org.apache.servicemix.tooling/servicemix-osgi-cxf-wsdl-first-archetype/2010.02.0-fuse-02-00
You invoke the archetype using the following command:
mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-cxf-wsdl-first-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version
Apache Camel archetype
The Apache Camel archetype creates a project for building a route that is deployed into Red Hat Fuse, as shown:
org.apache.servicemix.tooling/servicemix-osgi-camel-archetype/2010.02.0-fuse-02-00
You invoke the archetype using the following command:
mvn archetype:generate -DarchetypeGroupId=org.apache.servicemix.tooling -DarchetypeArtifactId=servicemix-osgi-camel-archetype -DarchetypeVersion=2010.02.0-fuse-02-00 -DgroupId=groupId -DartifactId=artifactId -Dversion=version
A.3. Configuring the Bundle Plug-In
Overview
A bundle plug-in requires very little information to function. All of the required properties use default settings to generate a valid OSGi bundle.
While you can create a valid bundle using just the default values, you will probably want to modify some of the values. You can specify most of the properties inside the plug-in’s instructions
element.
Configuration properties
Some of the commonly used configuration properties are:
Setting a bundle’s symbolic name
By default, the bundle plug-in sets the value for the Bundle-SymbolicName
property to groupId + "." +
artifactId, with the following exceptions:
If groupId has only one section (no dots), the first package name with classes is returned.
For example, if the group Id is
commons-logging:commons-logging
, the bundle’s symbolic name isorg.apache.commons.logging
.If artifactId is equal to the last section of groupId, then groupId is used.
For example, if the POM specifies the group ID and artifact ID as
org.apache.maven:maven
, the bundle’s symbolic name isorg.apache.maven
.If artifactId starts with the last section of groupId, that portion is removed.
For example, if the POM specifies the group ID and artifact ID as
org.apache.maven:maven-core
, the bundle’s symbolic name isorg.apache.maven.core
.
To specify your own value for the bundle’s symbolic name, add a Bundle-SymbolicName
child in the plug-in’s instructions
element, as shown in Example A.2, “Setting a bundle’s symbolic name”.
Example A.2. Setting a bundle’s symbolic name
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<configuration>
<instructions>
<Bundle-SymbolicName>${project.artifactId}</Bundle-SymbolicName>
...
</instructions>
</configuration>
</plugin>
Setting a bundle’s name
By default, a bundle’s name is set to ${project.name}
.
To specify your own value for the bundl