There are lots of parameters that can be used within Axis2 to change its behavior at runtime. This series of articles focuses on explaining these parameters.
|
Date: Wed, 5th Mar, 2008
Level:
Intermediate
Reads: 9794 Comments: 0 |
Login or register to post comments |
|
|
|
Eran Chinthaka
Software Engineer
WSO2 Inc. |
|
|
|
Introduction
HTTP is the protocol most people use to invoke Web services. There are various capabilities of the
HTTP protocol that can, when properly combined with Web services, provide powerful features for you,
the user. Web services engines should not depend on any transport protocol by any means. These days, it is a well known challenge for Web services to try to strike a balance between being transport independent and enabling users to use the powerful and unique features provided by various transports. Axis2 exposes a rich set of transport features for its users without compromising on its ability to be transport independent. Users may tweak various HTTP transport specific parameters using Axis2 properties. We talked about configuration parameters in the first part of this article series on Axis2 parameters. This article will talk about the various properties available to configure HTTP protocol specific parameters from inside Axis2.
Applies To
| Project |
Apache Axis2 1.3 or later |
| Environment |
JDK 1.4 or later |
HTTP Parameters In Axis2
These parameters, as you will see, can sometimes get changed from one version of Axis2 to another. These changes will mostly consist of new additions and maybe a few refactorings in each release. This series of articles is guaranteed to work on Axis2 1.3 and 1.4 versions. Many of the parameters will still work with previous or later versions of Axis2, but the author strongly suggests that you check the compatibility of the parameters and the Axis2 version you will be using.
Since all of these parameters are defined inside org.apache.axis2.transport.http.HTTPConstants class, the following table omits the class and package prefix. When attempting to use the following properties, you should prefix the property name with "org.apache.axis2.transport.http.HTTPConstants".
These parameters can be categorized in different ways. Some parameters can be used in the client side, server side or in both cases. In this categorization, "Client" is whenever we send a message out. "Server" is whenever we receive a message or handle a response before sending it. At the same time, some parameters are read only and the others can be used to set values (writable) in to Axis2. Therefore with each parameter name, you can see where it can be used and whether it is read only, writable or both.
This parameter will hold the HTTP status code after the invocation. Obviously this will not carry any meaningful information prior to completing an invocation.
Most Axis2 Web services administrators prefer to host Axis2 inside a servlet engine. In that case, the ability to access the HttpServletResponse object for the relevant invocation might be handy. Service authors, module authors or even Axis2 internal developers whose code is at work in the server side, can use this property to get hold of the HttpServletResponse object related to the current invocation.
Just like being able to access the HttpServletResponse object as mentioned above, this parameter enables users to get a hold of the corresponding HttpServletRequest object.
The javax.servlet.ServletContext interface provides access to the global properties of the servlet engine it is in. When Axis2 is deployed inside a servlet container, MC_HTTP_SERVLETCONTEXT parameter will provide access to the javax.servlet.ServletContext object of the current engine.
This will set the socket timeout in milliseconds to be used when executing the method with the underlying HTTP client that is being used. Axis2 uses Apache HttpClient as the default HTTP client implementation and therefore the SO_TIMEOUT property will set "http.socket.timeout" property of Apache HttpClient. In general, a timeout value of zero is interpreted as saying the method should never time out. See here for more information on socket timeouts.
PROXY ( Client, Writable)
This is used when a proxy is being used for Web service invocations. The value of this parameter should be an instance of org.apache.axis2.transport.http.HttpTransportProperties.ProxyProperties. The ProxyProperties java bean enables you to set properties associated with proxy invocations like, proxy port, domain, proxy host, username, password etc.
This is how Axis2 enables basic, digest, NTLM and custom authentications. If you need to use any of these authentication methods, you should first create an instance of org.apache.axis2.transport.http.HttpTransportProperties.Authenticator. Then you need to fill in the relevant information for this bean, depending on the authentication method. Then you can set this org.apache.axis2.transport.http.HttpTransportProperties.Authenticator object in to one of the contexts in the context hierarchy (the message context being the easiest pluggable point) associating it with AUTHENTICATE property.
This will set the connection timeout in milliseconds and is the the time allowed to pass for a connection to be established using the underlying http client that is being used. Since Axis2 uses Apache HttpClient as the default http client implementation, the CONNECTION_TIMEOUT property will set the "http.connection.timeout" property in Apache HttpClient. In general, a connection timeout value of zero is interpreted to mean there's no timeout being used. See here for more information on connection timeouts.
During Axis2 client side performance evaluations, it has been found that the creation of instances of HttpClient objects was a performance killer. So inside Axis2, we try to re-use the same HttpClient as much as possible. Sometimes, you may also need to set your own instance of Apache HttpClient for Axis2 to use internally. Setting the CACHED_HTTP_CLIENT property to an instance of HttpClient will ensure that your instance is used by Axis2.
As we mentioned above, Axis2 uses Apache HttpClient as the default HTTP client within the Axis2 engine. Apache HttpClient has the concept of connection managers. Since Axis2 allows for the execution of multiple HTTP requests concurrently (e.g. multiple requests against various sites, or multiple requests representing different user identities), the use of a dedicated thread per HTTP session can result in a significant performance gain. HttpClient is fully thread-safe when used with a thread-safe connection manager such as MultiThreadedHttpConnectionManager. The MULTITHREAD_HTTP_CONNECTION_MANAGER (PLEASE NOTE - there was an earlier spelling mistake where this property was named "MUTTITHREAD...". This has been corrected, but if you are using an earlier version you may need to use the misspelled name) property will alow you to set your own instance of MultiThreadedHttpConnectionManager. For more information on using connection managers, please refer to the Apache HttpClient performance improvement information page .
The CACHED_HTTP_CLIENT property mentioned above allows a client to set his or her own instance of a HttpClient object. Whereas the REUSE_HTTP_CLIENT property will force Axis2 to re-use its internal instance of HTTPClient across multiple invocations. This is hassle free way of gaining a performance increase without worrying about how the HttpClient object works.
You might want to know which HTTP method was used to receive a given message. The HTTP_METHOD parameter gives you the name of the HTTP method used to receive the message, on the server side.
On the other hand, if you want to select which HTTP method to be used while sending the message, then you need to use the org.apache.axis2.Constants.Configuration.HTTP_METHOD property to set the preferred HTTP method. You can set org.apache.axis2.Constants.Configuration.HTTP_METHOD with any of the following values: Constants.Configuration.HTTP_METHOD_GET, Constants.Configuration.HTTP_METHOD_DELETE and Constants.Configuration.HTTP_METHOD_PUT.
This enables the user to set the cookie policy property of Apache HttpClient, the HttpClient used within Axis2. Please refer here for more information on using cookie policies
If set, this will GZip your request before sending it over to the destination. But 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
By default the HTTP response body is not compressed. Set this message context property to true to have the response body be GZIP compressed.
Regardless of whether you are sending a GZIPped request or not, you can choose to receive GZIPped response back from the server using this flag. Possible values for this parameter are: "true"/"false" or Boolean.TRUE/Boolean.FALSE
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. Be aware that you must not try to override the Headers the Axis2 engine is adding to the outgoing message.
CHUNKED (Client, Writable)
Chunking is useful when you wants to send information, as soon as it is available, without waiting to receive all of the message. The sender will start sending chunks of messages with the "Transfer-Encoding: chunked" HTTP header. You can enable this behavior by setting the CHUNKED property to Boolean.TRUE. Note that this will only work with HTTP/1.1.
This will set the HTTP protocol version to be used in sending SOAP requests. Possible values are :
- HTTP/1.1 - HTTPConstants.HEADER_PROTOCOL_11
- HTTP/1.0 - HTTPConstants.HEADER_PROTOCOL_10
The default is to use HTTP/1.1.
This enables you to set the cookie-string header in the outgoing HTTP request.
You can define your own url scheme and assign a handler to handle that protocol. This is mainly used when someone needs to handle HTTPS using a custom protocol handler.
Refer to "How to Provide a Custom Socket Factory to be used in SSL Communication" for a detailed explanation on using this property.
HTTP method objects used to send messages might contain connections which are not released. When you set this property, Axis2 will clean up these connections by releasing them. This cleanup will happen after each HTTP method invocation.
This enables the user to set the user-agent header in the outgoing HTTP request. The default value is "Axis2"
SERVER (Server, Writable)
When set, the value of the SERVER property get sent as the value of the "Server" HTTP header. This is especially useful when one needs to customize the value of the Server address, within Axis2 server.
Summary
The First Part of this series of two articles concentrated on various configuration parameters. This article explored the HTTP configuration parameters available within Axis2. These are very useful to customize behavior if you are using HTTP to send and receive messages. Axis2 also tries to expose the powerful features provided by Apache Commons HttpClient project using these parameters.
Author
Author : Eran Chinthaka, Member-Apache Software Foundation. eranXchinthakaYgmail.com, where X=. and Y=@
Post to twitter
