Apache Axis2 - Client API

Client API

Nowadays, asynchronous or non-blocking Web Service invocation is a key requirement in Web Services. There are currently two approaches to invoking a Web Service in a non-blocking manner. The first is the client programming model, where a client invokes the service in a non-blocking manner.

The second way is the transport level non-blocking invocation where invocation occurs in two transports (it could either be two single-channel transports like SMTP, or two double-channel transports like HTTP). Axis2 client API supports both the non-blocking invocation scenarios.

Axis2 introduces a very convenient client API for invoking services that consists of two classes called "ServiceClient" and "OperationClient". The ServiceClient API is intended for regular usage when you just require to send and receive XML. On the other hand, the operation client is meant for advanced usage, when there is a need to work with SOAP headers and some other advanced tasks. With ServiceClient, we can only access the SOAP body or the payload. Although we can add SOAP headers, we do not have any way to retrieve the SOAP header by using the ServiceClient. We need to use an OperationClient for such a function.

ServiceClient has the following API for invoking a service:

• sendRobust: The whole idea of this is to just send an XML request to the Web Service and not care about its response. However, if something goes wrong, we require to know that too, so this API invokes a service, where it does not have a return value but would throw an exception.
  .
• FireAndForget: This API is for just sending an XML request and not caring about either the response, or any exception. Hence, this is useful in invoking an in-only MEP.
  .
• SendReceive: This invokes a service that has a return value. This is one of the most commonly used APIs. Hence, this is used for invoking an in-out MEP.
  .
• SendReceiveNonBlocking: This invokes a service in a non-blocking manner. This method can be used when the service has a return value. In order to use this method, we have to pass a callback object, which is called once the invocation is complete.

As mentioned earlier, the OperationClient class is for advanced users, and working with OperationClient requires us to know Axis2 in depth. In ServiceClient, we do not have to know anything about SOAP envelope, message context, and so on. But when it comes to OperationClient, the users have to create these by themselves, before invoking a service. Creating and invoking a service using OperationClient involves the following steps:

• Create a ServiceClient.
• Then create OperationClient with the use of the ServiceClient that we have created.
• Create SOAP envelop.
• Create Message context.
• Add the SOAP envelope to message context.
• Add the messagecontext to OperationClient.
• Then invoke the OperationClient.
• If there is a response, then get the response message context from the OperationClient.