Reference Guide to Apache Axis2 Client API Parameters

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Eran Chinthaka
  • 1 Aug, 2006

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 Constants.Configuration.TRANSPORT_URL any URL
  Constants.Configuration. CHARACTER_SET_ENCODING Character set encoding scheme as a String
  Constants.Configuration.ENABLE_MTOM
"true"/"false"or Boolean.TRUE/Boolean.FALSE
WS-Addressing module specific constants AddressingConstants. WS_ADDRESSING_VERSION
org.apache.axis2.addressing.
AddressingConstants.Final.WSA_NAMESPACE
and
org.apache.axis2.addressing.AddressingConstants.
Submission.WSA_NAMESPACE
  AddressingConstants. REPLACE_ADDRESSING_HEADERS
"true"/"false" or Boolean.TRUE/Boolean.FALSE
  AddressingConstants. DISABLE_ADDRESSING_FOR_OUT_MESSAGES
"true"/"false" or Boolean.TRUE/Boolean.FALSE
HTTP Constants HTTPConstants.CHUNKED
"true"/"false" or Boolean.TRUE/Boolean.FALSE
  HTTPConstants.NTLM_AUTHENTICATION an instance of
org.apache.axis2.transport.http.
HttpTransportProperties.NTLMAuthentication
  HTTPConstants.PROXY an instance of
org.apache.axis2.transport.http.
HttpTransportProperties.ProxyProperties
  HTTPConstants.BASIC_AUTHENTICATION an instance of
org.apache.axis2.transport.http.
HttpTransportProperties.BasicAuthentication
  HTTPConstants.SO_TIMEOUT Integer
  HTTPConstants.CONNECTION_TIMEOUT Integer
  HTTPConstants.USER_AGENT String
  HTTPConstants.MC_GZIP_REQUEST
"true"/"false" or Boolean.TRUE/Boolean.FALSE
  HTTPConstants.MC_ACCEPT_GZIP
"true"/"false" or Boolean.TRUE/Boolean.FALSE
  HTTPConstants.COOKIE_STRING String
  HTTPConstants.HTTP_PROTOCOL_VERSION

  • HTTP/1.1 - HTTPConstants.HEADER_PROTOCOL_11

  • HTTP/1.0 - HTTPConstants.HEADER_PROTOCOL_10
  HTTPConstants.HTTP_HEADERS ArrayList of org.apache.commons.httpclient.Header objects
  HTTPConstants.REUSE_HTTP_CLIENT
"true"/"false" or Boolean.TRUE/Boolean.FALSE
  HTTPConstants.CACHED_HTTP_CLIENT
org.apache.commons.httpclient.HttpClient
Constants to be used in a REST invocation Constants.Configuration.ENABLE_REST
"true"/"false" or Boolean.TRUE/Boolean.FALSE
  Constants.Configuration.HTTP_METHOD
org.apache.axis2.Constants.Configuration.
HTTP_METHOD_GET
and
org.apache.axis2.Constants.Configuration.
HTTP_METHOD_POST
  Constants.Configuration.CONTENT_TYPE
  • 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


Generic Constants

  • org.apache.axis2.Constants.Configuration.TRANSPORT_URL

    Sometimes you want to send your SOAP message through a node, before it reaches to its destination. This means you want to give transport URL different from the URL of the ultimate destination. A typical example would be wanting to send this SOAP (or REST)message through a transparent proxy or through a message monitoring applet. How can that be done using the ServiceClient API?

        options.setTo("http://destination.org");
    options.setProperty(MessageContextConstants.TRANSPORT_URL, "http://myProxy.org");

    This will send your SOAP message to "http://myProxy.org", but if WS-Addressing is enabled, wsa:To will contain "http://destination.org" as To address.

  • org.apache.axis2.Constants.Configuration.CHARACTER_SET_ENCODING

    This will enable user to set the character set encoding scheme to be used when sending the message. Default is set to "UTF-8"

  • org.apache.axis2.Constants.Configuration.ENABLE_MTOM

    This will enable/disable MTOM support for outgoing messages. Possible values are:

    "true"/"false" or Boolean.TRUE/Boolean.FALSE

     


WS-Addressing Module Specific Constants

  • org.apache.axis2.addressing.AddressingConstants.WS_ADDRESSING_VERSION

    This will enable to select one of the two WS-Addressing versions available, if WS-Addressing is engaged. Possible values are:

    org.apache.axis2.addressing.AddressingConstants.Final.WSA_NAMESPACE
    and
    org.apache.axis2.addressing.AddressingConstants.Submission.WSA_NAMESPACE

     

  • org.apache.axis2.addressing.AddressingConstants.REPLACE_ADDRESSING_HEADERS

    AddressingOutHandler picks up the addressing information from the message context and set them to the outgoing message. But someone may have already put some addressing headers, before the AddressingOutHandler. This flag will notify the handler whether to override them or not. Possible values are:

    "true"/"false" or Boolean.TRUE/Boolean.FALSE

     

  • org.apache.axis2.addressing.AddressingConstants. DISABLE_ADDRESSING_FOR_OUT_MESSAGES

    If WS-Addressing is engaged globally or some how in effect for this particular invocation, this will disable Axis2 from putting WS-Addressing headers in to the out going SOAP message. (Note that Axis2 will not put addressing headers to the outgoing message, irrespective of the above flag, if the incoming message did not contain addressing headers). Possible values are:

    "true"/"false" or Boolean.TRUE/Boolean.FALSE

     


HTTP Constants

  • org.apache.axis2.transport.http.HTTPConstants.CHUNKED

    This will enable/disable chunking support. Possible values are:

    "true"/"false" or Boolean.TRUE/Boolean.FALSE

     

  • org.apache.axis2.transport.http.HTTPConstants.NTLM_AUTHENTICATION

    This enables the user to pass in NTLM authentication information, such as host, port, realm, username, password to be used with HTTP transport sender. The value should always be an instance of:

    org.apache.axis2.transport.http.HttpTransportProperties.
    NTLMAuthentication

     

  • org.apache.axis2.transport.http.HTTPConstants.PROXY

    This enables the user to pass in proxy information, such as proxy host name, port, domain, username, password to be used with HTTP transport sender. The value should always be an instance of:

    org.apache.axis2.transport.http.HttpTransportProperties.ProxyProperties

     

  • org.apache.axis2.transport.http.HTTPConstants.BASIC_AUTHENTICATION

    This enables the user to pass in basic authentication information, such as host, port, realm, username, password to be used with HTTP transport sender. The value should always be an instance of:

    org.apache.axis2.transport.http.HttpTransportProperties.BasicAuthentication

     

  • org.apache.axis2.transport.http.HTTPConstants.SO_TIMEOUT

    This enables the user to pass in socket timeout value as an Integer. If nothing is set, the default value is 60000 milli seconds.

  • org.apache.axis2.transport.http.HTTPConstants.CONNECTION_TIMEOUT

    This enables the user to pass in connection timeout value as an Integer. If nothing is set, the default value is 60000 milli seconds.

  • org.apache.axis2.transport.http.HTTPConstants.USER_AGENT

    This enables the user to set the user agent header in the outgoing HTTP request. Default value is "Axis2"

  • org.apache.axis2.transport.http.HTTPConstants.MC_GZIP_REQUEST

    If set this will GZip your request and send over to the destination. Before doing this, you must make sure that the receiving end supports GZip compressed streams.
    Possible values are:

    "true"/"false" or Boolean.TRUE/Boolean.FALSE

     

  • org.apache.axis2.transport.http.HTTPConstants.MC_ACCEPT_GZIP

    Whether or not you send a gzip-ped request, you can choose to receive GZIP back from the server using this flag. Possible values are:

    "true"/"false" or Boolean.TRUE/Boolean.FALSE

     

  • org.apache.axis2.transport.http.HTTPConstants.COOKIE_STRING

    This enables the user to set the cookie string header in the outgoing HTTP request.

  • org.apache.axis2.transport.http.HTTPConstants.HTTP_PROTOCOL_VERSION

    This will set the HTTP protocol version to be used in sending the SOAP requests. Possible values are :

    HTTP/1.1 - HTTPConstants.HEADER_PROTOCOL_11
    HTTP/1.0 - HTTPConstants.HEADER_PROTOCOL_10

    Default is to use HTTP/1.1.

  • org.apache.axis2.transport.http.HTTPConstants.HTTP_HEADERS

    You might sometimes want to send your own custom HTTP headers. You can set an ArrayList filled with

    org.apache.commons.httpclient.Header

    objects using the above property. You must not try to override the Headers the Axis2 engine is setting to the outgoing message.

     

  • org.apache.axis2.transport.http.HTTPConstants.REUSE_HTTP_CLIENT

    You might want to use the same HTTPClient instance for multiple invocations. This flag will notify the engine to use the same HTTPClient between invocations.

  • org.apache.axis2.transport.http.HTTPConstants.CACHED_HTTP_CLIENT

    If user had requested to re-use an HTTPClient using the above property, this property can be used to set a custom HTTPClient to be re-used.


Constants to be used in a REST Invocation

  • org.apache.axis2.transport.http.Constants.Configuration.ENABLE_REST

    Enabling REST using the above flag will send your request as a REST invocation. Possible values are:

    "true"/"false" or Boolean.TRUE/Boolean.FALSE

     

  • org.apache.axis2.transport.http.Constants.Configuration.HTTP_METHOD

    This will help the user to pick the HTTP method to be used during a REST invocation. Possible values are :

    org.apache.axis2.Constants.Configuration.HTTP_METHOD_GET
    and
    org.apache.axis2.Constants.Configuration.HTTP_METHOD_POST

    Default is to use POST method.

  • org.apache.axis2.transport.http.Constants.Configuration.CONTENT_TYPE

    This will help the user to pick the content type to be used during a REST invocation. Possible values are :

    • application/xml -
      HTTPConstants.MEDIA_TYPE_APPLICATION_XML
    • application/x-www-form-urlencoded -
      HTTPConstants.MEDIA_TYPE_X_WWW_FORM
    • text/xml -
      MEDIA_TYPE_TEXT_XML
    • multipart/related -
      MEDIA_TYPE_MULTIPART_RELATED

The properties mentioned above helps user to gain control in message sending and receiving process. And at the same time it helps to maintain a much cleaner API, rather than having two methods, to set and get, for each and every property.

Ok, I tweaked the Axis2 engine using one or more of the above parameters, but how can I know whether those actually work? Look no further than the next setion.

How Can I Know Whether those actually work?

It's pretty much easy. You need to channel all your messages through TCPMon (It's a TCP packet sniffer which you can be used to watch message exchanges). This 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 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

Author

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

About Author

  • Eran Chinthaka
  • Software Engineer
  • WSO2 Inc.