Apache CXF Software Architecture Guide

...

...

This document provides an architectural overview of the Apache CXF services framework.

Table of Contents

...

Architectural Goals and Constraints

The Apache CXF services framework seeks to build the necessary infrastructure components for services. Goals for CXF are many and include:

• Embeddable
• High performance
• Easy configuration
• Intuitive and easy to use
• Clean separation of front-ends from the core code
• Data formats support
• Data bindings support
• Protocol bindings support
• Multiple transports support
• Multiple Programming Languages Support
• WS-* and related specifications support
• Tools for code generation and WSDL validation
• Flexible deployment

CXF-API

The overall CXF architecture is primarily made up of the following parts:

1. Bus: This is the backbone of the Apache CXF architecture.Contains a registry of extensions, interceptors and Properties
2. Front-endsend: Front-ends provide a programming model to create services.
3. Messaging & Interceptors: These provide the low level message and pipeline layer upon which most functionality is built.
4. Service Model: Services host a Service model which is a WSDL-like model that describes the service.
5. Pluggable Data Bindings: ...
6. Protocol Bindings: Bindings provide the functionality to interpret the protocol.
7. Transports: Transportfactory creates Destinations and Conduits make up the transport abstraction that CXF uses to achieve transport neutrality.(Receiving) and Conduits (Sending)

In the upcoming sections, we'll take a look at each layer in turn and examine how they work together.

Image Removed

Purpose

...

Scope

This Software Architecture Document (web page) provides an architectural overview of the Apache CXF services framework.

Definitions, Acronyms and Abbreviations

• Bus -
• Conduit -
• CORBA -
• Data Binding -
• Endpoint -
• Fault -
• Front-end -
• HTTP -
• HTTPS -
• IDL -
• Jabber
• JAXB -
• JAX-RS -
• JAX-WS -
• Javadoc -
• Java EE -
• Javascript -
• JBI -
• JiBX -
• JMS -
• Maven -
• Protocol Binding -
• REST -
• SAAJ -
• SDO - An acronym for Service Data Object. A ...
• Service Model -
• SOAP -
• Spring Framework -
• Transport -
• WSDL - WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information.
• WS-* -
• XML - An acronym for Extensible markup Language. A general-purpose specification used for creating markup languages. This specification allows for the creation of custom tags in structured text files.

References

• Software Architecture, Wikipedia
• Sample S/W Architecture Document, Rational Software Corporation
• Documenting your Software Architecture, by Jim Alateras (March 2006)

Architectural Representation

...

Bus

Image Added

Bus

The bus, being CXF's backbone, is a provider of shared resources to the CXF runtime. Examples for such shared resources include WSDL managers and binding factory managers. The bus can easily be extended to include your own custom resources or services, or you can replace default resources like the HTTP destination factory (based on Jetty) with your own (possibly based on another web container such as Apache Tomcat).

This extensibility is made possible by dependency injection; the default bus implemenation implementation is based on Springhttp://www.springsource.com/developer/spring Spring Framework, which wires the runtime components together for you.

...

• META-INF/cxf/cxf.xml (e.g., in cxf-rt-core only)
• META-INF/cxf/cxf-extension.xml (e.g. in cxf-rt-bindings-soap)
• META-INF/cxf/cxf-property-editors.xml (e.g. in cxf-rt-transports-http)

See Configuration of the Bus for an example of how to customize the bus by supplying your own bean configuration file and Configuration of Runtime Constructed Objects for more information on the special case of injecting into objects created by the runtime (as opposed to objects created by the IOC IoC container itself).

How service calls are processed

Client Side

Server Side

Front-ends

Front-ends provide a programming model to interact with CXF. JAX-WS, JAX-RS, Simple and Javascript front-end APIs are provided by CXF . Each implementation is cleanly separated from the rest of CXF, just like the bindings and the core. Front-ends provide functionality through interceptors that are added to Services and Endpoints. See also Front-ends.

JAX-WS Front-end

...

JAX-RS Front-end

...

Simple Front-end

CXF includes a simple front-end which builds services from reflection. This is in contrast to the JAX-WS frontend which requires you to annotate your web service classes or create a WSDL first. The simple front-end will use reflection to intelligently map your classes to a WSDL model.

Javascript Front-end

...

Messaging & Interceptors

CXF is built on a generic messaging layer comprised of Messages, Interceptors, and InterceptorChains. Interceptors are the fundamental unit of functionality. By dividing up how messages are processed and sent, this gives CXF a very flexible architecture. It can be reconfigured at any point in the processing. This also gives CXF the ability to pause & resume interceptor chains.

...

InterceptorChains have the concept of a fault interceptorobserver. Once the chain is unwound, the fault interceptor is invoked with the message that caused the fault. The fault interceptor observer may trigger a new chain which then invokes a specified set of interceptors meant to handle faults.

...

An interesting feature of the PhaseInterceptorChain is that it is reentrant. This can be powerful and slightly dangerous. This feature is only used in CXF during the sending of an outgoing message, The SoapOutInterceptor is the best example:

public void handleMessage(Message m) {
  writeSoapEnvelopeStart();
  writeSoapBodyStart();

  // invoke next interceptor, which writes the contents of the SOAP Body
  m.getInterceptorChain().doIntercept(m);
  writeSoapBodyEnd();

  writeSoapEnvelopeEnd();
}

...

The Service model itself is contained in the ServiceInfo class. The following image depicts a subset of the Service Model's packaged API:

Image RemovedImage Added

...

Data Bindings

Data bindings implement the mapping between XML elements and Java objects. Data bindings convert data to and from XML, produce XML schema, and provide support for wsdl2java code generation. Not all data bindings support all of this functionality. At very least, a data binding must provide the data conversion. See Data Binding Architecture for details. Currently supported data bindings include JAXB 2.x (default) , Aegis, Apache XMLBeans, Service Data Objects (SDO) and JiBX (under development)and Aegis.

Protocol Bindings

Bindings provide ways to map concrete formats and protocols on top of transports. A binding contains two main parts, a BindingFactory and a Binding. A BindingFactory builds a Binding from the service model's BindingInfo. The binding contains interceptors specific to the binding and also implements the createMessage() method, which creates a Message implementation specific for that binding.

CXF currently supported the following bindings protocols: SOAP 1.1, SOAP 1.2, REST/HTTP, pure XML and CORBA.

The Soap Binding

The prototypical binding is SOAP. It has its own Message class called the SoapMessage. It adds the ability to hold the current SoapVersion and the headers for the message.

The Soap binding also adds a special type of interceptor called the SoapInterceptor. The SoapInterceptor adds two methods to the Interceptor class:

Set<URI> getRoles();
Set<QName> getUnderstoodHeaders();

...

1. StaxInInterceptor: Creates an XMLStreamReader from an incoming InputStream
2. ReadHeadersInterceptor: Reads the headers into the SoapMessage
3. MustUnderstandInterceptor: Checks the MustUnderstand attributes of all the headers against all the SoapInterceptor's getUnderstoodHeaders method.
4. SoapOutInterceptor:

Additional Bindings

Other bindings include REST/HTTP

...

...

Pure XML Binding

...

CORBA Binding

...binding, pure XML binding, and the CORBA binding.

Transports

CXF includes its own transport abstraction layer to hide transport specific details from the binding and front end layers. Currently supported transports include: HTTP, HTTPs, HTTP-Jetty, HTTP-OSGI, Servlet, local, JMS, In-VM and many others via the Camel transport for CXF such as SMTP/POP3, TCP and Jabber. Learn more about transports here.

...

Destinations are the basis for receiving incoming messages. A destination is created from a DestinationFactory:

DestinationFactoryManager dfManager = bus.getExtension(DestinationFactoryManager.class);

// Find a DestinationFactory for the SOAP HTTP transport
DestinationFactory df = dfManager.getDestinationFactory("http://schemas.xmlsoap.org/wsdl/soap/http");

// TODO: outline building of EndpointInfo
EndpointInfo endpointInfo = ...;
Destination destination = df.getDestination(endpointInfo);

MessageObservers can then be registered with Destinations. These listen for incoming messages:

MessageObserver myObserver = ...;
destination.setMessageObserver(myObserver);

The most common MessageObserver used in CXF is the ChainInitiationObserver. This takes the incoming message, creates a message Exchange & PhaseInterceptorChain, then starts the chain.

Dependencies

CXF's dependencies

Tooling

...

Build Support

...

...

...

A JAX-WS example

Here's a small example of what might happen when we publish a service via the JAX-WS Endpoint.publish() method.

1. Call to Endpoint.publish("http://localhost/service", myService)
2. The EndpointImpl creates a Service from the myService object using the JaxWsServiceFactoryBean using the class and/or WSDL
3. An EndpointInfo is created for the Endpoint.publish URL
4. A JaxWsEndpointImpl is created from the EndpointInfo. This contains the JAX-WS endpoint specific interceptors
5. The JaxWsEndpointImpl creates a Binding and Destination to listen on.

Architectural Goals and Constraints

The Apache CXF services framework seeks to build the necessary infrastructure components for services. Goals for CXF are many and include:

• Embeddable
• High performance
• Easy configuration
• Intuitive and easy to use
• Clean separation of front-ends from the core code
• Data formats support
• Data bindings support
• Protocol bindings support
• Multiple transports support
• Multiple Programming Languages Support
• WS-* and related specifications support
• Tools for code generation and WSDL validation
• Flexible deployment

Deployment View

...

Size and Performance

...

Dependencies

CXF's dependencies

Quality

CXF's Software Quality approach is detailed here.

References

• Software Architecture, Wikipedia
• Sample S/W Architecture Document, Rational Software Corporation
• Documenting your Software Architecture, by Jim Alateras (March 2006)