Repository: camel Updated Branches: refs/heads/master bcc55a2a0 -> f6d04c8df
Add camel-cxf docs to gitbook Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/f6d04c8d Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/f6d04c8d Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/f6d04c8d Branch: refs/heads/master Commit: f6d04c8df1c3403a6c8dd01f5b8008e6b0602339 Parents: bcc55a2 Author: Andrea Cosentino <anco...@gmail.com> Authored: Thu Mar 17 15:44:42 2016 +0100 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Thu Mar 17 15:45:01 2016 +0100 ---------------------------------------------------------------------- components/camel-cxf/src/main/docs/cxf.adoc | 1030 ++++++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 1031 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/f6d04c8d/components/camel-cxf/src/main/docs/cxf.adoc ---------------------------------------------------------------------- diff --git a/components/camel-cxf/src/main/docs/cxf.adoc b/components/camel-cxf/src/main/docs/cxf.adoc new file mode 100644 index 0000000..fdd17a1 --- /dev/null +++ b/components/camel-cxf/src/main/docs/cxf.adoc @@ -0,0 +1,1030 @@ +[[CXF-CXFComponent]] +CXF Component +~~~~~~~~~~~~~ + +[Note] +==== + + +When using CXF as a consumer, the link:cxf-bean-component.html[CXF Bean +Component] allows you to factor out how message payloads are received +from their processing as a RESTful or SOAP web service. This has the +potential of using a multitude of transports to consume web services. +The bean component's configuration is also simpler and provides the +fastest method to implement web services using Camel and CXF. + +==== + +[Tip] +==== + + +When using CXF in streaming modes (see DataFormat option), then also +read about link:stream-caching.html[Stream caching]. + +==== + +The *cxf:* component provides integration with +http://cxf.apache.org[Apache CXF] for connecting to JAX-WS services +hosted in CXF. + +* link:#CXF-CXFComponent[CXF Component] +** link:#CXF-URIformat[URI format] +** link:#CXF-Options[Options] +*** link:#CXF-Thedescriptionsofthedataformats[The descriptions of the +dataformats] +**** link:#CXF-HowtoenableCXFLoggingOutInterceptorinMESSAGEmode[How to +enable CXF's LoggingOutInterceptor in MESSAGE mode] +*** link:#CXF-DescriptionofrelayHeadersoption[Description of +relayHeaders option] +**** link:#CXF-AvailableonlyinPOJOmode[Available only in POJO mode] +**** link:#CXF-ChangessinceRelease2.0[Changes since Release 2.0] +** link:#CXF-ConfiguretheCXFendpointswithSpring[Configure the CXF +endpoints with Spring] +** +link:#CXF-ConfiguringtheCXFEndpointswithApacheAriesBlueprint.[Configuring +the CXF Endpoints with Apache Aries Blueprint.] +** +link:#CXF-Howtomakethecamel-cxfcomponentuselog4jinsteadofjava.util.logging[How +to make the camel-cxf component use log4j instead of java.util.logging] +** link:#CXF-Howtoletcamel-cxfresponsemessagewithxmlstartdocument[How to +let camel-cxf response message with xml start document] +** link:#CXF-HowtooverridetheCXFproduceraddressfrommessageheader[How to +override the CXF producer address from message header] +** +link:#CXF-Howtoconsumeamessagefromacamel-cxfendpointinPOJOdataformat[How +to consume a message from a camel-cxf endpoint in POJO data format] +** +link:#CXF-Howtopreparethemessageforthecamel-cxfendpointinPOJOdataformat[How +to prepare the message for the camel-cxf endpoint in POJO data format] +** +link:#CXF-Howtodealwiththemessageforacamel-cxfendpointinPAYLOADdataformat[How +to deal with the message for a camel-cxf endpoint in PAYLOAD data +format] +** link:#CXF-HowtogetandsetSOAPheadersinPOJOmode[How to get and set SOAP +headers in POJO mode] +** link:#CXF-HowtogetandsetSOAPheadersinPAYLOADmode[How to get and set +SOAP headers in PAYLOAD mode] +** link:#CXF-SOAPheadersarenotavailableinMESSAGEmode[SOAP headers are +not available in MESSAGE mode] +** link:#CXF-HowtothrowaSOAPFaultfromCamel[How to throw a SOAP Fault +from Camel] +** +link:#CXF-Howtopropagateacamel-cxfendpointrequestandresponsecontext[How +to propagate a camel-cxf endpoint's request and response context] +** link:#CXF-AttachmentSupport[Attachment Support] +** link:#CXF-StreamingSupportinPAYLOADmode[Streaming Support in PAYLOAD +mode] +** link:#CXF-UsingthegenericCXFDispatchmode[Using the generic CXF +Dispatch mode] +** link:#CXF-SeeAlso[See Also] + +Maven users will need to add the following dependency to their `pom.xml` +for this component: + +[source,xml] +------------------------------------------------------------ +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-cxf</artifactId> + <version>x.x.x</version> + <!-- use the same version as your Camel core version --> +</dependency> +------------------------------------------------------------ + +[Tip] +==== +CXF dependencies + +If you want to learn about CXF dependencies you can checkout the +`WHICH-JARS` text file. + +==== + +[[CXF-URIformat]] +URI format +^^^^^^^^^^ + +[source,java] +------------------------------ +cxf:bean:cxfEndpoint[?options] +------------------------------ + +Where *cxfEndpoint* represents a bean ID that references a bean in the +Spring bean registry. With this URI format, most of the endpoint details +are specified in the bean definition. + +[source,java] +--------------------------- +cxf://someAddress[?options] +--------------------------- + +Where *someAddress* specifies the CXF endpoint's address. With this URI +format, most of the endpoint details are specified using options. + +For either style above, you can append options to the URI as follows: + +[source,java] +--------------------------------------------------------------------- +cxf:bean:cxfEndpoint?wsdlURL=wsdl/hello_world.wsdl&dataFormat=PAYLOAD +--------------------------------------------------------------------- + +[[CXF-Options]] +Options +^^^^^^^ + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Name |Required |Description + +|`wsdlURL` |No |The location of the WSDL. It is obtained from endpoint address by +default. _Example_: file://local/wsdl/hello.wsdl[file://local/wsdl/hello.wsdl] +or `wsdl/hello.wsdl` + +|`serviceClass` |Yes |The name of the SEI (Service Endpoint Interface) class. This class can +have, but does not require, JSR181 annotations. + + This option is only required by POJO mode. If the wsdlURL option is +provided, serviceClass is not required for PAYLOAD and MESSAGE mode. +When wsdlURL option is used without serviceClass, the serviceName and +portName (endpointName for Spring configuration) options *MUST* be +provided. It is possible to use `#` notation to reference a +`serviceClass` object instance from the registry. E.g. +`serviceClass=#beanName`. The `serviceClass` for a CXF producer (that +is, the `to` endpoint) should be a Java interface. + + *Since 2.8,* it is possible to omit both wsdlURL and serviceClass +options for PAYLOAD and MESSAGE mode. When they are omitted, arbitrary +XML elements can be put in CxfPayload's body in PAYLOAD mode to +facilitate CXF Dispatch Mode. + Please be advised that the *referenced object cannot be a Proxy* +(Spring AOP Proxy is OK) as it relies on `Object.getClass().getName()` +method for non Spring AOP Proxy. + _Example_: `org.apache.camel.Hello` + +|`serviceName` |No |The service name this service is implementing, it maps to the +`wsdl:service@name`. + *Required* for camel-cxf consumer since camel-2.2.0 or if more than one +`serviceName` is present in WSDL. + _Example_: \{http:Â//org.apache.camel}ServiceName + +|`endpointName` |No |The port name this service is implementing, it maps to the +`wsdl:port@name`. + *Required* for camel-cxf consumer since camel-2.2.0 or if more than one +`portName` is present under `serviceName`. + _Example_: \{http:Â//org.apache.camel}PortName + +|`dataFormat` |No |The data type messages supported by the CXF endpoint. + _Default_: `POJO` + _Example_: `POJO`, `PAYLOAD`, `MESSAGE` + +|`relayHeaders` |No |Please see the *Description of* `relayHeaders` *option* section for this +option. Should a CXF endpoint relay headers along the route. Currently +only available when `dataFormat=POJO` + _Default_: `true` + _Example_: `true`, `false` + +|`wrapped` |No |Which kind of operation that CXF endpoint producer will invoke + + _Default_: `false` + _Example_: `true`, `false` + +|`wrappedStyle` |No |*New in 2.5.0* The WSDL style that describes how parameters are +represented in the SOAP body. If the value is false, CXF will chose the +document-literal unwrapped style, If the value is true, CXF will chose +the document-literal wrapped style + _Default_: `Null` + _Example_: `true`, `false` + +|`setDefaultBus` |No |*Deprecated* Will set the default bus when CXF endpoint create a bus by +itself. This option is deprecated use defaultBus from Camel 2.16 +onwards. + _Default_: `false` + _Example_: `true`, `false` + +|`defaultBus` |No |*Camel 2.16:* Will set the default bus when CXF endpoint create a bus by +itself + _Default_: `false` + _Example_: `true`, `false` + +|`bus` |No |A default bus created by CXF Bus Factory. Use `#` notation to reference +a bus object from the registry. The referenced object must be an +instance of `org.apache.cxf.Bus`. + _Example_: `bus=#busName` + +|`cxfBinding` |No |Use `#` notation to reference a CXF binding object from the registry. +The referenced object must be an instance of +`org.apache.camel.component.cxf.CxfBinding` (use an instance of +`org.apache.camel.component.cxf.DefaultCxfBinding`). + _Example_: `cxfBinding=#bindingName` + +|`headerFilterStrategy` |No |Use `#` notation to reference a header filter strategy object from the +registry. The referenced object must be an instance of +`org.apache.camel.spi.HeaderFilterStrategy` (use an instance of +`org.apache.camel.component.cxf.CxfHeaderFilterStrategy`). + _Example_: `headerFilterStrategy=#strategyName` + +|`loggingFeatureEnabled` |No |New in 2.3. This option enables CXF Logging Feature which writes inbound +and outbound SOAP messages to log. + _Default_: `false` + + _Example_: `loggingFeatureEnabled``=true` + +|`defaultOperationName` |No |New in 2.4, this option will set the default operationName that will be +used by the CxfProducer which invokes the remote service. + _Default_: `null` + + _Example_: `defaultOperationName``=greetMe` + +|`defaultOperationNamespace` |No |New in 2.4. This option will set the default operationNamespace that +will be used by the CxfProducer which invokes the remote service. + _Default_: `null` + _Example_: +`defaultOperationNamespace``=``http://apache.org/hello_world_soap_http` + +|`synchronous` |No |New in 2.5. This option will let cxf endpoint decide to use sync or +async API to do the underlying work. The default value is false which +means camel-cxf endpoint will try to use async API by default. + _Default_: `false` + _Example_: synchronous=true + +|`publishedEndpointUrl` |No |New in 2.5. This option can override the endpointUrl that published from +the WSDL which can be accessed with service address url plus ?wsdl. + _Default_: `null` + _Example_: publshedEndpointUrl=http://example.com/service[http://example.com/service] + +|`properties.XXX` |No |*Camel 2.8:* Allows to set custom properties to CXF in the endpoint uri. +For example setting `properties.mtom-enabled=true` to enable MTOM. +`properties.org.apache.cxf.interceptor.OneWayProcessorInterceptor.USE_ORIGINAL_THREAD=true `just +make sure the CXF doesn't switch the thread when start the invocation. + +|`allowStreaming` |No |New in *Camel 2.8.2*. This option controls whether the CXF component, +when running in PAYLOAD mode (see below), will DOM parse the incoming +messages into DOM Elements or keep the payload as a +javax.xml.transform.Source object that would allow streaming in some +cases. + +|`skipFaultLogging` |No |New in *Camel 2.11*. This option controls whether the +PhaseInterceptorChain skips logging the Fault that it catches. + +|`cxfEndpointConfigurer` |No |New in *Camel 2.11*. This option could apply the implementation of +`org.apache.camel.component.cxf.CxfEndpointConfigurer which `supports to +configure the CXF endpoint in  programmatic way. Since *Camel +2.15.0,*user can configure the CXF server and client by implementing +configure\{Server|Client} method of `CxfEndpointConfigurer`. + +|`username` |No |New in *Camel 2.12.3* This option is used to set the basic +authentication information of username for the CXF client. + +|`password` |No |New in *Camel 2.12.3* This option is used to set the basic +authentication information of password for the CXF client. + +|`continuationTimeout` |No |New in *Camel 2.14.0*This option is used to set the CXF continuation +timeout which could be used in CxfConsumer by default when the CXF +server is using Jetty or Servlet transport. (Before *Camel 2.14.0*, +CxfConsumer just set the continuation timeout to be 0, which means the +continuation suspend operation never timeout.) +_Default_: 30000 + _Example_: continuation=80000 +|======================================================================= + +The `serviceName` and `portName` are +http://en.wikipedia.org/wiki/QName[QNames], so if you provide them be +sure to prefix them with their \{namespace} as shown in the examples +above. + +[[CXF-Thedescriptionsofthedataformats]] +The descriptions of the dataformats ++++++++++++++++++++++++++++++++++++ + +[width="100%",cols="50%,50%",options="header",] +|======================================================================= +|DataFormat |Description + +|`POJO` |POJOs (Plain old Java objects) are the Java parameters to the method +being invoked on the target server. Both Protocol and Logical JAX-WS +handlers are supported. + +|`PAYLOAD` |`PAYLOAD` is the message payload (the contents of the `soap:body`) after +message configuration in the CXF endpoint is applied. Only Protocol +JAX-WS handler is supported. Logical JAX-WS handler is not supported. + +|`MESSAGE` |`MESSAGE` is the raw message that is received from the transport layer. +It is not suppose to touch or change Stream, some of the CXF +interceptors will be removed if you are using this kind of DataFormat so +you can't see any soap headers after the camel-cxf consumer and JAX-WS +handler is not supported. + +|`CXF_MESSAGE` |New in *Camel 2.8.2*, `CXF_MESSAGE` allows for invoking the full +capabilities of CXF interceptors by converting the message from the +transport layer into a raw SOAP message +|======================================================================= + +You can determine the data format mode of an exchange by retrieving the +exchange property, `CamelCXFDataFormat`. The exchange key constant is +defined in +`org.apache.camel.component.cxf.CxfConstants.DATA_FORMAT_PROPERTY`. + +[[CXF-HowtoenableCXFLoggingOutInterceptorinMESSAGEmode]] +How to enable CXF's LoggingOutInterceptor in MESSAGE mode + +CXF's `LoggingOutInterceptor` outputs outbound message that goes on the +wire to logging system (Java Util Logging). Since the +`LoggingOutInterceptor` is in `PRE_STREAM` phase (but `PRE_STREAM` phase +is removed in `MESSAGE` mode), you have to configure +`LoggingOutInterceptor` to be run during the `WRITE` phase. The +following is an example. + +[source,xml] +------------------------------------------------------------------------------------------------------- +<bean id="loggingOutInterceptor" class="org.apache.cxf.interceptor.LoggingOutInterceptor"> + <!-- it really should have been user-prestream but CXF does have such phase! --> + <constructor-arg value="target/write"/> +</bean> + +<cxf:cxfEndpoint id="serviceEndpoint" address="http://localhost:${CXFTestSupport.port2}/LoggingInterceptorInMessageModeTest/helloworld"; + serviceClass="org.apache.camel.component.cxf.HelloService"> + <cxf:outInterceptors> + <ref bean="loggingOutInterceptor"/> + </cxf:outInterceptors> + <cxf:properties> + <entry key="dataFormat" value="MESSAGE"/> + </cxf:properties> +</cxf:cxfEndpoint> +------------------------------------------------------------------------------------------------------- + +[[CXF-DescriptionofrelayHeadersoption]] +Description of relayHeaders option +++++++++++++++++++++++++++++++++++ + +There are _in-band_ and _out-of-band_ on-the-wire headers from the +perspective of a JAXWS WSDL-first developer. + +The _in-band_ headers are headers that are explicitly defined as part of +the WSDL binding contract for an endpoint such as SOAP headers. + +The _out-of-band_ headers are headers that are serialized over the wire, +but are not explicitly part of the WSDL binding contract. + +Headers relaying/filtering is bi-directional. + +When a route has a CXF endpoint and the developer needs to have +on-the-wire headers, such as SOAP headers, be relayed along the route to +be consumed say by another JAXWS endpoint, then `relayHeaders` should be +set to `true`, which is the default value. + +[[CXF-AvailableonlyinPOJOmode]] +Available only in POJO mode + +The `relayHeaders=true` express an intent to relay the headers. The +actual decision on whether a given header is relayed is delegated to a +pluggable instance that implements the `MessageHeadersRelay` interface. +A concrete implementation of `MessageHeadersRelay` will be consulted to +decide if a header needs to be relayed or not. There is already an +implementation of `SoapMessageHeadersRelay` which binds itself to +well-known SOAP name spaces. Currently only out-of-band headers are +filtered, and in-band headers will always be relayed when +`relayHeaders=true`. If there is a header on the wire, whose name space +is unknown to the runtime, then a fall back `DefaultMessageHeadersRelay` +will be used, which simply allows all headers to be relayed. + +The `relayHeaders=false` setting asserts that all headers in-band and +out-of-band will be dropped. + +You can plugin your own `MessageHeadersRelay` implementations overriding +or adding additional ones to the list of relays. In order to override a +preloaded relay instance just make sure that your `MessageHeadersRelay` +implementation services the same name spaces as the one you looking to +override. Also note, that the overriding relay has to service all of the +name spaces as the one you looking to override, or else a runtime +exception on route start up will be thrown as this would introduce an +ambiguity in name spaces to relay instance mappings. + +[source,xml] +------------------------------------------------------------------------------------------------------- +<cxf:cxfEndpoint ...> + <cxf:properties> + <entry key="org.apache.camel.cxf.message.headers.relays"> + <list> + <ref bean="customHeadersRelay"/> + </list> + </entry> + </cxf:properties> + </cxf:cxfEndpoint> + <bean id="customHeadersRelay" class="org.apache.camel.component.cxf.soap.headers.CustomHeadersRelay"/> +------------------------------------------------------------------------------------------------------- + +Take a look at the tests that show how you'd be able to relay/drop +headers here: + +https://svn.apache.org/repos/asf/camel/branches/camel-1.x/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/soap/headers/CxfMessageHeadersRelayTest.java[https://svn.apache.org/repos/asf/camel/branches/camel-1.x/components/camel-cxf/src/test/java/org/apache/camel/component/cxf/soap/headers/CxfMessageHeadersRelayTest.java] + +[[CXF-ChangessinceRelease2.0]] +Changes since Release 2.0 + +* `POJO` and `PAYLOAD` modes are supported. In `POJO` mode, only +out-of-band message headers are available for filtering as the in-band +headers have been processed and removed from header list by CXF. The +in-band headers are incorporated into the `MessageContentList` in POJO +mode. The `camel-cxf` component does make any attempt to remove the +in-band headers from the `MessageContentList`. If filtering of in-band +headers is required, please use `PAYLOAD` mode or plug in a (pretty +straightforward) CXF interceptor/JAXWS Handler to the CXF endpoint. +* The Message Header Relay mechanism has been merged into +`CxfHeaderFilterStrategy`. The `relayHeaders` option, its semantics, and +default value remain the same, but it is a property of +`CxfHeaderFilterStrategy`. + Here is an example of configuring it. + +[source,xml] +------------------------------------------------------------------------------------------------------- +<bean id="dropAllMessageHeadersStrategy" class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStrategy"> + + <!-- Set relayHeaders to false to drop all SOAP headers --> + <property name="relayHeaders" value="false"/> + +</bean> +------------------------------------------------------------------------------------------------------- + +Then, your endpoint can reference the `CxfHeaderFilterStrategy`. + +[source,xml] +------------------------------------------------------------------------------------------------------- +<route> + <from uri="cxf:bean:routerNoRelayEndpoint?headerFilterStrategy=#dropAllMessageHeadersStrategy"/> + <to uri="cxf:bean:serviceNoRelayEndpoint?headerFilterStrategy=#dropAllMessageHeadersStrategy"/> +</route> +------------------------------------------------------------------------------------------------------- + +* The `MessageHeadersRelay` interface has changed slightly and has been +renamed to `MessageHeaderFilter`. It is a property of +`CxfHeaderFilterStrategy`. Here is an example of configuring user +defined Message Header Filters: + +[source,xml] +------------------------------------------------------------------------------------------------------- +<bean id="customMessageFilterStrategy" class="org.apache.camel.component.cxf.common.header.CxfHeaderFilterStrategy"> + <property name="messageHeaderFilters"> + <list> + <!-- SoapMessageHeaderFilter is the built in filter. It can be removed by omitting it. --> + <bean class="org.apache.camel.component.cxf.common.header.SoapMessageHeaderFilter"/> + + <!-- Add custom filter here --> + <bean class="org.apache.camel.component.cxf.soap.headers.CustomHeaderFilter"/> + </list> + </property> +</bean> +------------------------------------------------------------------------------------------------------- + +* Other than `relayHeaders`, there are new properties that can be +configured in `CxfHeaderFilterStrategy`. + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Name |Required |Description +|`relayHeaders` |No |All message headers will be processed by Message Header Filters + _Type_: `boolean` + _Default_: `true` + +|`relayAllMessageHeaders` | No |All message headers will be propagated (without processing by Message +Header Filters) + _Type_: `boolean` + _Default_: `false` + +|`allowFilterNamespaceClash` |No |If two filters overlap in activation namespace, the property control how +it should be handled. If the value is `true`, last one wins. If the +value is `false`, it will throw an exception + _Type_: `boolean` + _Default_: `false` +|======================================================================= + +[[CXF-ConfiguretheCXFendpointswithSpring]] +Configure the CXF endpoints with Spring +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can configure the CXF endpoint with the Spring configuration file +shown below, and you can also embed the endpoint into the `camelContext` +tags. When you are invoking the service endpoint, you can set the +`operationName` and `operationNamespace` headers to explicitly state +which operation you are calling. + +[source,xml] +---------------------------------------------------------------------------------------------------------------- +<beans xmlns="http://www.springframework.org/schema/beans"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xmlns:cxf="http://camel.apache.org/schema/cxf"; + xsi:schemaLocation=" + http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd + http://camel.apache.org/schema/cxf http://camel.apache.org/schema/cxf/camel-cxf.xsd + http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd";> + <cxf:cxfEndpoint id="routerEndpoint" address="http://localhost:9003/CamelContext/RouterPort"; + serviceClass="org.apache.hello_world_soap_http.GreeterImpl"/> + <cxf:cxfEndpoint id="serviceEndpoint" address="http://localhost:9000/SoapContext/SoapPort"; + wsdlURL="testutils/hello_world.wsdl" + serviceClass="org.apache.hello_world_soap_http.Greeter" + endpointName="s:SoapPort" + serviceName="s:SOAPService" + xmlns:s="http://apache.org/hello_world_soap_http"; /> + <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring";> + <route> + <from uri="cxf:bean:routerEndpoint" /> + <to uri="cxf:bean:serviceEndpoint" /> + </route> + </camelContext> + </beans> +---------------------------------------------------------------------------------------------------------------- + +Be sure to include the JAX-WS `schemaLocation` attribute specified on +the root beans element. This allows CXF to validate the file and is +required. Also note the namespace declarations at the end of the +`<cxf:cxfEndpoint/>` tag--these are required because the combined +\{`namespace}localName` syntax is presently not supported for this tag's +attribute values. + +The `cxf:cxfEndpoint` element supports many additional attributes: + +[width="100%",cols="50%,50%",options="header",] +|======================================================================= +|Name |Value + +|`PortName` |The endpoint name this service is implementing, it maps to the +`wsdl:port@name`. In the format of `ns:PORT_NAME` where `ns` is a +namespace prefix valid at this scope. + +|`serviceName` |The service name this service is implementing, it maps to the +`wsdl:service@name`. In the format of `ns:SERVICE_NAME` where `ns` is a +namespace prefix valid at this scope. + +|`wsdlURL` |The location of the WSDL. Can be on the classpath, file system, or be +hosted remotely. + +|`bindingId` |The `bindingId` for the service model to use. + +|`address` |The service publish address. + +|`bus` |The bus name that will be used in the JAX-WS endpoint. + +|`serviceClass` |The class name of the SEI (Service Endpoint Interface) class which could +have JSR181 annotation or not. +|======================================================================= + +It also supports many child elements: + +[width="100%",cols="50%,50%",options="header",] +|======================================================================= +|Name |Value + +|`cxf:inInterceptors` |The incoming interceptors for this endpoint. A list of `<bean>` or +`<ref>`. + +|`cxf:inFaultInterceptors` |The incoming fault interceptors for this endpoint. A list of `<bean>` or +`<ref>`. + +|`cxf:outInterceptors` |The outgoing interceptors for this endpoint. A list of `<bean>` or +`<ref>`. + +|`cxf:outFaultInterceptors` |The outgoing fault interceptors for this endpoint. A list of `<bean>` or +`<ref>`. + +|`cxf:properties` | A properties map which should be supplied to the JAX-WS endpoint. See +below. + +|`cxf:handlers` |A JAX-WS handler list which should be supplied to the JAX-WS endpoint. +See below. + +|`cxf:dataBinding` |You can specify the which `DataBinding` will be use in the endpoint. +This can be supplied using the Spring `<bean class="MyDataBinding"/>` +syntax. + +|`cxf:binding` |You can specify the `BindingFactory` for this endpoint to use. This can +be supplied using the Spring `<bean class="MyBindingFactory"/>` syntax. + +|`cxf:features` |The features that hold the interceptors for this endpoint. A list of +beans or refs + +|`cxf:schemaLocations` |The schema locations for endpoint to use. A list of schemaLocations + +|`cxf:serviceFactory` |The service factory for this endpoint to use. This can be supplied using +the Spring `<bean class="MyServiceFactory"/>` syntax +|======================================================================= + +You can find more advanced examples that show how to provide +interceptors, properties and handlers on the CXF +https://cwiki.apache.org/CXF20DOC/JAX-WS+Configuration[JAX-WS +Configuration page]. + +*NOTE* + You can use cxf:properties to set the camel-cxf endpoint's dataFormat +and setDefaultBus properties from spring configuration file. + +[source,xml] +------------------------------------------------------------------------- +<cxf:cxfEndpoint id="testEndpoint" address="http://localhost:9000/router"; + serviceClass="org.apache.camel.component.cxf.HelloService" + endpointName="s:PortName" + serviceName="s:ServiceName" + xmlns:s="http://www.example.com/test";> + <cxf:properties> + <entry key="dataFormat" value="MESSAGE"/> + <entry key="setDefaultBus" value="true"/> + </cxf:properties> + </cxf:cxfEndpoint> +------------------------------------------------------------------------- + +[[CXF-ConfiguringtheCXFEndpointswithApacheAriesBlueprint.]] +Configuring the CXF Endpoints with Apache Aries Blueprint. +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since camel 2.8 there is support for utilizing aries blueprint +dependency injection for your CXF endpoints. + The schema utilized is very similar to the spring schema so the +transition is fairly transparent. + +Example + +[source,xml] +------------------------------------------------------------------------------------------------------------------------------------ +<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"; + xmlns:camel-cxf="http://camel.apache.org/schema/blueprint/cxf"; + xmlns:cxfcore="http://cxf.apache.org/blueprint/core"; + xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd";> + + <camel-cxf:cxfEndpoint id="routerEndpoint" + address="http://localhost:9001/router"; + serviceClass="org.apache.servicemix.examples.cxf.HelloWorld"> + <camel-cxf:properties> + <entry key="dataFormat" value="MESSAGE"/> + </camel-cxf:properties> + </camel-cxf:cxfEndpoint> + + <camel-cxf:cxfEndpoint id="serviceEndpoint" + address="http://localhost:9000/SoapContext/SoapPort"; + serviceClass="org.apache.servicemix.examples.cxf.HelloWorld"> + </camel-cxf:cxfEndpoint> + + <camelContext xmlns="http://camel.apache.org/schema/blueprint";> + <route> + <from uri="routerEndpoint"/> + <to uri="log:request"/> + </route> + </camelContext> + +</blueprint> +------------------------------------------------------------------------------------------------------------------------------------ + +Currently the endpoint element is the first supported CXF +namespacehandler. + +You can also use the bean references just as in spring + +[source,xml] +---------------------------------------------------------------------------------------------------------------- +<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.0.0"; + xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws"; + xmlns:cxf="http://cxf.apache.org/blueprint/core"; + xmlns:camel="http://camel.apache.org/schema/blueprint"; + xmlns:camelcxf="http://camel.apache.org/schema/blueprint/cxf"; + xsi:schemaLocation=" + http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd + http://cxf.apache.org/blueprint/jaxws http://cxf.apache.org/schemas/blueprint/jaxws.xsd + http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd + "> + + <camelcxf:cxfEndpoint id="reportIncident" + address="/camel-example-cxf-blueprint/webservices/incident" + wsdlURL="META-INF/wsdl/report_incident.wsdl" + serviceClass="org.apache.camel.example.reportincident.ReportIncidentEndpoint"> + </camelcxf:cxfEndpoint> + + <bean id="reportIncidentRoutes" class="org.apache.camel.example.reportincident.ReportIncidentRoutes" /> + + <camelContext xmlns="http://camel.apache.org/schema/blueprint";> + <routeBuilder ref="reportIncidentRoutes"/> + </camelContext> + +</blueprint> +---------------------------------------------------------------------------------------------------------------- + +[[CXF-Howtomakethecamel-cxfcomponentuselog4jinsteadofjava.util.logging]] +How to make the camel-cxf component use log4j instead of java.util.logging +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CXF's default logger is `java.util.logging`. If you want to change it to +log4j, proceed as follows. Create a file, in the classpath, named +`META-INF/cxf/org.apache.cxf.logger`. This file should contain the +fully-qualified name of the class, +`org.apache.cxf.common.logging.Log4jLogger`, with no comments, on a +single line. + +[[CXF-Howtoletcamel-cxfresponsemessagewithxmlstartdocument]] +How to let camel-cxf response message with xml start document +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are using some SOAP client such as PHP, you will get this kind of +error, because CXF doesn't add the XML start document "<?xml +version="1.0" encoding="utf-8"?>" + +[source,java] +--------------------------------------------------------------------------------------- +Error:sendSms: SoapFault exception: [Client] looks like we got no XML document in [...] +--------------------------------------------------------------------------------------- + +To resolved this issue, you just need to tell StaxOutInterceptor to +write the XML start document for you. + +You can add a customer interceptor like this and configure it into you +camel-cxf endpont + +Or adding a message header for it like this if you are using *Camel +2.4*. + +[source,java] +------------------------------------------------------------------- + // set up the response context which force start document + Map<String, Object> map = new HashMap<String, Object>(); + map.put("org.apache.cxf.stax.force-start-document", Boolean.TRUE); + exchange.getOut().setHeader(Client.RESPONSE_CONTEXT, map); +------------------------------------------------------------------- + +[[CXF-HowtooverridetheCXFproduceraddressfrommessageheader]] +How to override the CXF producer address from message header +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `camel-cxf` producer supports to override the services address by +setting the message with the key of "CamelDestinationOverrideUrl". + +[source,java] +---------------------------------------------------------------------------------------------- + // set up the service address from the message header to override the setting of CXF endpoint + exchange.getIn().setHeader(Exchange.DESTINATION_OVERRIDE_URL, constant(getServiceAddress())); +---------------------------------------------------------------------------------------------- + +[[CXF-Howtoconsumeamessagefromacamel-cxfendpointinPOJOdataformat]] +How to consume a message from a camel-cxf endpoint in POJO data format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `camel-cxf` endpoint consumer POJO data format is based on the +http://cwiki.apache.org/CXF20DOC/invokers.html[cxf invoker], so the +message header has a property with the name of +`CxfConstants.OPERATION_NAME` and the message body is a list of the SEI +method parameters. + +[[CXF-Howtopreparethemessageforthecamel-cxfendpointinPOJOdataformat]] +How to prepare the message for the camel-cxf endpoint in POJO data format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `camel-cxf` endpoint producer is based on the +https://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/endpoint/Client.java[cxf +client API]. First you need to specify the operation name in the message +header, then add the method parameters to a list, and initialize the +message with this parameter list. The response message's body is a +messageContentsList, you can get the result from that list. + +If you don't specify the operation name in the message header, +`CxfProducer` will try to use the `defaultOperationName `from +`CxfEndpoint`, if there is no `defaultOperationName` set on +`CxfEndpoint`, it will pickup the first operationName from the Operation +list. + +If you want to get the object array from the message body, you can get +the body using `message.getbody(Object[].class)`, as follows: + +[[CXF-Howtodealwiththemessageforacamel-cxfendpointinPAYLOADdataformat]] +How to deal with the message for a camel-cxf endpoint in PAYLOAD data format +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`PAYLOAD` means that you process the payload message from the SOAP +envelope. You can use the `Header.HEADER_LIST` as the key to set or get +the SOAP headers and use the `List<Element>` to set or get SOAP body +elements. + `Message.getBody()` will return an +`org.apache.camel.component.cxf.CxfPayload` object, which has getters +for SOAP message headers and Body elements. This change enables +decoupling the native CXF message from the Camel message. + +[[CXF-HowtogetandsetSOAPheadersinPOJOmode]] +How to get and set SOAP headers in POJO mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`POJO` means that the data format is a "list of Java objects" when the +Camel-cxf endpoint produces or consumes Camel exchanges. Even though +Camel expose message body as POJOs in this mode, Camel-cxf still +provides access to read and write SOAP headers. However, since CXF +interceptors remove in-band SOAP headers from Header list after they +have been processed, only out-of-band SOAP headers are available to +Camel-cxf in POJO mode. + +The following example illustrate how to get/set SOAP headers. Suppose we +have a route that forwards from one Camel-cxf endpoint to another. That +is, SOAP Client -> Camel -> CXF service. We can attach two processors to +obtain/insert SOAP headers at (1) before request goes out to the CXF +service and (2) before response comes back to the SOAP Client. Processor +(1) and (2) in this example are InsertRequestOutHeaderProcessor and +InsertResponseOutHeaderProcessor. Our route looks like this: + +SOAP headers are propagated to and from Camel Message headers. The Camel +message header name is "org.apache.cxf.headers.Header.list" which is a +constant defined in CXF (org.apache.cxf.headers.Header.HEADER_LIST). The +header value is a List of CXF SoapHeader objects +(org.apache.cxf.binding.soap.SoapHeader). The following snippet is the +InsertResponseOutHeaderProcessor (that insert a new SOAP header in the +response message). The way to access SOAP headers in both +InsertResponseOutHeaderProcessor and InsertRequestOutHeaderProcessor are +actually the same. The only difference between the two processors is +setting the direction of the inserted SOAP header. + +[[CXF-HowtogetandsetSOAPheadersinPAYLOADmode]] +How to get and set SOAP headers in PAYLOAD mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We've already shown how to access SOAP message (CxfPayload object) in +PAYLOAD mode (See "How to deal with the message for a camel-cxf endpoint +in PAYLOAD data format"). + +Once you obtain a CxfPayload object, you can invoke the +CxfPayload.getHeaders() method that returns a List of DOM Elements (SOAP +headers). + +Since Camel 2.16.0, you can also use the same way as described in +sub-chapter "How to get and set SOAP headers in POJO mode" to set or get +the SOAP headers. So, you can use now the +header "org.apache.cxf.headers.Header.list" to get and set a list of +SOAP headers.This does also mean that if you have a route that forwards +from one Camel-cxf endpoint to another (SOAP Client -> Camel -> CXF +service), now also the SOAP headers sent by the SOAP client are +forwarded to the CXF service. If you do not want that these headers are +forwarded you have to remove them in the Camel header +"org.apache.cxf.headers.Header.list". + +[[CXF-SOAPheadersarenotavailableinMESSAGEmode]] +SOAP headers are not available in MESSAGE mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SOAP headers are not available in MESSAGE mode as SOAP processing is +skipped. + +[[CXF-HowtothrowaSOAPFaultfromCamel]] +How to throw a SOAP Fault from Camel +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are using a `camel-cxf` endpoint to consume the SOAP request, you +may need to throw the SOAP Fault from the camel context. + + Basically, you can use the `throwFault` DSL to do that; it works for +`POJO`, `PAYLOAD` and `MESSAGE` data format. + + You can define the soap fault like this + +Then throw it as you like + +If your CXF endpoint is working in the `MESSAGE` data format, you could +set the the SOAP Fault message in the message body and set the response +code in the message header. + +Same for using POJO data format. You can set the SOAPFault on the out +body and also indicate it's a fault by calling Message.setFault(true): + +[[CXF-Howtopropagateacamel-cxfendpointrequestandresponsecontext]] +How to propagate a camel-cxf endpoint's request and response context +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +https://svn.apache.org/repos/asf/cxf/trunk/api/src/main/java/org/apache/cxf/endpoint/Client.java[cxf +client API] provides a way to invoke the operation with request and +response context. If you are using a `camel-cxf` endpoint producer to +invoke the outside web service, you can set the request context and get +response context with the following code: + +[source,java] +------------------------------------------------------------------------------------------------------------- + CxfExchange exchange = (CxfExchange)template.send(getJaxwsEndpointUri(), new Processor() { + public void process(final Exchange exchange) { + final List<String> params = new ArrayList<String>(); + params.add(TEST_MESSAGE); + // Set the request context to the inMessage + Map<String, Object> requestContext = new HashMap<String, Object>(); + requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY, JAXWS_SERVER_ADDRESS); + exchange.getIn().setBody(params); + exchange.getIn().setHeader(Client.REQUEST_CONTEXT , requestContext); + exchange.getIn().setHeader(CxfConstants.OPERATION_NAME, GREET_ME_OPERATION); + } + }); + org.apache.camel.Message out = exchange.getOut(); + // The output is an object array, the first element of the array is the return value + Object\[\] output = out.getBody(Object\[\].class); + LOG.info("Received output text: " + output\[0\]); + // Get the response context form outMessage + Map<String, Object> responseContext = CastUtils.cast((Map)out.getHeader(Client.RESPONSE_CONTEXT)); + assertNotNull(responseContext); + assertEquals("Get the wrong wsdl opertion name", "{http://apache.org/hello_world_soap_http}greetMe";, + responseContext.get("javax.xml.ws.wsdl.operation").toString()); +------------------------------------------------------------------------------------------------------------- + +[[CXF-AttachmentSupport]] +Attachment Support +^^^^^^^^^^^^^^^^^^ + +*POJO Mode:* Both SOAP with Attachment and MTOM are supported (see +example in Payload Mode for enabling MTOM). However, SOAP with +Attachment is not tested. Since attachments are marshalled and +unmarshalled into POJOs, users typically do not need to deal with the +attachment themself. Attachments are propagated to Camel message's +attachments if the MTOM is not enabled, since 2.12.3. So, it is +possible to retreive attachments by Camel Message API + +[source,java] +-------------------------------------------- +DataHandler Message.getAttachment(String id) +-------------------------------------------- + +*Payload Mode:* MTOM is supported since 2.1. Attachments can be +retrieved by Camel Message APIs mentioned above. SOAP with Attachment +(SwA) is supported and attachments can be retrieved since 2.5. SwA is +the default (same as setting the CXF endpoint property "mtom-enabled" to +false). + +To enable MTOM, set the CXF endpoint property "mtom-enabled" to _true_. +(I believe you can only do it with Spring.) + +You can produce a Camel message with attachment to send to a CXF +endpoint in Payload mode. + +You can also consume a Camel message received from a CXF endpoint in +Payload mode. + +*Message Mode:* Attachments are not supported as it does not process the +message at all. + +*CXF_MESSAGE Mode*: MTOM is supported, and Attachments can be retrieved +by Camel Message APIs mentioned above. Note that when receiving a +multipart (i.e. MTOM) message the default SOAPMessage to String +converter will provide the complete multipart payload on the body. If +you require just the SOAP XML as a String, you can set the message body +with message.getSOAPPart(), and Camel convert can do the rest of work +for you. + +[[CXF-StreamingSupportinPAYLOADmode]] +Streaming Support in PAYLOAD mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In 2.8.2, the camel-cxf component now supports streaming of incoming +messages when using PAYLOAD mode. Previously, the incoming messages +would have been completely DOM parsed. For large messages, this is time +consuming and uses a significant amount of memory. Starting in 2.8.2, +the incoming messages can remain as a javax.xml.transform.Source while +being routed and, if nothing modifies the payload, can then be directly +streamed out to the target destination. For common "simple proxy" use +cases (example: from("cxf:...").to("cxf:...")), this can provide very +significant performance increases as well as significantly lowered +memory requirements. + +However, there are cases where streaming may not be appropriate or +desired. Due to the streaming nature, invalid incoming XML may not be +caught until later in the processing chain. Also, certain actions may +require the message to be DOM parsed anyway (like WS-Security or message +tracing and such) in which case the advantages of the streaming is +limited. At this point, there are two ways to control the streaming: + +* Endpoint property: you can add "allowStreaming=false" as an endpoint +property to turn the streaming on/off. + +* Component property: the CxfComponent object also has an allowStreaming +property that can set the default for endpoints created from that +component. + +Global system property: you can add a system property of +"org.apache.camel.component.cxf.streaming" to "false" to turn if off. +That sets the global default, but setting the endpoint property above +will override this value for that endpoint. + +[[CXF-UsingthegenericCXFDispatchmode]] +Using the generic CXF Dispatch mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +From 2.8.0, the camel-cxf component supports the generic +https://cxf.apache.org/docs/jax-ws-dispatch-api.html[CXF dispatch +mode] that can transport messages of arbitrary structures (i.e., not +bound to a specific XML schema). To use this mode, you simply omit +specifying the wsdlURL and serviceClass attributes of the CXF endpoint. + +[source,xml] +------------------------------------------------------------------------------------------- +<cxf:cxfEndpoint id="testEndpoint" address="http://localhost:9000/SoapContext/SoapAnyPort";> + <cxf:properties> + <entry key="dataFormat" value="PAYLOAD"/> + </cxf:properties> + </cxf:cxfEndpoint> +------------------------------------------------------------------------------------------- + +It is noted that the default CXF dispatch client does not send a +specific SOAPAction header. Therefore, when the target service requires +a specific SOAPAction value, it is supplied in the Camel header using +the key SOAPAction (case-insensitive). + + + +[[CXF-SeeAlso]] +See Also +^^^^^^^^ + +* link:configuring-camel.html[Configuring Camel] +* link:component.html[Component] +* link:endpoint.html[Endpoint] +* link:getting-started.html[Getting Started] + http://git-wip-us.apache.org/repos/asf/camel/blob/f6d04c8d/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 95b8866..73a8792 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -116,6 +116,7 @@ * [Crypto](crypto.adoc) * [Crypto Digital Signatures](crypto-digital-signatures.adoc) * [CSV](csv.adoc) + * [CXF](cxf.adoc) * [Disruptor](disruptor.adoc) * [DNS](dns.adoc) * [Docker](docker.adoc)
