[CONF] Apache CXF > Custom CXF Transport

[confluence]

Custom CXF Transport Page edited by Andrei Shakirin Changes (1) h1. Implementation of Custom CXF Transport This page tries to summarize experience of implementing new CXF transport. ... Full Content This page tries to summarize experience of implementing new CXF transport. Use Cases Normally implementation of custom transport is required to provide new physical protocol not yet supported by CXF(for instance udp, ftp). New CXF transport can be also a solution to support legacy ESB participants that have to be interoperable with JAX-WS services and clients. Actually CXF 2.3.x distribution provides transport implementation for following protocols: HTTP(S), JBI, JMS and Local(inside one JVM). Camel additionally implements CXF transport for camel exchanges. Architecture and Design The transport functionality is based on two fundamental definitions: Conduit and Destination. Conduit is responsible to send a message to recipient and Destination – to receive a message from the sender. In order to send a response, Destination needs own back-channel Conduit (in case of request-response communication). Conduit and Destination are created by TransportFactory. CXF selects a correct TransportFactory based on transport URL. SOAP is also considered as high level transport and has own Conduit and Destination in CXF. To send message into physical channel Conduit should access the message context. Normal practice in this case is own implementation of OutputStream extending CachedOutputStream. The custom stream will be set to message and provides a possibility to access context in streaming or buffered way depending on transport requirements and to send message to physical channel. CachedOutputStream is configured to keep message in memory only up to limited size. If size is exceeded, message is swapped to disk. Class diagram of TransportFactory, Conduit, Destination and OutputStream is shown bellow: CXF Transport class diagram How it Works Interaction between JAX-WS client and service using CXF transport is represented on following figure: CXF Transport intercations Simplified Client Workflow: Step1: JAX-WS client invokes a service for example in this way: URL wsdlURL = this.getClass().getResource("/HelloWorld.wsdl"); HelloWorldService service = new HelloWorldService(wsdlURL, SERVICE_NAME); HelloWorld hw = service.getHelloWorldPort(); String result = hw.sayHi(TEST_REQUEST); }} Step2: CXF runtime select correct TransportFactory based on some criteria (described bellow) Step3: CXF runtime calls TransportFactory.getConduit() method to obtain Conduit Step4: CXF runtime invokes Conduit.prepare() and passes outgoing message as argument Step5: Conduit sets own OutputStream (normally extended CachedOutputStream) as outgoing message content Step6: CXF runtime processes outgoing message, calls interceptors chain and invokes Conduit.close(Message) method is invoked for outgoing message. Step7: Finally, OutputStream.doClose() method for outgoing message is invoked Step8: In doClose() method OutputStream class has access to marshalled outgoing message and exchange and will send this message through network to service using corresponded transport protocol Step9: In case of one-way communication exchange will be closed. Go to step 14 Step10: In case of request-response communication Conduit waits for service response in synchronies or asynchronies manner Step11: When response is received, Conduit creates a new Message, set it’s context and puts it as In-Message in exchange as incoming message Step12: When fault is received, Conduit creates a new Message, sets it’s context and puts it as fault message in exchange as in-fault message Step13: Conduit notifies incomingObesrver about response using incomingObserver.onMessage() call Step14: Conduit.close(Message) method is invoked for incoming message. Normally Conduit implementation decreases the reference or closes network connection with the service. Step15: JAX-WS client code receives response in sync or async style Simplified Service Workflow: Step1: JAX-WS service is registered for example in this way: HelloWorldImpl serverImpl = new HelloWorldImpl(); Endpoint.publish("udp://localhost:9000/hello", serverImpl); Step2: CXF runtime selects correct TransportFactory based on some criteria (described bellow) Step3: CXF runtime calls TransportFactory.getDestination() method to obtain Destination Step4: As far as service is registered Destination will be activated using Destination.activate() method Step5: Destination.activate() opens network transport connections and listen incoming requests Step6: When request comes, Destination creates message, sets content and notifies message observer getMessageObserver.onMessage(). Normally incoming connection is saved in correlation map to be extracted for appropriate response. Step7: Service Implementation will be called with request message. In case of one-way communication it is end of exchange. In case of request-response business implementation returns response or throws fault exception. Step8: CXF Runtime requests back-channel conduit from destination via Destination.getInbuiltBackChannel() Step9: Back-channel conduit prepare() will be called with response message as argument Step10: Back-channel conduit sets own OutputStream as message context Step11: CXF runtime processes response message, calls interceptors chain and invokes Conduit.close(Message) method is invoked for response message. Step12. Finally OutputStream.doClose() method for response message is invoked Step13: In doClose() method OutputStream class has access to marshalled response message and exchange and will send this message through the network as response to. Appropriate incoming connection to send response normally is extracted from correlation map. Registration of Transport Factory There are two ways to register transport factory: programmatic and via spring configuration. To register transport factory programmatically it is necessary to execute following code: Bus bus = BusFactory.getThreadDefaultBus(); DestinationFactoryManagerImpl dfm = bus.getExtension(DestinationFactoryManagerImpl.class); CustomTransportFactory customTransport = new CustomTransportFactory(); dfm.registerDestinationFactory("http://cxf.apache.org/transports/TRANSPORT_PREFIX", customTransport); dfm.registerDestinationFactory("http://cxf.apache.org/transports/ TRANSPORT_PREFIX/configuration", customTransport); ConduitInitiatorManager extension = bus.getExtension(ConduitInitiatorManager.class); extension.registerConduitInitiator("http://cxf.apache.org/transports/ TRANSPORT_PREFIX", sbbTransport); extension.registerConduitInitiator("http://cxf.apache.org/transports/ TRANSPORT_PREFIX/configuration", customTransport); Where TRANSPORT_PREFIX is protocol of new transport (http, https, jms, udp). Alternatively it is also possible to register transport factory using spring configuration: <bean class="org.company.cxf.transport.CustomTransportFactory" lazy-init="false"> <property name="transportIds"> <list> <value>http http://cxf.apache.org/transports/ TRANSPORT_PREFIX</value> <value>http://cxf.apache.org/transports/ TRANSPORT_PREFIX/configuration</value> </list> </property> </bean> To define new transport endpoint in WSDL document it is necessary: a) Set soap:binding transport attribute to transport URL value (http://cxf.apache.org/transports/TRANSPORT_PREFIX) b) Port address element should be bound to namespace equals to transport URL in WSDL XML Sample: <wsdl:definitions xmlns:transport="http://cxf.apache.org/transports/TRANSPORT_PREFIX" …> … … <wsdl:binding name="GreeterPortBinding" type="tns: GreeterPortType"> <soap:binding style="document" transport=" http://cxf.apache.org/transports/TRANSPORT_PREFIX"/> … <wsdl:service name="GreeterService"> <wsdl:port binding="tns:GreeterPortBinding" name="GreeterPort"> <transport:address … Conduit and Destination Lifecycle Conduit and Destination lifecycle is requested from TransportFactory by every client or service creation. TransportFactory can either create Conduit and Destination for each request or cache them based on service endpoint information Concurrency Aspects Conduit and Destination objects can by concurrently accessed by multiple threads. Implementations should care about concurrent correlations maps and/or synchronization primitives. References CXF transport implementations: package org.apache.cxf.transport.* CXF Local Transport: http://cxf.apache.org/docs/local-transport.html Change Notification Preferences View Online | View Changes | Add Comment