cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > CXF Architecture
Date Thu, 11 Nov 2010 22:06:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true" type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/CXF+Architecture">CXF Architecture</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~gliesian">Robert Liguori</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Reverted from v. 47<br />
    </div>
        <br/>
                         <h4>Changes (100)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{toc:style=outline|maxLevel=2} <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h1. Apache CXF Software Architecture Guide <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Overview <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{info:title=Note...} <br>This guide is awork in progress.  Please feel free to fill in some of the incomplete sections. <br>{info} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">NOTE: this is work in progress. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Table of Contents <br>{toc:style=outline|maxLevel=3} <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">CXF seeks to build the necessary infrastructure components for services. Goals for CXF are many and include: <br>* Support for different bindings, including SOAP, REST, and Corba. <br>* WS-\* support, including WS-Addressing, WS-Security, WS-ReliableMessaging, and WS-Policy <br>* Support for multiple transports <br>* Pluggable Data-bindings <br>* Clean separation of front ends, like JAX-WS, from the core code. <br>* High Performance <br>* Embeddable <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Introduction <br></td></tr>
            <tr><td class="diff-unchanged" >The overall CXF architecture is primarily made up of the following parts: <br></td></tr>
            <tr><td class="diff-changed-lines" ># Bus: This is the backbone of the <span class="diff-added-words"style="background-color: #dfd;">Apache</span> CXF architecture. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;"># Front-ends: Front-ends provide a programming model to create services. <br></td></tr>
            <tr><td class="diff-unchanged" ># Messaging &amp; Interceptors: These provide the low level message and pipeline layer upon which most functionality is built. <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"># Front ends: Frontends provide a programming model to create services (e.g. JAX-WS). <br></td></tr>
            <tr><td class="diff-changed-lines" ># <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Services:</span> <span class="diff-added-words"style="background-color: #dfd;">Service Model:</span> Services host a Service model which is a WSDL-like model <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">which</span> <span class="diff-added-words"style="background-color: #dfd;">that</span> describes the service. <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;"># Bindings: Bindings provide the functionality to interpret the protocol (i.e. SOAP, REST, Corba). <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;"># Pluggable Data Bindings: ...  <br># Protocol Bindings: Bindings provide the functionality to interpret the protocol. <br></td></tr>
            <tr><td class="diff-unchanged" ># Transports: Destinations and Conduits make up the transport abstraction that CXF uses to achieve transport neutrality. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">We&#39;ll</span> <span class="diff-added-words"style="background-color: #dfd;">In the upcoming sections, we&#39;ll</span> take a look at each layer in turn and examine how they work together. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Bus <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">!cxf_architecture.png|thumbnail! <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The bus is a provider of shared resources to the CXF runtime. Examples for such shared resources are: wsdl managers, binding factory managers etc. 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 Tomcat). <br>This is made possible by dependency injection: the default bus implemenation is based on Spring, which wires the runtime components together for you. <br>The SpringBusFactory searches for all bean configuration files  in the META-INF/cxf directories on your classpath, and builds an application context from them. The bean configuration files included in the application context construction are: <br>* META-INF/cxf/cxf.xml (in cxf-rt-core only) <br>* META-INF/cxf/cxf-extension.xml (e.g. in cxf-rt-bindings-soap) <br>* META-INF/cxf/cxf-property-editors.xml (e.g. in cxf-rt-transports-http). <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">See [Configuration of the Bus|Configuration of the Bus] for an example of how to customise the bus by supplying your own bean configuration file and [Configuration of Runtime Constructed Objects|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 container itself). <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Purpose <br>... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Messaging &amp; Interceptors <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Scope <br>This Software Architecture Document (web page) provides an architectural overview of the Apache CXF services framework. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Definitions, Acronyms and Abbreviations <br>* Bus - <br>* Conduit - <br>* CORBA - <br>* Data Binding - <br>* Endpoint - <br>* Fault - <br>* Front-end - <br>* HTTP - <br>* HTTPS - <br>* IDL - <br>* Jabber <br>* JAXB - <br>* JAX-RS - <br>* JAX-WS - <br>* Javadoc - <br>* Java EE - <br>* Javascript - <br>* JBI - <br>* JiBX - <br>* JMS - <br>* Maven - <br>* Protocol Binding - <br>* REST - <br>* SAAJ - <br>* SDO - An acronym for Service Data Object. A ... <br>* Service Model - <br>* SOAP - <br>* Spring Framework - <br>* Transport - <br>* 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. <br>* WS-* - <br>* 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. <br> <br>h3. References <br>* [Software Architecture|http://en.wikipedia.org/wiki/Software_architecture], _Wikipedia_ <br>* [Sample S/W Architecture Document|http://www.ecs.csun.edu/~rlingard/COMP684/Example2SoftArch.htm#Logical%20View], _Rational Software Corporation_ <br>* [Documenting your Software Architecture|http://www.oreillynet.com/xml/blog/2006/03/documenting_your_software_arch.html], _by Jim Alateras_ (March 2006) <br> <br>h2. Architectural Representation <br>... <br> <br>h3. Bus <br>The bus, being CXF&#39;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). <br> <br>This extensibility is made possible by dependency injection; the default bus implemenation is based on [Springhttp://www.springsource.com/developer/spring], which wires the runtime components together for you. <br> <br>The {{SpringBusFactory}} searches for all bean configuration files  in the {{META-INF/cxf}} directories on your classpath, and builds an application context from them. The bean configuration files included in the application context construction are: <br>* {{META-INF/cxf/cxf.xml}} (e.g., in {{cxf-rt-core}} only) <br>* {{META-INF/cxf/cxf-extension.xml}} (e.g. in {{cxf-rt-bindings-soap}}) <br>* {{META-INF/cxf/cxf-property-editors.xml}} (e.g. in {{cxf-rt-transports-http}}) <br> <br>See [Configuration of the Bus|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|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 container itself). <br> <br>h3. Front-ends <br> <br>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|http://cxf.apache.org/docs/frontends.html]. <br> <br>h4. JAX-WS Front-end <br>... <br> <br>h4. JAX-RS Front-end <br>... <br> <br>h4. Simple Front-end <br>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.  <br> <br>h4. Javascript Front-end <br>... <br> <br>h3. Messaging &amp; Interceptors <br> <br></td></tr>
            <tr><td class="diff-unchanged" >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 &amp; resume interceptor chains. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Interceptors have a method, <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>handleMessage<span class="diff-added-chars"style="background-color: #dfd;">}}</span>,</span> which allows them to act on the Message.These Interceptors can then be built up into chains of interceptors, straightforwardly called InterceptorChains. Some examples include: <br></td></tr>
            <tr><td class="diff-unchanged" >* An interceptor which parses just the headers of a SOAP message into DOM elements <br>* A WS-Security interceptor which decrypts or authenticates an incoming message. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >Interceptors are uni-directional and are inherently unaware of whether they are dealing with a request, response, or fault. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">2</span><span class="diff-added-chars"style="background-color: #dfd;">4</span>.</span> Phase Interceptors <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >CXF provides an <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>InterceptorChain<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> implementation called the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>PhaseInterceptorChain<span class="diff-added-chars"style="background-color: #dfd;">}}</span>.</span> When Interceptors are added to the chain, they are grouped into ordered phases.&amp;nbsp; A <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>PhaseInterceptor<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> may provide guidance as to how it is to be ordered within the phase. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >Let us take a hypothetical simplified example (NOTE: these phases and interceptors don&#39;t necessarily exist in CXF). Let us say we are parsing a SOAP message. We may want to have two phases. First, a dispatch phase which parses the soap headers and determines which service to route the Message to. Second, an unmarshal phase which binds the SOAP body to JAXB objects. In the first dispatch phase we could implement this via two interceptors, first a ReadHeadersInterceptor which parses the headers and second a WS-AddressingInInterceptor which determines which service we&#39;re invoking from the WS-Addressing header. In the second unmarshal phase, we have just a single JAXBUnmarshallerIntercptor. Both the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>ReadHeadersInterceptor<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> and <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>AddressingInInterceptor<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> would tell the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>PhaseInterceptorChain<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> they are in the &quot;dispatch&quot; phase by returning &quot;dispatch&quot; when <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>getPhase()<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> is called. Additionally, the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>ReadHeadersInterceptor<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> could specify that it wants to run before the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>AddressingInInterceptor<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> by returning the interceptor id when <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>Interceptor.getBefore()<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> is called. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>Before it was mentioned how chains were very dynamic and flexible. In our above example, we could add interceptors specific to that service once it is resolved. Or we could pause the chain once while we wait for some external chain, like an asynchronous service response. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">2</span><span class="diff-added-chars"style="background-color: #dfd;">4</span>.</span> Fault Handling <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >At any point during processing, an interceptor may throw a Fault, or a derivative of a Fault like the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>SoapFault<span class="diff-added-chars"style="background-color: #dfd;">}}</span>.</span> This will cause the chain to stop invoking and unwind it. Unwinding consists of calling handleFault on each interceptor that was invoked in reverse order. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>InterceptorChains have the concept of a fault interceptor. Once the chain is unwound, the fault interceptor is invoked with the message that caused the fault. The fault interceptor may trigger a new chain which then invokes a specified set of interceptors meant to handle faults. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">2</span><span class="diff-added-chars"style="background-color: #dfd;">4</span>.</span> Exchanges <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >In addition to the concept of a Message, there is the concept of the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>Exchange<span class="diff-added-chars"style="background-color: #dfd;">}}</span>.</span> The exchange class holds a references to  the in, out and fault messages for the current message exchange. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >It also holds properties specific to the exchange, and not just the message. For instance the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>Exchange<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> holds the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>Service<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> that is current being invoked in it. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">2</span><span class="diff-added-chars"style="background-color: #dfd;">4</span>.</span> Reentrant InterceptorChains <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >An interesting feature of the <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>PhaseInterceptorChain<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> 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 <span class="diff-changed-words"><span class="diff-added-chars"style="background-color: #dfd;">{{</span>SoapOutInterceptor<span class="diff-added-chars"style="background-color: #dfd;">}}</span></span> is the best example: <br></td></tr>
            <tr><td class="diff-unchanged" >{code:java} <br>public void handleMessage(Message m) { <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Transports <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. The Service Model <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">CXF includes its own transport abstraction layer to hide transport specific details from the binding and front end layers. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The Service model is the representation of a service within CXF. It is made up of two parts. First there is the {{ServiceInfo}} which contains a WSDL-like model of the service and its operations, bindings, endpoints and schema. Second, there is the Service itself, which contains the {{ServiceInfo}}, data-binding information, service interceptors, service properties and more. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. Conduits <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">A service can be constructed from many different sources including classes and WSDLs (1.1 or 2.0). Typically front-ends are responsible for creating a service via service factories. Factory components such as {{ServerFactoryBean}} and {{ClientProxyFactoryBean}} can used with the front-end to create, publish and consume web services. The factory classes build up the service model and configure the service interceptors, data bindings and more. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Conduits provide the basis for outgoing message sending. A Conduit is created from a ConduitInitiator. Sending a message is a multistep pocess: <br># Call conduit.prepare(message): this starts the message sending. At this point a Conduit may initiate a connection and set the OutputStream for the outgoing message. <br># Writing of the actual message to the OutputStream <br># Call to conduit.close(message): this closes and disposes of any existing  resources for the message sending. <br>A message sender may also register a MessageObserver with the Conduit. If the Conduit is synchronous, the MessageObserver will be notified once a response has been received. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The Service model itself is contained in the {{ServiceInfo}} class. The following image depicts a subset of the Service Model&#39;s packaged API: <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. Destinations <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">!service_model.png|thumbnail! <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Destinations are the basis for receiving incoming messages. A destination is created from a DestinationFactory: <br>{code:java} <br>DestinationFactoryManager dfManager = bus.getExtension(DestinationFactoryManager.class); <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">// Find a DestinationFactory for the SOAP HTTP transport <br>DestinationFactory df = dfManager.getDestinationFactory(&quot;http://schemas.xmlsoap.org/wsdl/soap/http&quot;); <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Pluggable Data Bindings <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">// TODO: outline building of EndpointInfo <br>EndpointInfo endpointInfo = ...; <br>Destination destination = df.getDestination(endpointInfo); <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">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). <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">{code}</span> <span class="diff-added-words"style="background-color: #dfd;"> </span> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">MessageObservers can then be registered with Destinations. These listen for incoming messages: <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Protocol Bindings <br> <br>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&#39;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.   <br> <br>CXF currently supported the following bindings protocols: SOAP 1.1, SOAP 1.2, REST/HTTP, pure XML and CORBA. <br> <br>h3. The Soap Binding <br> <br>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. <br> <br>The {{Soap}} binding also adds a special type of interceptor called the {{SoapInterceptor}}. The {{SoapInterceptor}} adds two methods to the {{Interceptor}} class: <br></td></tr>
            <tr><td class="diff-unchanged" >{code:java} <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">MessageObserver myObserver = ...; <br>destination.setMessageObserver(myObserver); <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Set&lt;URI&gt; getRoles(); <br>Set&lt;QName&gt; getUnderstoodHeaders(); <br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The most common MessageObserver used in CXF is the ChainInitiationObserver. This takes the incoming message, creates a message Exchange &amp; PhaseInterceptorChain, then starts the chain. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">These inform the SOAP interceptors as to what headers and roles the particular SOAP interceptor understands. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Data Bindings <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">It has many interceptors designed to handle SOAP messages: <br># {{StaxInInterceptor}}: Creates an {{XMLStreamReader}} from an incoming {{InputStream}} <br># {{ReadHeadersInterceptor}}: Reads the headers into the {{SoapMessage}} <br># {{MustUnderstandInterceptor}}: Checks the {{MustUnderstand}} attributes of all the headers against all the {{SoapInterceptor}}&#39;s {{getUnderstoodHeaders}} method. <br># {{SoapOutInterceptor}}: <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Data Bindings implement the mapping between XML and Java. 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. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h4. REST/HTTP Binding <br>... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h4. Pure XML Binding <br>... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. The Service Model <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h4. CORBA Binding <br>... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The Service model is the representation of a service within CXF. It is made up of two parts. First there is the ServiceInfo which contains a WSDL-like model of the service and its operations, bindings, and endpoints. Second, there is the Service itself, which contains the ServiceInfo, data-binding information, service interceptors, service properties, and more. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Transports <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">A service can be constructed from many different sources - Classes, WSDL 1.1, and WSDL 2.0. Typically frontends are responsible for creating a service via ServiceFactorys. These build up the service model and configure the service interceptors, databindings, etc. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">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|http://cxf.apache.org/docs/transports.html]. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The Service model itself is  contained in the ServiceInfo class. The hierarchy looks roughly like so: <br>{code} <br>ServiceInfo <br>+-Interface: InterfaceInfo <br>| +-Operations: Collection&lt;OperationInfo&gt; <br>| | +- Input: MessageInfo <br>| | +- Output: MessageInfo <br>| | +- Faults: Collection&lt;MessageInfo&gt; <br>+-Bindings: Collection&lt;BindingInfo&gt; <br>| +-Operations: Collection&lt;BindingOperationInfo&gt; <br>+-Endpoints: Collection&lt;EndpointInfo&gt; <br>{code} <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h4. Conduits <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Bindings <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Conduits provide the basis for outgoing message sending. A {{Conduit}} is created from a {{ConduitInitiator}}. Sending a message is a multistep pocess: <br># Call conduit.prepare(message): this starts the message sending. At this point a {{Conduit}} may initiate a connection and set the OutputStream for the outgoing message. <br># Writing of the actual message to the {{OutputStream}} <br># Call to {{conduit.close(message)}}: this closes and disposes of any existing  resources for the message sending. <br>A message sender may also register a {{MessageObserver}} with the Conduit. If the {{Conduit}} is synchronous, the {{MessageObserver}} will be notified once a response has been received. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Bindings provide ways to map concrete formats &amp; 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&#39;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. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h4. Destinations <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. The Soap Binding <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Destinations are the basis for receiving incoming messages. A destination is created from a {{DestinationFactory}}: <br>{code:java} <br>DestinationFactoryManager dfManager = bus.getExtension(DestinationFactoryManager.class); <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">// Find a DestinationFactory for the SOAP HTTP transport <br>DestinationFactory df = dfManager.getDestinationFactory(&quot;http://schemas.xmlsoap.org/wsdl/soap/http&quot;); <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The Soap binding also adds a special type of interceptor called the SoapInterceptor. The SoapInterceptor adds two methods to the Interceptor class: <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">// TODO: outline building of EndpointInfo <br>EndpointInfo endpointInfo = ...; <br>Destination destination = df.getDestination(endpointInfo); <br>{code} <br>MessageObservers can then be registered with Destinations. These listen for incoming messages: <br></td></tr>
            <tr><td class="diff-unchanged" >{code:java} <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Set&lt;URI&gt; getRoles(); <br>Set&lt;QName&gt; getUnderstoodHeaders(); <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">MessageObserver myObserver = ...; <br>destination.setMessageObserver(myObserver); <br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">These inform the SOAP interceptors as to what headers and roles the particular SOAP interceptor understands. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The most common {{MessageObserver}} used in CXF is the {{ChainInitiationObserver}}. This takes the incoming message, creates a message Exchange &amp; {{PhaseInterceptorChain}}, then starts the chain. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">It has many interceptors designed to handle SOAP messages: <br># StaxInInterceptor: Creates an XMLStreamReader from an incoming InputStream <br># ReadHeadersInterceptor: Reads the headers into the SoapMessage <br># MustUnderstandInterceptor: Checks the MustUnderstand attributes of all the headers against all the SoapInterceptor&#39;s getUnderstoodHeaders method. <br># SoapOutInterceptor: <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Dependencies <br>[CXF&#39;s dependencies|http://cxf.apache.org/docs/cxf-dependency-graphs.html] <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. XML Binding <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Tooling <br>... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. Build Support <br>... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" ><span class="diff-changed-words">h<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">1</span><span class="diff-added-chars"style="background-color: #dfd;">3</span>.</span> Endpoints <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h3. A JAX-WS example <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Front-ends <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Here&#39;s a small example of what might happen when we publish a service via the JAX-WS {{Endpoint.publish()}} method. <br># Call to {{Endpoint.publish(&quot;http://localhost/service&quot;, myService)}} <br># The {{EndpointImpl}} creates a Service from the {{myService}} object using the {{JaxWsServiceFactoryBean}} using the class and/or WSDL <br># An {{EndpointInfo}} is created for the {{Endpoint.publish}} URL <br># A {{JaxWsEndpointImpl}} is created from the {{EndpointInfo}}. This contains the JAX-WS endpoint specific interceptors <br># The {{JaxWsEndpointImpl}} creates a {{Binding}} and {{Destination}} to listen on. <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Frontends provide a programming model to interact with CXF. The primary frontend at the moment is JAX-WS. The JAX-WS implementation is cleanly separated from the rest of CXF -- like the bindings and core. They provide functionality through interceptors that are added to Services and Endpoints. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Architectural Goals and Constraints <br>The Apache CXF services framework seeks to build the necessary infrastructure components for services. Goals for CXF are many and include: <br>* Embeddable <br>* High performance <br>* Easy configuration <br>* Intuitive and easy to use <br>* Clean separation of front-ends from the core code <br>* Data formats support <br>* Data bindings support <br>* Protocol bindings support <br>* Multiple transports support <br>* Multiple Programming Languages Support <br>* WS-\* and related specifications support <br>* Tools for code generation and WSDL validation <br>* Flexible deployment <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h2. JAX-WS <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Deployment View <br>... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Size and Performance <br>... <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">h1. Putting it all Together <br> <br> <br>h2. A JAX-WS example <br> <br>Here&#39;s a small example of what might happen when we publish a service via the JAX-WS Endpoint.publish() method. <br># Call to Endpoint.publish(&quot;http://localhost/service&quot;, myService) <br># The EndpointImpl creates a Service from the myService object using the JaxWsServiceFactoryBean using the class and/or WSDL <br># An EndpointInfo is created for the Endpoint.publish URL <br># A JaxWsEndpointImpl is created from the EndpointInfo. This contains the JAX-WS endpoint specific interceptors <br># The JaxWsEndpointImpl creates a Binding and Destination to listen on. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">h2. Quality  <br>CXF&#39;s Software Quality approach is detailed [here|http://cxf.apache.org/coding-guidelines.html]. <br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="CXFArchitecture-ApacheCXFSoftwareArchitectureGuide"></a>Apache CXF Software Architecture Guide</h1>

<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Note...</b><br />This guide is awork in progress.  Please feel free to fill in some of the incomplete sections.</td></tr></table></div>

<h2><a name="CXFArchitecture-TableofContents"></a>Table of Contents</h2>
<style type='text/css'>/*<![CDATA[*/
div.rbtoc1289513133561 {margin-left: 1.5em;padding: 0px;}
div.rbtoc1289513133561 ul {list-style: outline;margin-left: 0px;}
div.rbtoc1289513133561 li {margin-left: 0px;padding-left: 0px;}

/*]]>*/</style><div class='rbtoc1289513133561'>
<ul>
    <li><a href='#CXFArchitecture-ApacheCXFSoftwareArchitectureGuide'>Apache CXF Software Architecture Guide</a></li>
<ul>
    <li><a href='#CXFArchitecture-TableofContents'>Table of Contents</a></li>
    <li><a href='#CXFArchitecture-Introduction'>Introduction</a></li>
<ul>
    <li><a href='#CXFArchitecture-Purpose'>Purpose</a></li>
    <li><a href='#CXFArchitecture-Scope'>Scope</a></li>
    <li><a href='#CXFArchitecture-Definitions%2CAcronymsandAbbreviations'>Definitions, Acronyms and Abbreviations</a></li>
    <li><a href='#CXFArchitecture-References'>References</a></li>
</ul>
    <li><a href='#CXFArchitecture-ArchitecturalRepresentation'>Architectural Representation</a></li>
<ul>
    <li><a href='#CXFArchitecture-Bus'>Bus</a></li>
    <li><a href='#CXFArchitecture-Frontends'>Front-ends</a></li>
    <li><a href='#CXFArchitecture-Messaging%26Interceptors'>Messaging &amp; Interceptors</a></li>
    <li><a href='#CXFArchitecture-TheServiceModel'>The Service Model</a></li>
    <li><a href='#CXFArchitecture-PluggableDataBindings'>Pluggable Data Bindings</a></li>
    <li><a href='#CXFArchitecture-ProtocolBindings'>Protocol Bindings</a></li>
    <li><a href='#CXFArchitecture-TheSoapBinding'>The Soap Binding</a></li>
    <li><a href='#CXFArchitecture-Transports'>Transports</a></li>
    <li><a href='#CXFArchitecture-Dependencies'>Dependencies</a></li>
    <li><a href='#CXFArchitecture-Tooling'>Tooling</a></li>
    <li><a href='#CXFArchitecture-BuildSupport'>Build Support</a></li>
    <li><a href='#CXFArchitecture-Endpoints'>Endpoints</a></li>
    <li><a href='#CXFArchitecture-AJAXWSexample'>A JAX-WS example</a></li>
</ul>
    <li><a href='#CXFArchitecture-ArchitecturalGoalsandConstraints'>Architectural Goals and Constraints</a></li>
    <li><a href='#CXFArchitecture-DeploymentView'>Deployment View</a></li>
    <li><a href='#CXFArchitecture-SizeandPerformance'>Size and Performance</a></li>
    <li><a href='#CXFArchitecture-Quality'>Quality</a></li>
</ul>
</ul></div>

<h2><a name="CXFArchitecture-Introduction"></a>Introduction</h2>
<p>The overall CXF architecture is primarily made up of the following parts:</p>
<ol>
	<li>Bus: This is the backbone of the Apache CXF architecture.</li>
	<li>Front-ends: Front-ends provide a programming model to create services.</li>
	<li>Messaging &amp; Interceptors: These provide the low level message and pipeline layer upon which most functionality is built.</li>
	<li>Service Model: Services host a Service model which is a WSDL-like model that describes the service.</li>
	<li>Pluggable Data Bindings: ...</li>
	<li>Protocol Bindings: Bindings provide the functionality to interpret the protocol.</li>
	<li>Transports: Destinations and Conduits make up the transport abstraction that CXF uses to achieve transport neutrality.</li>
</ol>


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

<p><span class="image-wrap" style=""><a class="confluence-thumbnail-link 455x305" href='https://cwiki.apache.org/confluence/download/attachments/44806/cxf_architecture.png'><img src="/confluence/download/thumbnails/44806/cxf_architecture.png" style="border: 0px solid black" /></a></span></p>


<h3><a name="CXFArchitecture-Purpose"></a>Purpose</h3>
<p>...</p>

<h3><a name="CXFArchitecture-Scope"></a>Scope</h3>
<p>This Software Architecture Document (web page) provides an architectural overview of the Apache CXF services framework.</p>

<h3><a name="CXFArchitecture-Definitions%2CAcronymsandAbbreviations"></a>Definitions, Acronyms and Abbreviations</h3>
<ul>
	<li>Bus -</li>
	<li>Conduit -</li>
	<li>CORBA -</li>
	<li>Data Binding -</li>
	<li>Endpoint -</li>
	<li>Fault -</li>
	<li>Front-end -</li>
	<li>HTTP -</li>
	<li>HTTPS -</li>
	<li>IDL -</li>
	<li>Jabber</li>
	<li>JAXB -</li>
	<li>JAX-RS -</li>
	<li>JAX-WS -</li>
	<li>Javadoc -</li>
	<li>Java EE -</li>
	<li>Javascript -</li>
	<li>JBI -</li>
	<li>JiBX -</li>
	<li>JMS -</li>
	<li>Maven -</li>
	<li>Protocol Binding -</li>
	<li>REST -</li>
	<li>SAAJ -</li>
	<li>SDO - An acronym for Service Data Object. A ...</li>
	<li>Service Model -</li>
	<li>SOAP -</li>
	<li>Spring Framework -</li>
	<li>Transport -</li>
	<li>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.</li>
	<li>WS-* -</li>
	<li>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.</li>
</ul>


<h3><a name="CXFArchitecture-References"></a>References</h3>
<ul>
	<li><a href="http://en.wikipedia.org/wiki/Software_architecture" class="external-link" rel="nofollow">Software Architecture</a>, <em>Wikipedia</em></li>
	<li><a href="http://www.ecs.csun.edu/~rlingard/COMP684/Example2SoftArch.htm#Logical%20View" class="external-link" rel="nofollow">Sample S/W Architecture Document</a>, <em>Rational Software Corporation</em></li>
	<li><a href="http://www.oreillynet.com/xml/blog/2006/03/documenting_your_software_arch.html" class="external-link" rel="nofollow">Documenting your Software Architecture</a>, <em>by Jim Alateras</em> (March 2006)</li>
</ul>


<h2><a name="CXFArchitecture-ArchitecturalRepresentation"></a>Architectural Representation</h2>
<p>...</p>

<h3><a name="CXFArchitecture-Bus"></a>Bus</h3>
<p>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).</p>

<p>This extensibility is made possible by dependency injection; the default bus implemenation is based on <a href="Springhttp://www.springsource.com/developer/spring" class="external-link" rel="nofollow">Springhttp://www.springsource.com/developer/spring</a>, which wires the runtime components together for you.</p>

<p>The <tt>SpringBusFactory</tt> searches for all bean configuration files  in the <tt>META-INF/cxf</tt> directories on your classpath, and builds an application context from them. The bean configuration files included in the application context construction are:</p>
<ul>
	<li><tt>META-INF/cxf/cxf.xml</tt> (e.g., in <tt>cxf-rt-core</tt> only)</li>
	<li><tt>META-INF/cxf/cxf-extension.xml</tt> (e.g. in <tt>cxf-rt-bindings-soap</tt>)</li>
	<li><tt>META-INF/cxf/cxf-property-editors.xml</tt> (e.g. in <tt>cxf-rt-transports-http</tt>)</li>
</ul>


<p>See <a href="/confluence/display/CXF20DOC/Configuration+of+the+Bus" title="Configuration of the Bus">Configuration of the Bus</a> for an example of how to customize the bus by supplying your own bean configuration file and <a href="/confluence/display/CXF20DOC/Configuration+of+Runtime+Constructed+Objects" title="Configuration of Runtime Constructed Objects">Configuration of Runtime Constructed Objects</a> for more information on the special case of injecting into objects created by the runtime (as opposed to objects created by the IOC container itself).</p>

<h3><a name="CXFArchitecture-Frontends"></a>Front-ends</h3>

<p>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 <a href="http://cxf.apache.org/docs/frontends.html" class="external-link" rel="nofollow">Front-ends</a>.</p>

<h4><a name="CXFArchitecture-JAXWSFrontend"></a>JAX-WS Front-end</h4>
<p>...</p>

<h4><a name="CXFArchitecture-JAXRSFrontend"></a>JAX-RS Front-end</h4>
<p>...</p>

<h4><a name="CXFArchitecture-SimpleFrontend"></a>Simple Front-end</h4>
<p>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. </p>

<h4><a name="CXFArchitecture-JavascriptFrontend"></a>Javascript Front-end</h4>
<p>...</p>

<h3><a name="CXFArchitecture-Messaging%26Interceptors"></a>Messaging &amp; Interceptors</h3>

<p>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 &amp; resume interceptor chains.</p>

<p>Interceptors have a method, <tt>handleMessage</tt>, which allows them to act on the Message.These Interceptors can then be built up into chains of interceptors, straightforwardly called InterceptorChains. Some examples include:</p>
<ul>
	<li>An interceptor which parses just the headers of a SOAP message into DOM elements</li>
	<li>A WS-Security interceptor which decrypts or authenticates an incoming message.</li>
	<li>An outgoing data binding interceptor which serializes the result</li>
</ul>


<p>Interceptors are uni-directional and are inherently unaware of whether they are dealing with a request, response, or fault.</p>

<h4><a name="CXFArchitecture-PhaseInterceptors"></a>Phase Interceptors</h4>

<p>CXF provides an <tt>InterceptorChain</tt> implementation called the <tt>PhaseInterceptorChain</tt>. When Interceptors are added to the chain, they are grouped into ordered phases.&nbsp; A <tt>PhaseInterceptor</tt> may provide guidance as to how it is to be ordered within the phase.</p>

<p>Let us take a hypothetical simplified example (NOTE: these phases and interceptors don't necessarily exist in CXF). Let us say we are parsing a SOAP message. We may want to have two phases. First, a dispatch phase which parses the soap headers and determines which service to route the Message to. Second, an unmarshal phase which binds the SOAP body to JAXB objects. In the first dispatch phase we could implement this via two interceptors, first a ReadHeadersInterceptor which parses the headers and second a WS-AddressingInInterceptor which determines which service we're invoking from the WS-Addressing header. In the second unmarshal phase, we have just a single JAXBUnmarshallerIntercptor. Both the <tt>ReadHeadersInterceptor</tt> and <tt>AddressingInInterceptor</tt> would tell the <tt>PhaseInterceptorChain</tt> they are in the "dispatch" phase by returning "dispatch" when <tt>getPhase()</tt> is called. Additionally, the <tt>ReadHeadersInterceptor</tt> could specify that it wants to run before the <tt>AddressingInInterceptor</tt> by returning the interceptor id when <tt>Interceptor.getBefore()</tt> is called.</p>

<p>Before it was mentioned how chains were very dynamic and flexible. In our above example, we could add interceptors specific to that service once it is resolved. Or we could pause the chain once while we wait for some external chain, like an asynchronous service response.</p>

<h4><a name="CXFArchitecture-FaultHandling"></a>Fault Handling</h4>

<p>At any point during processing, an interceptor may throw a Fault, or a derivative of a Fault like the <tt>SoapFault</tt>. This will cause the chain to stop invoking and unwind it. Unwinding consists of calling handleFault on each interceptor that was invoked in reverse order.</p>

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

<h4><a name="CXFArchitecture-Exchanges"></a>Exchanges</h4>

<p>In addition to the concept of a Message, there is the concept of the <tt>Exchange</tt>. The exchange class holds a references to  the in, out and fault messages for the current message exchange.</p>

<p>It also holds properties specific to the exchange, and not just the message. For instance the <tt>Exchange</tt> holds the <tt>Service</tt> that is current being invoked in it.</p>

<h4><a name="CXFArchitecture-ReentrantInterceptorChains"></a>Reentrant InterceptorChains</h4>

<p>An interesting feature of the <tt>PhaseInterceptorChain</tt> 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 <tt>SoapOutInterceptor</tt> is the best example:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> void handleMessage(Message m) {
  writeSoapEnvelopeStart();
  writeSoapBodyStart();

  <span class="code-comment">// invoke next interceptor, which writes the contents of the SOAP Body
</span>  m.getInterceptorChain().doIntercept(m);
  writeSoapBodyEnd();

  writeSoapEnvelopeEnd();
}
</pre>
</div></div>

<h3><a name="CXFArchitecture-TheServiceModel"></a>The Service Model</h3>

<p>The Service model is the representation of a service within CXF. It is made up of two parts. First there is the <tt>ServiceInfo</tt> which contains a WSDL-like model of the service and its operations, bindings, endpoints and schema. Second, there is the Service itself, which contains the <tt>ServiceInfo</tt>, data-binding information, service interceptors, service properties and more.</p>

<p>A service can be constructed from many different sources including classes and WSDLs (1.1 or 2.0). Typically front-ends are responsible for creating a service via service factories. Factory components such as <tt>ServerFactoryBean</tt> and <tt>ClientProxyFactoryBean</tt> can used with the front-end to create, publish and consume web services. The factory classes build up the service model and configure the service interceptors, data bindings and more.</p>

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

<p><span class="image-wrap" style=""><a class="confluence-thumbnail-link 601x505" href='https://cwiki.apache.org/confluence/download/attachments/44806/service_model.png'><img src="/confluence/download/thumbnails/44806/service_model.png" style="border: 0px solid black" /></a></span></p>


<h3><a name="CXFArchitecture-PluggableDataBindings"></a>Pluggable Data Bindings</h3>

<p>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 <a href="/confluence/display/CXF20DOC/Data+Binding+Architecture" title="Data Binding Architecture">Data Binding Architecture</a> for details. Currently supported data bindings include JAXB 2.x (default), Aegis, Apache XMLBeans, Service Data Objects (SDO) and JiBX (under development).</p>

<h3><a name="CXFArchitecture-ProtocolBindings"></a>Protocol Bindings</h3>

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

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

<h3><a name="CXFArchitecture-TheSoapBinding"></a>The Soap Binding</h3>

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

<p>The <tt>Soap</tt> binding also adds a special type of interceptor called the <tt>SoapInterceptor</tt>. The <tt>SoapInterceptor</tt> adds two methods to the <tt>Interceptor</tt> class:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
Set&lt;URI&gt; getRoles();
Set&lt;QName&gt; getUnderstoodHeaders();
</pre>
</div></div>
<p>These inform the SOAP interceptors as to what headers and roles the particular SOAP interceptor understands.</p>

<p>It has many interceptors designed to handle SOAP messages:</p>
<ol>
	<li><tt>StaxInInterceptor</tt>: Creates an <tt>XMLStreamReader</tt> from an incoming <tt>InputStream</tt></li>
	<li><tt>ReadHeadersInterceptor</tt>: Reads the headers into the <tt>SoapMessage</tt></li>
	<li><tt>MustUnderstandInterceptor</tt>: Checks the <tt>MustUnderstand</tt> attributes of all the headers against all the <tt>SoapInterceptor</tt>'s <tt>getUnderstoodHeaders</tt> method.</li>
	<li><tt>SoapOutInterceptor</tt>:</li>
</ol>


<h4><a name="CXFArchitecture-REST%2FHTTPBinding"></a>REST/HTTP Binding</h4>
<p>...</p>

<h4><a name="CXFArchitecture-PureXMLBinding"></a>Pure XML Binding</h4>
<p>...</p>

<h4><a name="CXFArchitecture-CORBABinding"></a>CORBA Binding</h4>
<p>...</p>

<h3><a name="CXFArchitecture-Transports"></a>Transports</h3>

<p>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 <a href="http://cxf.apache.org/docs/transports.html" class="external-link" rel="nofollow">here</a>.</p>

<h4><a name="CXFArchitecture-Conduits"></a>Conduits</h4>

<p>Conduits provide the basis for outgoing message sending. A <tt>Conduit</tt> is created from a <tt>ConduitInitiator</tt>. Sending a message is a multistep pocess:</p>
<ol>
	<li>Call conduit.prepare(message): this starts the message sending. At this point a <tt>Conduit</tt> may initiate a connection and set the OutputStream for the outgoing message.</li>
	<li>Writing of the actual message to the <tt>OutputStream</tt></li>
	<li>Call to <tt>conduit.close(message)</tt>: this closes and disposes of any existing  resources for the message sending.<br/>
A message sender may also register a <tt>MessageObserver</tt> with the Conduit. If the <tt>Conduit</tt> is synchronous, the <tt>MessageObserver</tt> will be notified once a response has been received.</li>
</ol>


<h4><a name="CXFArchitecture-Destinations"></a>Destinations</h4>

<p>Destinations are the basis for receiving incoming messages. A destination is created from a <tt>DestinationFactory</tt>:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
DestinationFactoryManager dfManager = bus.getExtension(DestinationFactoryManager.class);

<span class="code-comment">// Find a DestinationFactory <span class="code-keyword">for</span> the SOAP HTTP transport
</span>DestinationFactory df = dfManager.getDestinationFactory(<span class="code-quote">"http:<span class="code-comment">//schemas.xmlsoap.org/wsdl/soap/http"</span>);
</span>
<span class="code-comment">// TODO: outline building of EndpointInfo
</span>EndpointInfo endpointInfo = ...;
Destination destination = df.getDestination(endpointInfo);
</pre>
</div></div>
<p>MessageObservers can then be registered with Destinations. These listen for incoming messages:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
MessageObserver myObserver = ...;
destination.setMessageObserver(myObserver);
</pre>
</div></div>
<p>The most common <tt>MessageObserver</tt> used in CXF is the <tt>ChainInitiationObserver</tt>. This takes the incoming message, creates a message Exchange &amp; <tt>PhaseInterceptorChain</tt>, then starts the chain.</p>

<h3><a name="CXFArchitecture-Dependencies"></a>Dependencies</h3>
<p><a href="http://cxf.apache.org/docs/cxf-dependency-graphs.html" class="external-link" rel="nofollow">CXF's dependencies</a></p>

<h3><a name="CXFArchitecture-Tooling"></a>Tooling</h3>
<p>...</p>

<h3><a name="CXFArchitecture-BuildSupport"></a>Build Support</h3>
<p>...</p>

<h3><a name="CXFArchitecture-Endpoints"></a>Endpoints</h3>
<p>...</p>

<h3><a name="CXFArchitecture-AJAXWSexample"></a>A JAX-WS example</h3>

<p>Here's a small example of what might happen when we publish a service via the JAX-WS <tt>Endpoint.publish()</tt> method.</p>
<ol>
	<li>Call to <tt>Endpoint.publish("http://localhost/service", myService)</tt></li>
	<li>The <tt>EndpointImpl</tt> creates a Service from the <tt>myService</tt> object using the <tt>JaxWsServiceFactoryBean</tt> using the class and/or WSDL</li>
	<li>An <tt>EndpointInfo</tt> is created for the <tt>Endpoint.publish</tt> URL</li>
	<li>A <tt>JaxWsEndpointImpl</tt> is created from the <tt>EndpointInfo</tt>. This contains the JAX-WS endpoint specific interceptors</li>
	<li>The <tt>JaxWsEndpointImpl</tt> creates a <tt>Binding</tt> and <tt>Destination</tt> to listen on.</li>
</ol>


<h2><a name="CXFArchitecture-ArchitecturalGoalsandConstraints"></a>Architectural Goals and Constraints</h2>
<p>The Apache CXF services framework seeks to build the necessary infrastructure components for services. Goals for CXF are many and include:</p>
<ul>
	<li>Embeddable</li>
	<li>High performance</li>
	<li>Easy configuration</li>
	<li>Intuitive and easy to use</li>
	<li>Clean separation of front-ends from the core code</li>
	<li>Data formats support</li>
	<li>Data bindings support</li>
	<li>Protocol bindings support</li>
	<li>Multiple transports support</li>
	<li>Multiple Programming Languages Support</li>
	<li>WS-&#42; and related specifications support</li>
	<li>Tools for code generation and WSDL validation</li>
	<li>Flexible deployment</li>
</ul>


<h2><a name="CXFArchitecture-DeploymentView"></a>Deployment View</h2>
<p>...</p>

<h2><a name="CXFArchitecture-SizeandPerformance"></a>Size and Performance</h2>
<p>...</p>

<h2><a name="CXFArchitecture-Quality"></a>Quality </h2>
<p>CXF's Software Quality approach is detailed <a href="http://cxf.apache.org/coding-guidelines.html" class="external-link" rel="nofollow">here</a>.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action" class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/CXF+Architecture">View Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=44806&revisedVersion=49&originalVersion=48">View Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/CXF+Architecture?showComments=true&amp;showCommentArea=true#addcomment">Add Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message