Skip to main content

Tubes in JAX-WS 2.1

Posted by jitu on February 2, 2007 at 10:41 AM PST


Few months back,   href="">Kohsuke
mentioned about href="">Tubes
in his blog href="">JAX-WS
RI goes truly asynchronous!
That time, it was working only in prototypes. Now JAX-WS 2.1 runtimes
completely works on Tubes. The javadoc for Tube says, "Tube is a basic
processing unit that represents SOAP-level protocol handling code.
Multiple tubes are often put together in a line, and act on href="">Packets
in a sequential fashion". We converted all the JAX-WS processing units
Tubes(for e.g: mustunderstand processing is done in href="">MUTube,
of web sevice endpoints is done in href="">InvokerTube
etc). Most developers need not worry about creating Tubes but an
advanced user or a middleware developer may care to do so. This is also
a good alternative to writing Handlers while retaining the performance.
But this approach is not portable as you would be using classes.

Advantages of Tubes

There are quite a few advantages in writing your own Tube for SOAP

  • Tubes work on href="">Message
    abstraction and has the efficient access to the payload. On the other
    hand, SOAP handlers wouldn't perform that well since they operate on
  • No thread need to be blocked any time and this result in
    high scalability. Asynchronous
    transport tubes can take full advantage of this aspect and scale better
    for asynchronous web service invocations(for e.g.
  • href="">AsyncProvider
    endpoints scale well with asynchronous transports.
  • Request and response processing is decoupled and that means
    they could potentially be run by different threads.

Sample Tube to add SOAP headers

OK, say you need to add a custom header to all the SOAP response
messages. To do this :

  1. Write a href="">Tube
    that adds custom header to response messages.
  2. Write a href="">TubelineAssembler
    to include and postion the custom Tube in the tubeline.
  3. Write a href="">TubelineAssemblerFactory
    that creates these TubelineAssembler instances.

Writing a href="">Tube

Usually, a href="">Tube
implementation would extend from
since there will be a next Tube in the processing tubeline. If your
Tube is the last one in the processing
tube line, it would extend from href="">AbstractTubeImpl.
Extending from these
base classes is better as they provide good implementations for many
methods. The javadocs provide complete information on all these things.

public class CustomTube extends AbstractFilterTubeImpl {

    protected CustomTube(Tube next) {

    protected CustomTube(AbstractFilterTubeImpl that, TubeCloner cloner) {
        super(that, cloner);

    public CustomTube copy(TubeCloner cloner) {
        return new CustomTube(this, cloner);

    public NextAction processResponse(Packet packet) {
        Message message = packet.getMessage();
        if (message == null) {          // oneway
            return super.processResponse(packet);
        HeaderList headers = message.getHeaders();
        QName adQName = new QName("test", "test");
        headers.add(Headers.create(adQName, "Advertisement"));
        return super.processResponse(packet);


In the above CustomTube code

  • In the processResponse(), it gets the href="">Message
    from href="">Packet
    and adds a href="">Header
  • Need
    to implement the correct copy() method. Eventhough, our Tube doesn't
    have any state, it needs to give a new instance since "next" tube may
    not be stateless. When the tubeline is copied, the copied instance is
    an independent tubeline without any shared tube instances among the
    tubelines. Also in the copy constructor, copy other instance data.
  • Need
    to return correct href="">NextAction
    for processRequest() and processResponse()
    methods. The NextAction determines whether to proceed with the next
    Tube or processing needs to change direction etc. Use the base class href="">AbstractTubeImpl's
    methods to create different href="">NextAction

Writing a href="">TubelineAssembler

To place our CustomTube in the tubeline, we need to write a href="">TubelineAssembler.
I pretty much copied from default assembler and added our tube in
server's tubeline. This needs to be improved in our runtime so that
tubeline assembly is simple and easy.

public class CustomTubeAssembler implements TubelineAssembler {   
    public Tube createClient(ClientTubeAssemblerContext context) {
        Tube head = context.createTransportTube();
        head = context.createSecurityTube(head);
        head = context.createWsaTube(head);
        head = context.createClientMUTube(head);
        return context.createHandlerTube(head);

    public Tube createServer(ServerTubeAssemblerContext context) {
        Tube head = context.getTerminalTube();
        head = new CustomTube(head);         // Add our custom tube
        head = context.createHandlerTube(head);
        head = context.createMonitoringTube(head);
        head = context.createServerMUTube(head);
        head = context.createWsaTube(head);
        head = context.createSecurityTube(head);
        return head;

Writing a href="">TubelineAssemblerFactory

Next, we need to create href="">TubelineAssemblerFactory
that knows how to create href="">TubelineAssemblers.

public class CustomTubelineAssemblerFactory extends TubelineAssemblerFactory {
    public TubelineAssembler doCreate(BindingID bindingID) {
        return new CustomTubeAssembler();

JAX-WS runtime discovers TubelineAssemblerFactory
using service
finder mechanism. It looks for
META-INF/services/ and
loads the factory entry in that file. So we add
com.jitu.CustomTubelineAssemblerFactory in the
file META-INF/services/

CustomTube in action

Let us create a jar customtube.jar with all the above classes and
META-INF/services entry. The entries would look like:


If you put this jar in the classpath of the container, you would see
there is an additional header in every SOAP response message

<S:Header><test xmlns="test">Advertisement</test> ...</S:Header>

You can download the href="">source
zip of the above code. In future, we will come up with an
easier way to plug-in a Tube.

Related Topics >>


Tubes in JAX-WS 2.1

Hi Jitendra Kotamraju:
As you can modify or acess the body messages in processRequest? How is possible?