Reference Guide to Apache Axis2 Client API Parameters

In this document Eran Chinthaka gives an invaluable guide to users on how to tweak Apache Axis2 client side engine's internal settings using parameters while sending and receiving messages.

Introduction

Apache Axis2 client API, which mainly includes ServiceClient or OperationClient, provides easy to use methods for users to send and receive SOAP and REST messages. This API has methods to get/set frequently used parameters. But in addition to that, there are a number of optional parameters that a user can set. Client API does not provide methods for each of these parameter, but user can set those as properties using the Options object that you pass in to the ServiceClient or OperationClient. These parameters helps the users to tweak Apache Axis2 client side engine's internal settings while sending and receiving messages. All these should be set through the client API using setProperty() method of the Options object that you pass in.

Options options = new Options();
options.setProperty(propertyName, propertyValue);

ServiceClient serviceClient = new ServiceClient();
sender.setOptions(options);

Now let's have a quick look at the different parameters available in Axis2 engine.

Parameters, A Quick Guide

Category	Constant	Possible Values
Generic Constants [0]	Constants.Configuration.TRANSPORT_URL [0]	any URL
	Constants.Configuration. CHARACTER_SET_ENCODING [0]	Character set encoding scheme as a String
	Constants.Configuration.ENABLE_MTOM [0]	"true"/"false"or Boolean.TRUE/Boolean.FALSE
WS-Addressing module specific constants [0]	AddressingConstants. WS_ADDRESSING_VERSION [0]	org.apache.axis2.addressing. AddressingConstants.Final.WSA_NAMESPACE and org.apache.axis2.addressing.AddressingConstants. Submission.WSA_NAMESPACE
	AddressingConstants. REPLACE_ADDRESSING_HEADERS [0]	"true"/"false" or Boolean.TRUE/Boolean.FALSE
	AddressingConstants. DISABLE_ADDRESSING_FOR_OUT_MESSAGES [0]	"true"/"false" or Boolean.TRUE/Boolean.FALSE
HTTP Constants [0]	HTTPConstants.CHUNKED [0]	"true"/"false" or Boolean.TRUE/Boolean.FALSE
	HTTPConstants.NTLM_AUTHENTICATION [0]	an instance of org.apache.axis2.transport.http. HttpTransportProperties.NTLMAuthentication
	HTTPConstants.PROXY [0]	an instance of org.apache.axis2.transport.http. HttpTransportProperties.ProxyProperties
	HTTPConstants.BASIC_AUTHENTICATION [0]	an instance of org.apache.axis2.transport.http. HttpTransportProperties.BasicAuthentication
	HTTPConstants.SO_TIMEOUT [0]	Integer
	HTTPConstants.CONNECTION_TIMEOUT [0]	Integer
	HTTPConstants.USER_AGENT [0]	String
	HTTPConstants.MC_GZIP_REQUEST [0]	"true"/"false" or Boolean.TRUE/Boolean.FALSE
	HTTPConstants.MC_ACCEPT_GZIP [0]	"true"/"false" or Boolean.TRUE/Boolean.FALSE
	HTTPConstants.COOKIE_STRING [0]	String
	HTTPConstants.HTTP_PROTOCOL_VERSION [0]	HTTP/1.1 - HTTPConstants.HEADER_PROTOCOL_11 HTTP/1.0 - HTTPConstants.HEADER_PROTOCOL_10
	HTTPConstants.HTTP_HEADERS [0]	ArrayList of org.apache.commons.httpclient.Header objects
	HTTPConstants.REUSE_HTTP_CLIENT [0]	"true"/"false" or Boolean.TRUE/Boolean.FALSE
	HTTPConstants.CACHED_HTTP_CLIENT [0]	org.apache.commons.httpclient.HttpClient
Constants to be used in a REST invocation [0]	Constants.Configuration.ENABLE_REST [0]	"true"/"false" or Boolean.TRUE/Boolean.FALSE
	Constants.Configuration.HTTP_METHOD [0]	org.apache.axis2.Constants.Configuration. HTTP_METHOD_GET and org.apache.axis2.Constants.Configuration. HTTP_METHOD_POST
	Constants.Configuration.CONTENT_TYPE [0]	HTTPConstants.MEDIA_TYPE_APPLICATION_XML HTTPConstants.MEDIA_TYPE_X_WWW_FORM MEDIA_TYPE_TEXT_XML MEDIA_TYPE_MULTIPART_RELATED

Parameters, A More Detailed View

Now let's see what each of these parameters mean and what they can tweak inside Axis2

TCPMon [1] (It's a TCP packet sniffer which you can be used to watch message exchanges). This [2] will show you the way to setup TCPMon for the above task.

Then modify your TO EPR, which you pass in to OperationClient or ServiceClient constructor, to send your messages through the TCPMon. Thats it !!

How Does This Tweaking Propagate to the Correct Places Inside Axis2 Engine?

You set the parameters to the Options object. When you invoke the Web service though the client API, this option get registered with the message context that is being created. MessageContext is a construct within Axis2, which holds all the information about a particular message (Refer Apache Axis2 Architecture Guide [2] if you want to understand what message context means).

When handlers are invoked they get access to the message context along with all the properties you set. This is how properties are passed in to the AddressingHandler.

When you pass HTTP parameters, they are used within the HTTP transport sender (which most of the time is org.apache.axis2.transport.http.CommonsHTTPTransportSender. This is a special type of a handler which sits at the end of the handler chain.

Applies To

Project/Language : Apache Axis2 /Java 1.0

Environment : JDK 1.4 or later

References

Apache Axis2 Website [3]

Axis2 Architecture Guide [4]

TCPMon Tutorial [5]

Author

Eran Chinthaka, Senior Software Engineer, WSO2 Inc.chinthaka at wso2 dot com