LibraryPrintFeedback

Using the Apache CXF Binding Component

Version 7.1

December 2012
Trademark Disclaimer
Third Party Acknowledgements

Updated: 08 Jan 2014

Table of Contents

1. Introduction to the Apache CXF Binding Component
I. Defining an Endpoint in WSDL
2. Introducing WSDL Contracts
Structure of a WSDL document
WSDL elements
Designing a contract
3. Defining Logical Data Units
Mapping data into logical data units
Adding data units to a contract
XML Schema simple types
Defining complex data types
Defining data structures
Defining arrays
Defining types by extension
Defining types by restriction
Defining enumerated types
Defining elements
4. Defining Logical Messages Used by a Service
5. Defining Your Logical Interfaces
6. Using HTTP
Adding a Basic HTTP Endpoint
Consumer Configuration
Provider Configuration
Using the HTTP Transport in Decoupled Mode
7. Using JMS
Using SOAP/JMS
Basic configuration
JMS URIs
WSDL extensions
Using WSDL to configure JMS
Basic JMS configuration
JMS client configuration
JMS provider configuration
Using a Named Reply Destination
II. Configuring and Packaging Endpoints
8. Introduction to the Apache CXF Binding Component
9. Consumer Endpoints
10. Provider Endpoints
11. Using MTOM to Process Binary Content
12. Working with the JBI Wrapper
13. Using Message Interceptors
III. Configuring the CXF Runtime
14. Configuring the Endpoints to Load Apache CXF Runtime Configuration
15. Transport Configuration
Using the JMS configuration bean
Configuring the Jetty Runtime
16. Deploying WS-Addressing
Introduction to WS-Addressing
WS-Addressing Interceptors
Enabling WS-Addressing
Configuring WS-Addressing Attributes
17. Enabling Reliable Messaging
Introduction to WS-RM
WS-RM Interceptors
Enabling WS-RM
Configuring WS-RM
Configuring Fuse Services Framework-Specific WS-RM Attributes
Configuring Standard WS-RM Policy Attributes
WS-RM Configuration Use Cases
Configuring WS-RM Persistence
A. Consumer Endpoint Properties
B. Provider Endpoint Properties
C. Using the Maven JBI Tooling
Setting up a Fuse ESB Enterprise JBI project
A service unit project
A service assembly project
D. Using the Maven OSGi Tooling
Setting up a Fuse ESB Enterprise OSGi project
Configuring the Bundle Plug-In
Index

List of Figures

6.1. Message Flow in for a Decoupled HTTP Transport
9.1. Consumer Endpoint
10.1. Provider Endpoint
17.1. Web Services Reliable Messaging

List of Tables

3.1. Complex type descriptor elements
4.1. Part data type attributes
5.1. Operation message elements
5.2. Attributes of the input and output elements
6.1. HTTP Consumer Configuration Attributes
6.2. http-conf:client Cache Control Directives
6.3. HTTP Service Provider Configuration Attributes
6.4. http-conf:server Cache Control Directives
7.1. JMS URI variants
7.2. JMS properties settable as URI options
7.3. JNDI properties settable as URI options
7.4. SOAP/JMS WSDL extension elements
7.5. JMS endpoint attributes
7.6. JMS Client WSDL Extensions
7.7. JMS provider endpoint WSDL extensions
13.1. Elements Used to Configure an Endpoint's Interceptor Chain
15.1. General JMS Configuration Properties
15.2. Elements for Configuring a Jetty Runtime Factory
15.3. Elements for Configuring a Jetty Runtime Instance
15.4. Attributes for Configuring a Jetty Thread Pool
16.1. WS-Addressing Interceptors
16.2. WS-Addressing Attributes
17.1. Fuse Services Framework WS-ReliableMessaging Interceptors
17.2. Children of the rmManager Spring Bean
17.3. Children of the WS-Policy RMAssertion Element
17.4. JDBC Store Properties
A.1. Consumer Endpoint Attributes
B.1. Provider Endpoint Attributes
C.1. Service unit archetypes

List of Examples

3.1. Schema entry for a WSDL contract
3.2. Defining an element with a simple type
3.3. Simple Structure
3.4. A complex type
3.5. Simple complex choice type
3.6. Simple complex type with occurrence constraints
3.7. Simple complex type with minOccurs set to zero
3.8. Complex type with an attribute
3.9. Complex type array
3.10. Syntax for a SOAP array derived using wsdl:arrayType
3.11. Definition of a SOAP array
3.12. Syntax for a SOAP array derived using an element
3.13. Type defined by extension
3.14. Using int as the base type
3.15. SSN simple type description
3.16. Syntax for an enumeration
3.17. widgetSize enumeration
4.1. Reused part
4.2. personalInfo lookup method
4.3. RPC WSDL message definitions
4.4. Wrapped document WSDL message definitions
5.1. personalInfo lookup interface
5.2. personalInfo lookup port type
6.1. SOAP 1.1 Port Element
6.2. SOAP 1.2 Port Element
6.3. HTTP Port Element
6.4. HTTP Consumer WSDL Element's Namespace
6.5. WSDL to Configure an HTTP Consumer Endpoint
6.6. HTTP Provider WSDL Element's Namespace
6.7. WSDL to Configure an HTTP Service Provider Endpoint
6.8. Activating WS-Addressing using WSDL
6.9. Activating WS-Addressing using a Policy
6.10. Configuring a Consumer to Use a Decoupled HTTP Endpoint
7.1. SOAP over JMS binding specification
7.2. JMS URI syntax
7.3. SOAP/JMS endpoint address
7.4. Syntax for JMS URI options
7.5. Setting a JNDI property in a JMS URI
7.6. JMS URI that configures a JNDI connection
7.7. WSDL contract with SOAP/JMS configuration
7.8. JMS WSDL extension namespace
7.9. JMS WSDL port specification
7.10. WSDL for a JMS consumer endpoint
7.11. WSDL for a JMS provider endpoint
7.12. JMS Consumer Specification Using a Named Reply Queue
8.1. JBI Descriptor for a Apache CXF Binding Component Service Unit
8.2. Namespace Declaration for Using Apache CXF Binding Component Endpoints
8.3. Schema Location for Using Apache CXF Binding Component Endpoints
9.1. Minimal Consumer Endpoint Configuration
9.2. WSDL with Two Services
9.3. Consumer Endpoint with a Defined Service Name
9.4. Service with Two Endpoints
9.5. Consumer Endpoint with a Defined Endpoint Name
9.6. Consumer Endpoint Configuration Specifying a Target Endpoint
10.1. Minimal Provider Endpoint Configuration
10.2. WSDL with Two Services
10.3. Provider Endpoint with a Defined Service Name
10.4. Service with Two Endpoints
10.5. Provider Endpoint with a Defined Endpoint Name
11.1. Configuring an Endpoint to Use MTOM
12.1. Configuring a Consumer to Not Use the JBI Wrapper
13.1. Configuring an Interceptor Chain
14.1. Provider Endpoint that Loads Apache CXF Runtime Configuration
15.1. Declaring the Spring p-namespace
15.2. JMS configuration bean
15.3. Adding JMS configuration to a JAX-WS client
15.4. Adding JMS configuration to a JMS conduit
15.5. Jetty Runtime Configuration Namespace
15.6. Configuring a Jetty Instance
16.1. client.xml—Adding WS-Addressing Feature to Client Configuration
16.2. server.xml—Adding WS-Addressing Feature to Server Configuration
16.3. Using the Policies to Configure WS-Addressing
17.1. Enabling WS-RM Using Spring Beans
17.2. Configuring WS-RM using WS-Policy
17.3. Adding an RM Policy to Your WSDL File
17.4. Configuring Fuse Services Framework-Specific WS-RM Attributes
17.5. Configuring WS-RM Attributes Using an RMAssertion in an rmManager Spring Bean
17.6. Configuring WS-RM Attributes as a Policy within a Feature
17.7. Configuring WS-RM in an External Attachment
17.8. Setting the WS-RM Base Retransmission Interval
17.9. Setting the WS-RM Exponential Backoff Property
17.10. Setting the WS-RM Acknowledgement Interval
17.11. Setting the WS-RM Maximum Unacknowledged Message Threshold
17.12. Setting the Maximum Length of a WS-RM Message Sequence
17.13. Setting the WS-RM Message Delivery Assurance Policy
17.14. Configuration for the Default WS-RM Persistence Store
17.15. Configuring the JDBC Store for WS-RM Persistence
C.1. POM elements for using Fuse ESB Enterprise Maven tooling
C.2. Top-level POM for a Fuse ESB Enterprise JBI project
C.3. Maven archetype command for service units
C.4. Configuring the maven plug-in to build a service unit
C.5. Specifying the target components for a service unit
C.6. Specifying a target component for a service unit
C.7. POM file for a service unit project
C.8. Maven archetype command for service assemblies
C.9. Configuring the Maven plug-in to build a service assembly
C.10. Specifying the target components for a service unit
C.11. POM for a service assembly project
D.1. Adding an OSGi bundle plug-in to a POM
D.2. Setting a bundle's symbolic name
D.3. Setting a bundle's name
D.4. Setting a bundle's version
D.5. Including a private package in a bundle
D.6. Specifying the packages imported by a bundle

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.

A WSDL document is made up of the following elements:

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:

  1. Breaking the data into logical units that can be mapped into the data types used by the physical implementations of the service

  2. Combining the logical units into messages that are passed between endpoints to carry out the operations

This chapter discusses the first step. Defining Logical Messages Used by a Service discusses the second step.

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.

Depending on how you choose to create your WSDL contract, creating new data definitions requires varying amounts of knowledge. The Fuse Services Framework 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.

Defining the data used in a WSDL contract involves the following steps:

  1. Determine all the data units used in the interface described by the contract.

  2. Create a types element in your contract.

  3. Create a schema element, shown in Example 3.1, as a child of the type element.

    The targetNamespace attribute specifies the namespace under which new data types are defined. The remaining entries should not be changed.


  4. For each complex type that is a collection of elements, define the data type using a complexType element. See Defining data structures.

  5. For each array, define the data type using a complexType element. See Defining arrays.

  6. For each complex type that is derived from a simple type, define the data type using a simpleType element. See Defining types by restriction.

  7. For each enumerated type, define the data type using a simpleType element. See Defining enumerated types.

  8. For each element, define it using an element element. See Defining elements.

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.

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:

For example, the structure shown in Example 3.3 is be defined in XML Schema as a complex type with two elements.


Example 3.4 shows one possible XML Schema mapping for the structure shown in Example 3.3.


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 3.6.


You can also use the minOccurs to make the age field optional by setting the minOccurs to zero as shown in Example 3.7. In this case age can be omitted and the data will still be valid.


Fuse Services Framework 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.

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 3.10.


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 3.11, 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.


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 3.12.


When using this syntax, the element's maxOccurs attribute must always be set to unbounded.

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 3.4 by adding a new element called planet.

Types defined by extension have four parts:

  1. The name of the type is defined by the name attribute of the complexType element.

  2. The complexContent element specifies that the new type will have more than one element.

    [Note]Note

    If you are only adding new attributes to the complex type, you can use a simpleContent element.

  3. The type from which the new type is derived, called the base type, is specified in the base attribute of the extension element.

  4. 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 3.13.


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:

Example 3.15 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.


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.

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.

[Tip]Tip

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.

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 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.

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.

To define a logical interface in a WSDL contract you must do the following:

  1. Create a portType element to contain the interface definition and give it a unique name. See Port types.

  2. Create an operation element for each operation defined in the interface. See Operations.

  3. For each operation, specify the messages used to represent the operation’s parameter list, return type, and exceptions. See 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 5.1.


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 5.2.


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.

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. The attributes are described in Table 6.1.

Table 6.1. HTTP Consumer Configuration Attributes

AttributeDescription
ConnectionTimeout

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

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

ReceiveTimeout

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

0 specifies that the consumer will wait indefinitely.

AutoRedirect

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

MaxRetransmits

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

AllowChunking

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

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

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

  • AutoRedirect is set to true.

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

Accept

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

AcceptLanguage

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

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

AcceptEncoding

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

ContentType

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

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

Host

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

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

Connection

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

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

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

CacheControl

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

Cookie

Specifies a static cookie to be sent with all requests.

BrowserType

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

Referer

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

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

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

DecoupledEndpoint

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

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

ProxyServer

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

ProxyServerPort

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

ProxyServerType

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

  • HTTP(default)

  • SOCKS


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

Table 6.2. http-conf:client Cache Control Directives

DirectiveBehavior
no-cache

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

no-store

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

max-age

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

max-stale

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

min-fresh

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

no-transform

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

only-if-cached

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

cache-extension

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


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. The attributes are described in Table 6.3.

Table 6.3. HTTP Service Provider Configuration Attributes

AttributeDescription
ReceiveTimeout

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

0 specifies that the provider will not timeout.

SuppressClientSendErrors

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

SuppressClientReceiveErrors

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

HonorKeepAlive

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

RedirectURL

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

CacheControl

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

ContentLocation

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

ContentType

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

ContentEncoding

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

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

ServerType

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


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

Table 6.4. http-conf:server Cache Control Directives

DirectiveBehavior
no-cache

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

public

Any cache can store the response.

private

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

no-store

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

no-transform

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

must-revalidate

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

proxy-revalidate

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

max-age

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

s-max-age

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

cache-extension

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


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 6.1 shows the flow of messages when using HTTP in decoupled mode.


A request starts the following process:

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

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

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

  3. The message is sent to the service provider.

  4. The service provider receives the message.

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

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

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

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

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

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

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

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

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

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

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

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

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.

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

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

To use the SOAP/JMS transport:

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

  2. Specify the target destination using a JMS URI.

  3. Optionally, configure the JNDI connection.

  4. Optionally, add additional JMS configuration.

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


Table 7.1 describes the available variants for the JMS URI.


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

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


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

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


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

Table 7.4. SOAP/JMS WSDL extension elements

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

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

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

  • jndi variant—the JNDI name of the destination.

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

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

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

Example 7.7. WSDL contract with SOAP/JMS configuration

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

The WSDL in Example 7.7 does the following:

1

Declare the namespace for the SOAP/JMS extensions.

2

Configure the JNDI connections in the binding scope.

3

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

4

Specify the target destination.

5

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

The 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 7.8 to the definitions element of your contract.


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


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

Consumer endpoints play the role of consumer from the vantage point of other endpoints running inside of the ESB. However, from outside of the ESB a consumer endpoint plays the role of a service provider. As shown in Figure 9.1, consumer endpoints listen from incoming requests from external endpoints. When it receives a request, the consumer passes it off to the NMR fro delivery to endpoint that will process the request. If a response is generated, the consumer endpoint delivers the response back to the external endpoint.


[Important]Important

Because consumer endpoint's behave like service providers to external endpoints, you configure the runtime behavior of the transport using the provider-specific WSDL entries.

To configure a consumer endpoint do the following:

  1. Add a consumer element to your xbean.xml file.

  2. Add a wsdl attribute to the consumer element.

    See Specifying the WSDL.

  3. If your WSDL defines more than one service, you will need to specify a value for the service attribute.

    See Specifying the endpoint details.

  4. If the service you choose defines more than one endpoint, you will need to specify a value for the endpoint attribute.

    See Specifying the endpoint details.

  5. Specify the details for the target of the requests received by the endpoint.

    See Specifying the target endpoint.

  6. If your endpoint is going to be receiving binary attachments set its mtomEnabled attribute to true.

    See Using MTOM to Process Binary Content.

  7. If your endpoint does not need to process the JBI wrapper set its useJbiWrapper attribute to false.

    See Working with the JBI Wrapper.

  8. If you are using any of the advanced features, such as WS-Addressing or WS-Policy, specify a value for the busCfg attribute.

    See Part III.

If the endpoint's WSDL document defines a single service with a single endpoint, the ESB can easily determine which endpoint to use. It will use the values from the WSDL document to specify the service name, endpoint name and interface name for the instantiated endpoint.

However, if the endpoint's WSDL document defines multiple services or if it defines multiple endpoints for a service, you will need to provide the consumer endpoint with additional information so that it can determine the proper definition to use. What information you need to provide depends on the complexity of the WSDL document. You may need to supply values for both the service name and the endpoint name, or you may only have to supply one of these values.

If the WSDL document contains more than one service element you will need to specify a value for the consumer's service attribute. The value of the consumer's service attribute is the QName of the WSDL service element that defines the desired service in the WSDL document. For example, if you wanted your endpoint to use the WidgetSalesService in the WSDL shown in Example 9.2 you would use the configuration shown in Example 9.3.



If the WSDL document's service definition contains more than one endpoint, then you will need to provide a value for the consumer's endpoint attribute. The value of the endpoint attribute corresponds to the value of the WSDL port element's name attribute. For example, if you wanted your endpoint to use the WidgetEasternSalesPort in the WSDL shown in Example 9.4 you would use the configuration shown in Example 9.5.



To configure a provider endpoint do the following:

  1. Add a provider element to your xbean.xml file.

  2. Add a wsdl attribute to the provider element.

    See Specifying the WSDL.

  3. If your WSDL defines more than one service, you will need to specify a value for the service attribute.

    See Specifying the endpoint details.

  4. If the service you choose defines more than one endpoint, you will need to specify a value for the endpoint attribute.

    See Specifying the endpoint details.

  5. If your endpoint is going to be receiving binary attachments set its mtomEnabled attribute to true.

    See Using MTOM to Process Binary Content.

  6. If your endpoint does not need to process the JBI wrapper set its useJbiWrapper attribute to false.

    See Working with the JBI Wrapper.

  7. If you are using any of the advanced features, such as WS-Addressing or WS-Policy, specify a value for the busCfg attribute.

    See Part III.

If the endpoint's WSDL document defines a single service with a single endpoint, the ESB can easily determine which endpoint to use. It will use the values from the WSDL document to specify the service name, endpoint name and interface name for the instantiated endpoint.

However, if the endpoint's WSDL document defines multiple services or if it defines multiple endpoints for a service, you will need to provide the provider endpoint with additional information so that it can determine the proper definition to use. What information you need to provide depends on the complexity of the WSDL document. You may need to supply values for both the service name and the endpoint name, or you may only have to supply one of these values.

If the WSDL document contains more than one service element you will need to specify a value for the provider's service attribute. The value of the provider's service attribute is the QName of the WSDL service element that defines the desired service in the WSDL document. For example, if you wanted your endpoint to use the WidgetInventoryService in the WSDL shown in Example 10.2 you would use the configuration shown in Example 10.3.



If the WSDL document's service definition contains more than one endpoint, then you will need to provide a value for the provider's endpoint attribute. The value of the endpoint attribute corresponds to the value of the WSDL port element's name attribute. For example, if you wanted your endpoint to use the WidgetWesternSalesPort in the WSDL shown in Example 10.4 you would use the configuration shown in Example 10.5.



A Apache CXF binding component endpoint's interceptor chain has four points at which you can insert an interceptor:

An endpoint's interceptor chain is configured using children of its consumer element or provider element. Table 13.1 lists the elements used to configure an endpoint's interceptor chain.


Example 13.1 shows a consumer endpoint configured to use the Apache CXF logging interceptors.


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

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

Table 15.1. General JMS Configuration Properties

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

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

  • 1(NON_PERSISTENT)—messages will be kept memory

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

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

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


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

[Tip]Tip

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

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

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


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 17.1.


The flow of WS-RM messages can be described as follows:

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.

To enable WS-RM add the WS-RM and WS-Addressing interceptors to the Fuse Services Framework 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 17.1).

Example 17.1. Enabling WS-RM Using Spring Beans

<?xml version="1.0" encoding="UTF-8"?>
1<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">
2   <bean id="mapAggregator" class="org.apache.cxf.ws.addressing.MAPAggregator"/>
   <bean id="mapCodec" class="org.apache.cxf.ws.addressing.soap.MAPCodec"/>
3   <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">
4        <property name="inInterceptors">
            <list>
                <ref bean="mapAggregator"/>
                <ref bean="mapCodec"/>
                <ref bean="rmLogicalIn"/>
                <ref bean="rmCodec"/>
            </list>
        </property>
5        <property name="inFaultInterceptors">
            <list>
                <ref bean="mapAggregator"/>
                <ref bean="mapCodec"/>
                <ref bean="rmLogicalIn"/>
                <ref bean="rmCodec"/>
            </list>
        </property>
6        <property name="outInterceptors">
            <list>
                <ref bean="mapAggregator"/>
                <ref bean="mapCodec"/>
                <ref bean="rmLogicalOut"/>
                <ref bean="rmCodec"/>
            </list>
        </property>
7        <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 17.1 can be explained as follows:

1

A Fuse Services Framework 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.

2

Configures each of the WS-Addressing interceptors—MAPAggregator and MAPCodec. For more information on WS-Addressing, see Deploying WS-Addressing.

3

Configures each of the WS-RM interceptors—RMOutInterceptor, RMInInterceptor, and RMSoapInterceptor.

4

Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for inbound messages.

5

Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for inbound faults.

6

Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for outbound messages.

7

Adds the WS-Addressing and WS-RM interceptors to the interceptor chain for outbound faults.

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 Fuse Services Framework WS-Policy framework, do the following:

  1. Add the policy feature to your client and server endpoint. Example 17.2 shows a reference bean nested within a jaxws:feature element. The reference bean specifies the AddressingPolicy, which is defined as a separate element within the same configuration file.


  2. 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 17.3.


You can configure WS-RM by:

  • Setting Fuse Services Framework-specific attributes that are defined in the Fuse Services Framework WS-RM manager namespace, http://cxf.apache.org/ws/rm/manager.

  • Setting standard WS-RM policy attributes that are defined in the http://schemas.xmlsoap.org/ws/2005/02/rm/policy namespace.

The attributes described in Table A.1 are used to configure a consumer endpoint.


The attributes described in Table B.1 are used to configure a provider endpoint.


Fuse ESB Enterprise provides a Maven plug-in and a number of Maven archetypes that make developing, packaging, and deploying JBI artifacts easier. The tooling provides you with a number of benefits including:

Because Fuse ESB Enterprise only allows you to deploy service assemblies, you will need to do the following when using the Maven JBI tooling:

  1. Set up a top-level project to build all of the service units and the final service assembly.

  2. Create a project for each of your service units..

  3. Create a project for the service assembly.

Example C.2 shows a top-level POM for a project that contains a single service unit.

Example C.2. Top-level POM for a Fuse ESB Enterprise JBI project

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>com.widgets</groupId>
    <artifactId>demos</artifactId>
    <version>1.0</version>
  </parent>

  <groupId>com.widgets.demo</groupId>
  <artifactId>cxf-wsdl-first</artifactId>
  <name>CXF WSDL Fisrt Demo</name>
  <packaging>pom</packaging>
    
  <pluginRepositories> 1
    <pluginRepository>
      <id>fusesource.m2</id>
      <name> Open Source Community Release Repository</name>
      <url>http://repo.fusesource.com/maven2</url>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <releases>
        <enabled>true</enabled>
      </releases>
    </pluginRepository>
  </pluginRepositories>
  <repositories>
    <repository>
      <id>fusesource.m2</id>
      <name> Open Source Community Release Repository</name>
      <url>http://repo.fusesource.com/maven2</url>
      <snapshots>
         <enabled>false</enabled>
      </snapshots>
      <releases>
        <enabled>true</enabled>
      </releases>
    </repository>
    <repository>
      <id>fusesource.m2-snapshot</id>
      <name> Open Source Community Snapshot Repository</name>
      <url>http://repo.fusesource.com/maven2-snapshot</url>
      <snapshots>
        <enabled>true</enabled>
      </snapshots>
      <releases>
        <enabled>false</enabled>
      </releases>
    </repository>
  </repositories>
    
  <modules> 2
    <module>wsdl-first-cxfse-su</module>
     <module>wsdl-first-cxf-sa</module>
  </modules>
    
  <build>
    <plugins>
      <plugin> 3
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-assembly-plugin</artifactId>
         <version>2.1</version>
         <inherited>false</inherited>
           <executions>
             <execution>
                <id>src</id>
                <phase>package</phase>
                <goals>
                  <goal>single</goal>
                </goals>
                <configuration>
                  <descriptors>
                    <descriptor>src/main/assembly/src.xml</descriptor>
                  </descriptors>
                 </configuration>
               </execution>
             </executions>
           </plugin>
           <plugin> 4
             <groupId>org.apache.servicemix.tooling</groupId>
             <artifactId>jbi-maven-plugin</artifactId>
             <extensions>true</extensions>
           </plugin>
    </plugins>
  </build>
</project>

The top-level POM shown in Example C.2 does the following:

1

Configures Maven to use the repositories for loading the Fuse ESB Enterprise plug-ins.

2

Lists the sub-projects used for this application. The wsdl-first-cxfse-su module is the module for the service unit. The wsdl-first-cxf-sa module is the module for the service assembly

3

Configures the Maven assembly plug-in.

4

Loads the Fuse ESB Enterprise JBI plug-in.

Fuse ESB Enterprise provides Maven artifacts for a number of service unit types. They can be used to seed a project with the smx-arch command. As shown in Example C.3, the smx-arch command takes three arguments. The groupId value and the artifactId values correspond to the project's group ID and artifact ID.


[Important]Important

The double quotes(") are required when using the -DgroupId argument and the -DartifactId argument.

The suArchetypeName specifies the type of service unit to seed. Table C.1 lists the possible values and describes what type of project is seeded.

Table C.1. Service unit archetypes

NameDescription
camelCreates a project for using the Apache Camel service engine
cxf-seCreates a project for developing a Java-first service using the Apache CXF service engine
cxf-se-wsdl-firstCreates a project for developing a WSDL-first service using the Apache CXF service engine
cxf-bcCreates an endpoint project targeted at the Apache CXF binding component
http-consumerCreates a consumer endpoint project targeted at the HTTP binding component
http-providerCreates a provider endpoint project targeted at the HTTP binding component
jms-consumerCreates a consumer endpoint project targeted at the JMS binding component (see Using the JMS Binding Component)
jms-providerCreates a provider endpoint project targeted at the JMS binding component (see Using the JMS Binding Component)
file-pollerCreates a polling (consumer) endpoint project targeted at the file binding component (see Using Poller Endpoints in Using the File Binding Component)
file-senderCreates a sender (provider) endpoint project targeted at the file binding component (see Using Sender Endpoints in Using the File Binding Component)
ftp-pollerCreates a polling (consumer) endpoint project targeted at the FTP binding component
ftp-senderCreates a sender (provider) endpoint project targeted at the FTP binding component
jsr181-annotatedCreates a project for developing an annotated Java service to be run by the JSR181 service engine [a]
jsr181-wsdl-firstCreates a project for developing a WSDL generated Java service to be run by the JSR181 service engine [a]
saxon-xqueryCreates a project for executing xquery statements using the Saxon service engine
saxon-xsltCreates a project for executing XSLT scripts using the Saxon service engine
eipCreates a project for using the EIP service engine. [b]
lwcontainerCreates a project for deploying functionality into the lightweight container [c]
beanCreates a project for deploying a POJO to be executed by the bean service engine
odeCreate a project for deploying a BPEL process into the ODE service engine

[a] The JSR181 has been deprecated. The Apache CXF service engine has superseded it.

[b] The EIP service engine has been deprecated. The Apache Camel service engine has superseded it.

[c] The lightweight container has been deprecated.


To correctly fill in the metadata required for packaging a service unit, the Maven plug-in must be told what component (or components) the service unit is targeting. If your service unit only has a single component dependency, you can specify it in one of two ways:

  • List the targeted component as a dependency

  • Add a componentName property specifying the targeted component

If your service unit has more than one component dependency, you must configure the project as follows:

  1. Add a componentName property specifying the targeted component.

  2. Add the remaining components to the list dependencies.

Example C.5 shows the configuration for a service unit targeting the Apache CXF binding component.


The advantage of using the Maven dependency mechanism is that it allows Maven to verify if the targeted component is deployed in the container. If one of the components is not deployed, Fuse ESB Enterprise will not hold off deploying the service unit until all of the required components are deployed.

[Tip]Tip

Typically, a message identifying the missing component(s) is written to the log.

If your service unit's targeted component is not available as a Maven artifact, you can specify the targeted component using the componentName element. This element is added to the standard Maven properties block and it specifies the name of a targeted component, as specified in Example C.6.


When you use the componentName element, Maven does not check to see if the component is installed, nor does it download the required component.

Example C.7 shows the POM file for a project that is building a service unit targeted to the Apache CXF binding component.

Example C.7. POM file for a service unit project

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent> 1
        <groupId>com.widgets.demo</groupId>
        <artifactId>cxf-wsdl-first</artifactId>
        <version>1.0</version>
    </parent>

  <groupId>com.widgets.demo.cxf-wsdl-first</groupId>
  <artifactId>cxfse-wsdl-first-su</artifactId>
  <name>CXF WSDL Fisrt Demo :: SE Service Unit</name>
  <packaging>jbi-service-unit</packaging> 2

  <dependencies> 3
    <dependency>
      <groupId>org.apache.servicemix</groupId>
      <artifactId>servicemix-cxf-bc</artifactId>
      <version>3.3.1.0-fuse</version>
    </dependency>
  >/dependencies>

  <build>
    <plugins>
      <plugin> 4
        <groupId>org.apache.servicemix.tooling</groupId>
        <artifactId>jbi-maven-plugin</artifactId>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
</project>

The POM file in Example C.7 does the following:

1

Specifies that it is a part of the top-level project shown in Example C.2

2

Specifies that this project builds a service unit

3

Specifies that the service unit targets the Apache CXF binding component

4

Specifies to use the Fuse ESB Enterprise Maven plug-in



[1] You replace this with the version of Apache CXF you are using.

Example C.11 shows a POM file for a project that is building a service assembly.

Example C.11. POM for a service assembly project

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <parent> 1
        <groupId>com.widgets.demo</groupId>
        <artifactId>cxf-wsdl-first</artifactId>
        <version>1.0</version>
    </parent>

  <groupId>com.widgets.demo.cxf-wsdl-first</groupId>
  <artifactId>cxf-wsdl-first-sa</artifactId>
  <name>CXF WSDL Fisrt Demo ::  Service Assemby</name>
  <packaging>jbi-service-assembly</packaging> 2

  <dependencies> 3
    <dependency>
      <groupId>com.widgets.demo.cxf-wsdl-first</groupId>
      <artifactId>cxfse-wsdl-first-su</artifactId>
      <version>1.0</version>
    </dependency>
    <dependency>
      <groupId>com.widgets.demo.cxf-wsdl-first</groupId>
      <artifactId>cxfbc-wsdl-first-su</artifactId>
      <version>1.0</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin> 4
        <groupId>org.apache.servicemix.tooling</groupId>
        <artifactId>jbi-maven-plugin</artifactId>
        <extensions>true</extensions>
      </plugin>
    </plugins>
  </build>
</project>

The POM in Example C.11 does the following:

1

Specifies that it is a part of the top-level project shown in Example C.2

2

Specifies that this project builds a service assembly

3

Specifies the service units being bundled by the service assembly

4

Specifies to use the Fuse ESB Enterprise Maven plug-in

The Fuse ESB Enterprise 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:

  1. Add the bundle plug-in to your project's POM file.

  2. Configure the plug-in to correctly populate your bundle's manifest.

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:

  1. Add the bundle plug-in to your POM.

  2. Instruct Maven to package the results as an OSGi bundle.

[Tip]Tip

There are several Maven archetypes you can use to set up your project with the appropriate settings.

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 D.1 shows the POM entries required to add the bundle plug-in to your project.

Example D.1. Adding an OSGi bundle plug-in to a POM

...
<dependencies>
  <dependency> 1
    <groupId>org.apache.felix</groupId>
    <artifactId>org.osgi.core</artifactId>
    <version>1.0.0</version>
  </dependency>
...
</dependencies>
...
<build>
  <plugins>
    <plugin> 2
      <groupId>org.apache.felix</groupId>
      <artifactId>maven-bundle-plugin</artifactId>
      <configuration>
        <instructions>
          <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName> 3
          <Import-Package>*,org.apache.camel.osgi</Import-Package> 4
          <Private-Package>org.apache.servicemix.examples.camel</Private-Package> 5
        </instructions>
      </configuration> 
    </plugin>
  </plugins>
</build>
...

The entries in Example D.1 do the following:

1

Adds the dependency on Apache Felix

2

Adds the bundle plug-in to your project

3

Configures the plug-in to use the project's artifact ID as the bundle's symbolic name

4

Configures the plug-in to include all Java packages imported by the bundled classes; also imports the org.apache.camel.osgi package

5

Configures the plug-in to bundle the listed class, but not to include them in the list of exported packages

[Note]Note

Edit the configuration to meet the requirements of your project.

For more information on configuring the bundle plug-in, see Configuring the Bundle Plug-In.

By default, the OSGi manifest's Export-Package list is populated by all of the packages in your local Java source code (under src/main/java), except for the deault package, ., and any packages containing .impl or .internal.

[Important]Important

If you use a Private-Package element in your plug-in configuration and you do not specify a list of packages to export, the default behavior includes only the packages listed in the Private-Package element in the bundle. No packages are exported.

The default behavior can result in very large packages and in exporting packages that should be kept private. To change the list of exported packages you can add an Export-Package child to the plug-in's instructions element.

The Export-Package element specifies a list of packages that are to be included in the bundle and that are to be exported. The package names can be specified using the * wildcard symbol. For example, the entry com.fuse.demo.* includes all packages on the project's classpath that start with com.fuse.demo.

You can specify packages to be excluded be prefixing the entry with !. For example, the entry !com.fuse.demo.private excludes the package com.fuse.demo.private.

When excluding packages, the order of entries in the list is important. The list is processed in order from the beginning and any subsequent contradicting entries are ignored.

For example, to include all packages starting with com.fuse.demo except the package com.fuse.demo.private, list the packages using:

!com.fuse.demo.private,com.fuse.demo.*

However, if you list the packages using com.fuse.demo.*,!com.fuse.demo.private, then com.fuse.demo.private is included in the bundle because it matches the first pattern.

B

BaseRetransmissionInterval, Base retransmission interval
binding element, WSDL elements
Bundle-Name, Setting a bundle's name
Bundle-SymbolicName, Setting a bundle's symbolic name
Bundle-Version, Setting a bundle's version
bundles
exporting packages, Specifying exported packages
importing packages, Specifying imported packages
name, Setting a bundle's name
private packages, Specifying private packages
symbolic name, Setting a bundle's symbolic name
version, Setting a bundle's version

D

definitions element, WSDL elements
driverClassName, Configuring WS-persistence

H

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

J

jbi.xml, Contents of a file component service unit
JMS
specifying the message type, Specifying the message type
JMS destination
specifying, Specifying the JMS address
jms:address, Specifying the JMS address
connectionPassword attribute, Specifying the JMS address
connectionUserName attribute, Specifying the JMS address
destinationStyle attribute, Specifying the JMS address
jmsDestinationName attribute, Specifying the JMS address
jmsiReplyDestinationName attribute, Using a Named Reply Destination
jmsReplyDestinationName attribute, Specifying the JMS address
jndiConnectionFactoryName attribute, Specifying the JMS address
jndiDestinationName attribute, Specifying the JMS address
jndiReplyDestinationName attribute, Specifying the JMS address, Using a Named Reply Destination
jms:client, Specifying the message type
messageType attribute, Specifying the message type
jms:JMSNamingProperties, Specifying JNDI properties
jms:server, Specifying the configuration
durableSubscriberName, Specifying the configuration
messageSelector, Specifying the configuration
transactional, Specifying the configuration
useMessageIDAsCorrealationID, Specifying the configuration
JMSConfiguration, Specifying the configuration
JNDI
specifying the connection factory, Specifying the JMS address

L

logical part, The logical part

N

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

S

Sequence, How WS-RM works
sequence element, Complex type varieties
SequenceAcknowledgment, How WS-RM works
service assembly
seeding, Seeding a project using a Maven artifact
specifying the service units, Specifying the target components
service element, WSDL elements
service unit
seeding, Seeding a project using a Maven artifact
specifying the target component, Specifying the target components
smx-arch, Seeding a project using a Maven artifact, Seeding a project using a Maven artifact
SOAP 1.1
endpoint address, SOAP 1.1
SOAP 1.2
endpoint address, SOAP 1.2
soap12:address, SOAP 1.2
soap:address, SOAP 1.1

T

types element, WSDL elements

W

wrapped document style, Message design for SOAP services
WS-Addressing
using, Configuring an endpoint to use WS-Addressing
WS-RM
AcknowledgementInterval, Acknowledgement interval
AtLeastOnce, Message delivery assurance policies
AtMostOnce, Message delivery assurance policies
BaseRetransmissionInterval, Base retransmission interval
configuring, Configuring WS-RM
destination, How WS-RM works
driverClassName, Configuring WS-persistence
enabling, Enabling WS-RM
ExponentialBackoff, Exponential backoff for retransmission
externaL attachment, External attachment
initial sender, How WS-RM works
InOrder, Message delivery assurance policies
interceptors, Fuse Services Framework WS-RM Interceptors
maxLength, Maximum length of an RM sequence
maxUnacknowledged, Maximum unacknowledged messages threshold
passWord, Configuring WS-persistence
rmManager, Children of the rmManager Spring bean
source, How WS-RM works
ultimate receiver, How WS-RM works
url, Configuring WS-persistence
userName, Configuring WS-persistence
wsam:Addressing, Configuring an endpoint to use WS-Addressing
WSDL design
RPC style, Message design for integrating with legacy systems
wrapped document style, Message design for SOAP services
WSDL extensors
jms:address (see jms:address)
jms:client (see jms:client)
jms:JMSNamingProperties (see jms:JMSNamingProperties)
jms:server (see jms:server)
wsrm:AcksTo, How WS-RM works
wswa:UsingAddressing, Configuring an endpoint to use WS-Addressing