Skip to end of metadata
Go to start of metadata

Overview of APIs

Generally many of the various frameworks share the same principles.

Description

Axis2

Celtix

ServiceMix/JBI

Tuscany

XFire

A representation of the message

MessageContext

JAX WS MessageContext

NormalizedMessage

Message

InMessage/OutMessage

Allowable representations of mmessage

AXIOM

Stream, Object, Source, SAAJ

Source

Object

Stream (sometimes), StAX streams, Objects

A representation of the message exchange pattern

OperationContext

Exchange

MessageExchange

Transport API for sending/receiving messages

TransportSender, TransportListener

ClientTransport, ServerTransport

DeliveryChannel

MessageChannel (kind of?)

Transport + Channel

A interceptor chain to manipulate messages

Handlers & Phases

Stream, Logical, and Protocol Handlers

MessageHandler, Interceptor

Handlers & Phases

Session Handling

SessionContext

?

Session

  • A way to deal with synchronous and asynchronous transports

Axis2

Javadocs

Transports and Messages
Transports will create a MessageContext with an AXIOM soap envelope then send it off to the AxisEngine. Messages go through the processing pipeline. Messages are sent out via a TransportSender class which extends the Handler class. To send the message the invoke method is called with the appropriate MessageContext.

The correlation to a MessageExchange in JBI would be the OperationContext in Axis 2. The OperationContext holds references to the various MessageContexts involved in the message exchange pattern.

Handlers
Additionally there are ServiceContext and SessionContext classes.

For the interceptor chain, Axis2 has the concept of Handlers, Phases and flows. There are multiple flows - in, out, and fault. Fore each flow there are many different phases. Handlers can associate themselves with a phase and they can specify that they want to run before/after specific handlers within the phase.

Pros:

  • Well layered approach with the Contexts
  • Good seperation of the Messages & exchange pattern
  • Flexible way to order handlers

Cons:

  • The biggest con is that everything has to be an AXIOM object, making byte or object or straight up stream manipulation hard.
  • Transport API is kind of vague
  • MessageContext seems to have a lot of methods on it:
    • It maintains state for the flow which I personally (Dan) don't like
    • It holds a property letting you know whether it is a REST invocation or not. This seems like it should be at the Transport level.

Celtix

Javadocs

Handlers
Celtix has several different types of MessageContexts which extend the JAX-WS MessageContext: InputStreamMessageContext, OutputStreamMessageContext, ObjectMessageContext, GenericMessageContext. Celtix reuses the JAX-WS handler concept and recognizes several different kind of handlers: protocol, logical, and stream handlers. Stream handlers can work with the Input/Output streams. LogicalHandlers work with the payload in Source form. And ProtocolHandlers can work with SAAJ SOAPMessages.

Transport API
Celtix has several different classes associated with the transport layer:

  • ClientTransport: An api to send and receive back Messages from a Client. This is a one shot interface created for a specific MEP. Provides invoke, invokeOneWay, and invokeAsync operations. They take OutputStreamMessageContexts and return (most of the time) InputStreamMessageContexts.
  • ServerTransport: Activates/deactivates the server transport. Also provides the ability to "rebase" messages - allowing you to do things like piggy back a WS-RM sequence acknowledgement on a one way request.
  • ServerTransportCallback: When a ServerTransport is activated a ServerTransportCallback is provided. This gets called whenever there is a new message on that transport.
  • TransportFactory: Creates a Server/ClientTransport for a particular EPR

Celtix really reuses the concept of WS-Addressing endpoint references within its API. Whenever you create a transport you must supply an EPR. This will then set up your ReplyTo/FaultTo streams automatically.

Pros:

  • Unlike most of the other APIs its pretty straightforward to have a messageContext that has a payload of an object that isn't XML
  • There is a straightforward way to work with the underlying byte streams
  • Has the ability to "rebase"
  • Creates transports with EndpointReferences, setting up the ReplyTo/FaultTo automagically

Cons:

  • Handlers phases are hard coded and executed in serial. This makes it impossible to do things like write bytes, write xml, then write bytes again. Or to really do streaming xml type things.
  • Only one representation of the message is valid at a time - streams, then source, then saaj.
  • There is no concept of a MessageExchange
  • The Transport API has different Client and Server classes

ServiceMix/JBI

JBI Javadocs
ServiceMix Javadocs

Central to JBI is the concept of a NormalizedMessage. The NormalizedMessage holds a reference to the message as a Source object.

  • DeliveryChannel
  • MessageExchange, InOut, In, etc

Pros:

  • NormalizedMessage and MessageExchange patterns are very clean
  • Has an attachment API (although not quite sufficient to use with a SOAP stack, needs a few more details)

Cons:

  • No interceptor API
  • No way to deal with POJOs & other types of data, like CSV text

Tuscany

Tuscany's Message class holds a simple object containing the Body of the message. It also provides a callback channel for synchronous/correlated responses.

TODO: what is getRelatedCallbackMessage for? It seems like maybe its for a correlated response.

The MessageChannel class is as close to defining a Transport API as Tuscany comes currently. It does however, define some interception patterns:

TODO: fill in more details on how these classes are used!

Pros:

  • Simple
  • Message interface which can hold anything

Cons:
(warning: I am not a tuscany expert - DD)

  • Handlers seems to assume request/response? What about other MEPs?
  • Why two different interceptors - MessageHandler and Interceptor?

XFire

Javadocs

The XFire model focuses on the idea of Transports and Channels. Channels provide a means of communication on a Transport. When a request comes in, a Channel is opened and a message is sent to the ChannelReceiver. This starts an invocation flow within XFire sending a message down the in pipeline.

Typically transports will want to handle soap messages. To do there is typicall a raw transport class, like HttpTransport, and a Soap transport class which extends it - like SoapHttpTransport. A soap transport will then register additional handlers to parse the soap message, set the soap version, etc.

Messages in XFire are represented by the InMessage and OutMessage classes. The InMessage has an XMLStreamReader associated with it. The OutMessage takes a MessageSerializer which is a callback to write the message to an XMLStreamWriter at the appropriate time. The InMessage/OutMessage API is mostly focused around StAX, but can be used to hold objects as well in its Body property.

There is also the concept of a MessageExchange in XFire. These holds references to the various messages in the MessageExchange pattern. It also holds a reference to an OperationInfo instance which contains the metadata about the operation being invoked. This class correlates highly with the WSDL operation concept.

Handlers are XFire's way to Intercept messages. They provide an invoke method which takes a MessageContext. Handlers can be registered in the in, out, and fault flows of a service & client. Within each flow there are a number of phases a Handler can participate in.

Pros:

  • Allows very efficient use of xml, parsing can occur in any phase at any time, its up to which ever handlers you want to use.
  • Allows you to manipulate streams as well as work with StAX
  • Clean way to handle soap transports
  • Provides an Attachment API

Cons:

  • API for working with streams & objects is not as clean as it could be
  • Message classes have SOAP specific information on them, like the SOAP version and headers
  • Phase API could be a bit cleaner
  • No labels