Apache Axis2 XML Based Client API

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

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

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

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

Invocation patterns sendRobust fireAndForget sendReceive sendReceiveNonBlocking

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

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

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("http://127.0.0.1:8080/axis2/services/MyService")); //setting action opts.setAction("urn:echo"); sc.setOptions(opts); //invoke service sc.sendReceive(element);

Options Options options = new Options()‏ // which version of SOAP options.setSoapVersionURI("http://...); // 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);

Properties LOTS and LOTS A full list is available here: http://wso2.org/library/230 Another interesting document: http://wso2.org/library/3025

Properties MessageContextConstants.TRANSPORT_URL Configuration.ENABLE_MTOM options.setTo("http://destination.org"); options.setProperty( MessageContextConstants.TRANSPORT_URL, "http://mySOAPIntermediary.org");

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)‏

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…

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

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)‏

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

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

Overriding Properties ServiceClient sc = new ServiceClient( null, new URL("http://127.0.0.1:8080/axis2/services/MyService?wsdl"), null); // overriding target EPR sc.getOptions().setTo(new EndpointReference("http://127.0.0.1:8000/axis2 /services/MyService"));

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!

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

Resources Reference Guide to Apache Axis2 Client API Parameters http://wso2.org/library/230 Reference Guide to Axis2 Parameters – Part – I http://wso2.org/library/3025 Invoking Web Services Using Apache Axis2 http://today.java.net/pub/a/today/2006/12/13/invoking-web-services-using-apache-axis2.html Configuring Properties Within Axis2 http://wso2.org/library/3122

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 – 2006 23

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