1. Apache Axis2
XML Based Client API

2. Agenda What is XML based client API? Introducing ServiceClient
Available invocation patterns
Configuring client using options
Working with Dynamic clients
Creating OperationClient
RPCServiceClient API
Exercises

3. What is XML Based Client API?
Service
WSDL
Stub
Client using XML
Based Client API
Client using Stub

4. Why? Sometimes, it's just the preference! But in some other cases,
Fine-grained manipulation of services/clients
Synchronous/asynchronous service invocations
Dynamic creation of clients

5. ServiceClient
Supports both blocking and non-blocking invocations models
Asynchronous case has Callbacks
Can handle transport dependent asynchrony as well.

6. Invocation patterns sendRobust fireAndForget sendReceive
sendReceiveNonBlocking

7. Typical ServiceClient usage
ServiceClient sc = new ServiceClient();
sc.setTargetEPR(targetEPR);
sc.setOptions(options);
OMElement requestBody = …;
OMElement responseBody = sc.sendReceive(requestBody);

8. What are Options ? Addressing information SOAP action (wsa:action)‏
Transport data
Properties

9. There's Nothing Like Code to Explain it !
//creating service client
ServiceClient sc = new ServiceClient();
//creating option
Options opts = new Options();
// setting target EPR
opts.setTo(new EndpointReference("
//setting action
opts.setAction("urn:echo");
sc.setOptions(opts);
//invoke service
sc.sendReceive(element);

10. Options Options options = new Options()‏ // which version of SOAP
options.setSoapVersionURI("
// also set other WS-A MAPs – replyTo, To
options.setFrom(fromEPR);
// create your own messageID instead of default
options.setMessageId("uuid:42");
// for blocking case
options.setTimeOutInMilliSeconds(1000);
// sets up an HTTP listener for the response
options.setUseSeparateListener(true);
// other properties
options.setProperty(name, value);

11. Properties LOTS and LOTS A full list is available here:
Another interesting document:

12. Properties MessageContextConstants.TRANSPORT_URL
Configuration.ENABLE_MTOM
options.setTo("
options.setProperty(
MessageContextConstants.TRANSPORT_URL, "

13. WS-Addressing Properties
AddressingConstants.WS_ADDRESSING_VERSION
AddressingConstants.Final.WSA_NAMESPACE
AddressingConstants.Submission.WSA_NAMESPACE
AddressingConstants.REPLACE_ADDRESSING_HEADERS
Use already set addressing headers or have Axis2 set them
AddressingConstants.DISABLE_ADDRESSING_FOR_OUT_MESSAGES
To skip WS-A on outgoing messages (for example to an old pre-WSA server)‏

14. HTTP properties HTTPConstants.* CHUNKED NTLM_AUTHENTICATION
Instance of HttpTransportProperties.NTLMAuthenticati on
PROXY
Instance of HttpTransportProperties.ProxyProperties
BASIC_AUTHENTICATION
HttpTransportProperties.BasicAuthenticati on
SO_TIMEOUT
Socket Timeout as an Integer
CONNECTION_TIMEOUT
Plus others…

15. REST Properties Configuration.ENABLE_REST True/False
Configuration.HTTP_METHOD_POST – default
Configuration.CONTENT_TYPE
HTTPConstants.MEDIA_TYPE_APPLICATION_X ML
HTTPConstants.MEDIA_TYPE_X_WWW_FORM
HTTPConstants.MEDIA_TYPE_TEXT_XML
HTTPConstants.MEDIA_TYPE_MULTIPART_RE LATED

16. Adding SOAP Headers
Useful to be able to add SOAP headers without writing a handler or hacking with the Envelope
serviceClient.addHeader(OMElement el);
sc.addStringHeader(QName tag, String value)‏

17. Dynamic Client What is a dynamic client?
Creating ServiceClient on the fly
From a WSDL
Why is this useful?
No need to worry about target EPR , soap action etc...
You can still override properties

18. Creating Dynamic client
The constructor of a dynamic client looks like the following:
ServiceClient(ConfigurationContext configContext,
URL wsdlURL,QName wsdlServiceName, String portName);

19. Overriding Properties
ServiceClient sc = new ServiceClient(
null,
new URL("
null);
// overriding target EPR
sc.getOptions().setTo(new EndpointReference(" /services/MyService"));

20. OperationClient Used internally by ServiceClient
Allows specific access to outgoing or incoming messages
OperationClients work with MessageContext instances
Useful if you need tight control or building middleware
Warning: It's hard work!

21. RPCServiceClient API This is not considered part of base client API
How it works:
Can take an array of Java beans
Or objects of primitive types (Integer, Boolean,..)‏
Specify the service/operation details
RPCServiceClient serializes the Java beans and sends out the SOAP message

22. Resources Reference Guide to Apache Axis2 Client API Parameters
Reference Guide to Axis2 Parameters – Part – I
Invoking Web Services Using Apache Axis2
Configuring Properties Within Axis2

23. Summary Service client Invocation Patterns Operation client
Supports both blocking and non-blocking invocations models
Can handle both transport dependent and transport independent asynchrony
Invocation Patterns
sendRobust, fireAndForget, sendReceive, sendReceiveNonBlocking
Operation client
Service Client has a set of operation clients
Options for the client
Addressing information, SOAP action (wsa:action), Transport data, Properties
Dynamic client
Creating ServiceClient on the fly
With it, no need to worry about target EPR , soap action etc...
RPCServiceClient API
Yet another way to interact with services.
Skills Matter –

24. Exercises Get familiar with the API documentation of ServiceClient
Options
ConfigurationContext
MessageContext
Download and extract the sample code zip file. Read the README file. Included client flavors:
Blocking client
Non-blocking client
OperationClient usage