Axis2 Client API Concepts
The Axis2 client API handles In-Only and In-Out MEPs with all
messaging combinations discussed in the last section. The space of
the MEPs are unlimited; as a result, Axis2 is compelled to provide
a core that can support any message exchange pattern, but provides
API support only for the two most widely used patterns: In-Only and
In-Out. There are two ways to implement more complex patterns:
combine In-Out and In-Only patterns to achieve the desired pattern,
or write a new implementation for the desired pattern. As Axis2
provides support for any MEP in the core level, implementing either
is fairly straightforward. The In-Only and In-Out MEPs are
supported with the two classes
InOutMEPClient, described in the next two
In-Only MEP Support:
InOnlyMEPClient class provides support for
fire-and-forget messaging, and treats all transport types as
one-way transports. The real difference between
that the addressing parameters are not locked in the former, and
addressing parameters are controlled by Axis2 in the latter. As the
addressing parameters can be controlled, the
InOnlyMEPClient can be used as the messaging API, and
used as the building block to build more complex message
interactions on top of it.
In-Out MEP Support:
InOutMEPClient and the
Call class that
InOutMEPClient provide the API for
request-response messaging. Axis2 takes care of the complete
operation, and all of the addressing properties except the
To address are under the control of the Axis2.
Users can configure
InOutMEPClient to behave
differently using the following four parameters:
- Sender transport
- Listener transport
- Use separate listener
- Use blocking
The client API currently provides support for HTTP and SMTP transports. The following matrix shows the possible combinations for these parameters and how they combine to provide different effects.
|Messaging interaction||Sender transport||Listener transport||Use separate Listener||Blocking|
The following code samples show how to do several well-defined interactions with Apache Axis2. The user may configure Axis2 to switch between different interactions by simply switching the properties in the client API. The client API of Axis2 supports only XML-level messaging, and OMElement represents a chunk of XML.
Invoking One-Way Messaging
The one-way MEP is simple in that there is exactly one way it can behave, as there is only one message that goes back and forth. The messages are treated asynchronously and the transport is one-way.
There are four ways a request-response message can behave:
- In-Out synchronous with two-way transport
- In-Out asynchronous with two-way transport
- In-Out synchronous with one-way transport
- In-Out asynchronous with one-way transport
The following code samples show how these cases can be addressed with Axis2. Pay attention to how the four properties of the client API are used.
- In-Out synchronous, HTTP as two-way transports
OMElement payload = .... Call call = new Call(); call.setTo( new EndpointReference(AddressingConstants.WSA_TO, "HTTP://...)); call.setTransportInfo(Constants.TRANSPORT_HTTP, Constants.TRANSPORT_HTTP, false); OMElement result = (OMElement) call.invokeBlocking( operationName.getLocalPart(), payload);
Here, the SOAP messages travel through the same HTTP connection. The addressing properties are not specified, so they will be defaulted to
Anonymousat the server side. The client API will block until the response message arrives.