Red Hat JBoss Fuse

Apache CXF Development Guide

Develop applications with Apache CXF Web services

Red Hat

Version 6.1

Legal Notice

Trademark Disclaimer

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Apache, ServiceMix, Camel, CXF, and ActiveMQ are trademarks of Apache Software Foundation. Any other names contained herein may be trademarks of their respective owners.

Legal Notice

Third Party Acknowledgements

One or more products in the Red Hat JBoss Fuse release includes third party components covered by licenses that require that the following documentation notices be provided:
  • JLine (http://jline.sourceforge.net) jline:jline:jar:1.0
    License: BSD (LICENSE.txt) - Copyright (c) 2002-2006, Marc Prud'hommeaux
    All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    • Neither the name of JLine nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • Stax2 API (http://woodstox.codehaus.org/StAX2) org.codehaus.woodstox:stax2-api:jar:3.1.1
    Copyright (c) <YEAR>, <OWNER> All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • jibx-run - JiBX runtime (http://www.jibx.org/main-reactor/jibx-run) org.jibx:jibx-run:bundle:1.2.3
    License: BSD (http://jibx.sourceforge.net/jibx-license.html) Copyright (c) 2003-2010, Dennis M. Sosnoski.
    All rights reserved.
    Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
    • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    • Neither the name of JiBX nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  • JavaAssist (http://www.jboss.org/javassist) org.jboss.javassist:com.springsource.javassist:jar:3.9.0.GA:compile
  • HAPI-OSGI-Base Module (http://hl7api.sourceforge.net/hapi-osgi-base/) ca.uhn.hapi:hapi-osgi-base:bundle:1.2
    License: Mozilla Public License 1.1 (http://www.mozilla.org/MPL/MPL-1.1.txt)
22 Dec 2014

Abstract

REVISIT -
I. Writing WSDL Contracts
1. Introducing WSDL Contracts
1.1. Structure of a WSDL document
1.2. WSDL elements
1.3. Designing a contract
2. Defining Logical Data Units
2.1. Mapping data into logical data units
2.2. Adding data units to a contract
2.3. XML Schema simple types
2.4. Defining complex data types
2.4.1. Defining data structures
2.4.2. Defining arrays
2.4.3. Defining types by extension
2.4.4. Defining types by restriction
2.4.5. Defining enumerated types
2.5. Defining elements
3. Defining Logical Messages Used by a Service
4. Defining Your Logical Interfaces
II. Web Services Bindings
5. Understanding Bindings in WSDL
6. Using SOAP 1.1 Messages
6.1. Adding a SOAP 1.1 Binding
6.2. Adding SOAP Headers to a SOAP 1.1 Binding
7. Using SOAP 1.2 Messages
7.1. Adding a SOAP 1.2 Binding to a WSDL Document
7.2. Adding Headers to a SOAP 1.2 Message
8. Sending Binary Data Using SOAP with Attachments
9. Sending Binary Data with SOAP MTOM
9.1. Annotating Data Types to use MTOM
9.2. Enabling MTOM
9.2.1. Using JAX-WS APIs
9.2.2. Using configuration
10. Using XML Documents
III. Web Services Transports
11. Understanding How Endpoints are Defined in WSDL
12. Using HTTP
12.1. Adding a Basic HTTP Endpoint
12.2. Configuring a Consumer
12.2.1. Using Configuration
12.2.2. Using WSDL
12.2.3. Consumer Cache Control Directives
12.3. Configuring a Service Provider
12.3.1. Using Configuration
12.3.2. Using WSDL
12.3.3. Service Provider Cache Control Directives
12.4. Configuring the Jetty Runtime
12.5. Configuring the Netty Runtime
12.6. Using the HTTP Transport in Decoupled Mode
13. Using SOAP Over JMS
13.1. Basic configuration
13.2. JMS URIs
13.3. WSDL extensions
14. Using Generic JMS
14.1. Using the JMS configuration bean
14.2. Using WSDL to configure JMS
14.2.1. Basic JMS configuration
14.2.2. JMS client configuration
14.2.3. JMS provider configuration
14.3. Using a Named Reply Destination
A. Integrating with Apache ActiveMQ
B. Conduits
IV. Configuring Web Service Endpoints
15. Configuring JAX-WS Endpoints
15.1. Configuring Service Providers
15.1.1. Using the jaxws:endpoint Element
15.1.2. Using the jaxws:server Element
15.1.3. Adding Functionality to Service Providers
15.2. Configuring Consumer Endpoints
16. Apache CXF Logging
16.1. Overview of Apache CXF Logging
16.2. Simple Example of Using Logging
16.3. Default logging configuration file
16.3.1. Configuring Logging Output
16.3.2. Configuring Logging Levels
16.4. Enabling Logging at the Command Line
16.5. Logging for Subsystems and Services
16.6. Logging Message Content
17. Deploying WS-Addressing
17.1. Introduction to WS-Addressing
17.2. WS-Addressing Interceptors
17.3. Enabling WS-Addressing
17.4. Configuring WS-Addressing Attributes
18. Enabling Reliable Messaging
18.1. Introduction to WS-RM
18.2. WS-RM Interceptors
18.3. Enabling WS-RM
18.4. Configuring WS-RM
18.4.1. Configuring Apache CXF-Specific WS-RM Attributes
18.4.2. Configuring Standard WS-RM Policy Attributes
18.4.3. WS-RM Configuration Use Cases
18.5. Configuring WS-RM Persistence
19. Enabling High Availability
19.1. Introduction to High Availability
19.2. Enabling HA with Static Failover
19.3. Configuring HA with Static Failover
20. Enabling High Availability in Fuse Fabric
20.1. Load Balancing Cluster
20.1.1. Introduction to Load Balancing
20.1.2. Configure the Server
20.1.3. Configure the Client
20.2. Failover Cluster
21. Packaging an Application
22. Deploying an Application
C. Apache CXF Binding IDs
D. Using the Maven OSGi Tooling
D.1. Setting up a Red Hat JBoss Fuse OSGi project
D.2. Configuring the Bundle Plug-In
V. Developing Applications Using JAX-WS
23. Bottom-Up Service Development
23.1. Creating the SEI
23.2. Annotating the Code
23.2.1. Required Annotations
23.2.2. Optional Annotations
23.2.3. Apache CXF Annotations
23.3. Generating WSDL
24. Developing a Consumer Without a WSDL Contract
24.1. Creating a Service Object
24.2. Adding a Port to a Service
24.3. Getting a Proxy for an Endpoint
24.4. Implementing the Consumer's Business Logic
25. A Starting Point WSDL Contract
26. Top-Down Service Development
26.1. Generating the Starting Point Code
26.2. Implementing the Service Provider
27. Developing a Consumer From a WSDL Contract
27.1. Generating the Stub Code
27.2. Implementing a Consumer
28. Finding WSDL at Runtime
28.1. Instantiating a Proxy by Injection
28.2. Using a JAX-WS Catalog
28.3. Using a contract resolver
29. Generic Fault Handling
29.1. Runtime Faults
29.2. Protocol Faults
30. Publishing a Service
30.1. APIs Used to Publish a Service
30.2. Publishing a Service in a Plain Java Application
30.3. Publishing a Service in an OSGi Container
31. Basic Data Binding Concepts
31.1. Including and Importing Schema Definitions
31.2. XML Namespace Mapping
31.3. The Object Factory
31.4. Adding Classes to the Runtime Marshaller
32. Using XML Elements
33. Using Simple Types
33.1. Primitive Types
33.2. Simple Types Defined by Restriction
33.3. Enumerations
33.4. Lists
33.5. Unions
33.6. Simple Type Substitution
34. Using Complex Types
34.1. Basic Complex Type Mapping
34.2. Attributes
34.3. Deriving Complex Types from Simple Types
34.4. Deriving Complex Types from Complex Types
34.5. Occurrence Constraints
34.5.1. Occurrence Constraints on the All Element
34.5.2. Occurrence Constraints on the Choice Element
34.5.3. Occurrence Constraints on Elements
34.5.4. Occurrence Constraints on Sequences
34.6. Using Model Groups
35. Using Wild Card Types
35.1. Using Any Elements
35.2. Using the XML Schema anyType Type
35.3. Using Unbound Attributes
36. Element Substitution
36.1. Substitution Groups in XML Schema
36.2. Substitution Groups in Java
36.3. Widget Vendor Example
36.3.1. The checkWidgets Operation
36.3.2. The placeWidgetOrder Operation
37. Customizing How Types are Generated
37.1. Basics of Customizing Type Mappings
37.2. Specifying the Java Class of an XML Schema Primitive
37.3. Generating Java Classes for Simple Types
37.4. Customizing Enumeration Mapping
37.5. Customizing Fixed Value Attribute Mapping
37.6. Specifying the Base Type of an Element or an Attribute
38. Using A JAXBContext Object
39. Using SOAP over JMS
40. Developing Asynchronous Applications
40.1. WSDL for Asynchronous Examples
40.2. Generating the Stub Code
40.3. Implementing an Asynchronous Client with the Polling Approach
40.4. Implementing an Asynchronous Client with the Callback Approach
40.5. Catching Exceptions Returned from a Remote Service
41. Using Raw XML Messages
41.1. Using XML in a Consumer
41.1.1. Usage Modes
41.1.2. Data Types
41.1.3. Working with Dispatch Objects
41.2. Using XML in a Service Provider
41.2.1. Messaging Modes
41.2.2. Data Types
41.2.3. Implementing a Provider Object
42. Working with Contexts
42.1. Understanding Contexts
42.2. Working with Contexts in a Service Implementation
42.3. Working with Contexts in a Consumer Implementation
42.4. Working with JMS Message Properties
42.4.1. Inspecting JMS Message Headers
42.4.2. Inspecting the Message Header Properties
42.4.3. Setting JMS Properties
43. Writing Handlers
43.1. Handlers: An Introduction
43.2. Implementing a Logical Handler
43.3. Handling Messages in a Logical Handler
43.4. Implementing a Protocol Handler
43.5. Handling Messages in a SOAP Handler
43.6. Initializing a Handler
43.7. Handling Fault Messages
43.8. Closing a Handler
43.9. Releasing a Handler
43.10. Configuring Endpoints to Use Handlers
43.10.1. Programmatic Configuration
43.10.2. Spring Configuration
E. Maven Tooling Reference
Plug-in Setup — before you can use the Apache CXF plug-ins, you must first add the proper dependencies and repositories to your POM.
cxf-codegen-plugin — generates JAX-WS compliant Java code from a WSDL document
java2ws — generates a WSDL document from Java code
VI. Developing RESTful Web Services
44. Introduction to RESTful Web Services
45. Creating Resources
45.1. Introduction
45.2. Basic JAX-RS annotations
45.3. Root resource classes
45.4. Working with resource methods
45.5. Working with sub-resources
45.6. Resource selection method
46. Passing Information into Resource Classes and Methods
46.1. Basics of injecting data
46.2. Using JAX-RS APIs
46.2.1. Injecting data from a request URI
46.2.2. Injecting data from the HTTP message header
46.2.3. Injecting data from HTML forms
46.2.4. Specifying a default value to inject
46.3. Using Apache CXF extensions
47. Returning Information to the Consumer
47.1. Returning plain Java constructs
47.2. Fine tuning an application's responses
47.2.1. Basics of building responses
47.2.2. Creating responses for common use cases
47.2.3. Handling more advanced responses
47.3. Returning entities with generic type information
48. Handling Exceptions
48.1. Using WebApplicaitonException exceptions to report errors
48.2. Mapping exceptions to responses
49. Entity Support
50. Getting and Using Context Information
50.1. Introduction to contexts
50.2. Working with the full request URI
50.2.1. Injecting the URI information
50.2.2. Working with the URI
50.2.3. Getting the value of URI template variables
51. Annotation Inheritance
VII. Developing Apache CXF Interceptors
52. Interceptors in the Apache CXF Runtime
53. The Interceptor APIs
54. Determining When the Interceptor is Invoked
54.1. Specifying an interceptor's phase
54.2. Constraining an interceptors placement in a phase
55. Implementing the Interceptors Processing Logic
55.1. Processing messages
55.2. Unwinding after an error
56. Configuring Endpoints to Use Interceptors
56.1. Deciding where to attach interceptors
56.2. Adding interceptors using configuration
56.3. Adding interceptors programmatically
56.3.1. Using the interceptor provider API
56.3.2. Using Java annotations
57. Manipulating Interceptor Chains on the Fly
F. Apache CXF Message Processing Phases
G. Apache CXF Provided Interceptors
G.1. Core Apache CXF Interceptors
G.2. Front-Ends
G.3. Message bindings
G.4. Other features
H. Interceptor Providers
Index