Return-Path: Delivered-To: apmail-ws-axis-cvs-archive@www.apache.org Received: (qmail 96576 invoked from network); 23 Mar 2006 07:39:31 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (209.237.227.199) by minotaur.apache.org with SMTP; 23 Mar 2006 07:39:31 -0000 Received: (qmail 43815 invoked by uid 500); 23 Mar 2006 07:39:23 -0000 Delivered-To: apmail-ws-axis-cvs-archive@ws.apache.org Received: (qmail 43400 invoked by uid 500); 23 Mar 2006 07:39:21 -0000 Mailing-List: contact axis-cvs-help@ws.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list axis-cvs@ws.apache.org Received: (qmail 43371 invoked by uid 500); 23 Mar 2006 07:39:20 -0000 Delivered-To: apmail-ws-axis2-cvs@ws.apache.org Received: (qmail 43352 invoked by uid 99); 23 Mar 2006 07:39:20 -0000 Received: from asf.osuosl.org (HELO asf.osuosl.org) (140.211.166.49) by apache.org (qpsmtpd/0.29) with ESMTP; Wed, 22 Mar 2006 23:39:20 -0800 X-ASF-Spam-Status: No, hits=-9.4 required=10.0 tests=ALL_TRUSTED,NO_REAL_NAME X-Spam-Check-By: apache.org Received: from [209.237.227.194] (HELO minotaur.apache.org) (209.237.227.194) by apache.org (qpsmtpd/0.29) with SMTP; Wed, 22 Mar 2006 23:39:12 -0800 Received: (qmail 95692 invoked by uid 65534); 23 Mar 2006 07:38:51 -0000 Message-ID: <20060323073851.95691.qmail@minotaur.apache.org> Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r388085 [3/6] - in /webservices/axis2/trunk/java/xdocs/latest: ./ adb/ adb/images/ images/ images/archi-guide/ images/tools/ images/tools/service/ images/tools/wsdl/ images/userguide/ resources/ resources/schemas/ sec-conf/ Date: Thu, 23 Mar 2006 07:38:40 -0000 To: axis2-cvs@ws.apache.org From: chatra@apache.org X-Mailer: svnmailer-1.0.7 X-Virus-Checked: Checked by ClamAV on apache.org X-Spam-Rating: minotaur.apache.org 1.6.2 0/1000/N Added: webservices/axis2/trunk/java/xdocs/latest/http-transport.html URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/latest/http-transport.html?rev=388085&view=auto ============================================================================== --- webservices/axis2/trunk/java/xdocs/latest/http-transport.html (added) +++ webservices/axis2/trunk/java/xdocs/latest/http-transport.html Wed Mar 22 23:38:30 2006 @@ -0,0 +1,149 @@ + + + + + HTTP transports + + + + +

HTTP transports

+ +

CommonsHTTPTransportSender

+ +

This is the default transport sender that is used in Server API as well as +Client API. As the name implies it is based on commons-httpclient-3.0-rc3. In +order to acquire the maximum flexibility, this sender has implemented POST +interface and GET interface. GET interface is provided to help axis2 support +REST.

+ +

Chunking support and KeepAlive support is also integrated via the +facilities provided by commons-httpclient along with HTTP 1.1 support.

+ +

<transportSender/> element is used to define transport senders in +the axis2.xml as follows:

<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
        <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
        <parameter name="Transfer-Encoding">chunked</parameter>
</transportSender>

+ +

Above code snippet shows the complete configuration of the transport +sender. <parameter/> element introduces the additional parameters that +should be compliant with the sender. HTTP PROTOCOL version sets as HTTP/1.0 +or HTTP/1.1. Default version is HTTP/1.1. It should be noted that chunking +support is available only for HTTP/1.1. Thus, the user should be careful in +setting the "chunked" property and use it only with version 1.1. KeepAlive +property is default in version 1.1.

+ +

These are the only parameters that are available from deployment. Other +parameters such as character encoding style (UTF-8, UTF-16 etc) etc, are +provided via MessageContext.

+ +

HTTPS support

+It should be noted that CommonsHTTPTransportSender can be used to communicate +over https. +

<transportSender name="https" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
        <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
        <parameter name="Transfer-Encoding">chunked</parameter>
</transportSender>

+Please note that https works only when the server does not expect to +authenticate the clients and where the server has the clients' public keys in +its trust store. + +

Timeout Configuration

+ +

There are two timeout exists in transport level. They are called, Socket +timeout and Connection timeout. This can be configured in deployment time or +in run time. In deployment time, user has to add the following lines in +axis2.xml.

+ +

For Socket timeout:

<parameter name="SO_TIMEOUT" locked="false">some_int_value</parameter>

+ +

For Connection timeout:

 <parameter name="CONNECTION_TIMEOUT" locked="false">some_int_value</parameter>

+
+In runtime it's set as follows in the Stub. +

...
+Options options = new Options();
+options.setProperty(HTTPConstants.SO_TIMEOUT,new Integer(some_int_value));
+options.setProperty(HTTPConstants.CONNECTION_TIMEOUT,new Integer(some_int_value));
+...

+ +

HTTP Version Configuration

The default HTTP version is 1.1. There are two methods in which user can change HTTP version to 1.0

By defining version in Axis2.xml as shown below.

 <parameter name="PROTOCOL" locked="false">HTTP/1.0</parameter>

Or user can change version at runtime by doing the following

...
+options.setProperty(org.apache.axis2.context.MessageContextConstants.HTTP_PROTOCOL_VERSION,org.apache.axis2.transport.http.HTTPConstants.HEADER_PROTOCOL_10);
+...

+ +

Proxy and NTLM Authentication

+ +

HttpClient support "Basic, Digest and NTLM" authentication schemes. These +are used to authenticate with http servers and proxies.

+ +

Axis2 uses deployment time and runtime mechanisms to authenticate proxies. +In deployment time, user has to change the Axis2.xml as follows. This +authentication will be available in http and https.

<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+        <parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
+        <parameter name="PROXY" proxy_host="proxy_host_name" proxy_port="proxy_host_port" locked="true>userName:domain:passWord</parameter>
+</transportSender>

+ +

For a particular proxy, if authentication is not available fill +"userName:domain:passWord"as "anonymous:anonymous:anonymous".

+ +

At runtime user can override the PROXY settings with an Object of +HttpTransportProperties.ProxyProperties. On the stub initiate an object of +prior and set it to the MessageContext's property bag via +HttpConstants.PROXY. On the stub, it depicts as follows,

...
+Options options = new Options();
+....
+
+HttpTransportProperties.ProxyProperties proxyProperties = new HttpTransportProperties.new ProxyProperties();
+proxyProperties.setProxyHostName(....);
+proxyProperties.setProxyPort(...);
+...
+options.setProperty(HttpConstants.PROXY, proxyProperties);
+....

+ +

The above code would eventually override the deployment proxy +configuration settings.

+ +

NTLM is the most complex of the authentication protocols supported by +HttpClient. It requires an instance of NTCredentials be available for the +domain name of the server or the default credentials. Note that since NTLM +does not use the notion of realms HttpClient uses the domain name of the +server as the name of the realm. Also note that the username provided to the +NTCredentials should not be prefixed with the domain - ie: "axis2" is correct +whereas "DOMAIN\axis2" is not correct.

+ +

There are some significant differences in the way that NTLM works compared +with basic and digest authentication. These differences are generally handled +by HttpClient, however having an understanding of these differences can help +avoid problems when using NTLM authentication.

NTLM authentication works almost exactly the same as any other form of + authentication in terms of the HttpClient API. The only difference is + that you need to supply 'NTCredentials' instead of + 'UsernamePasswordCredentials' (NTCredentials actually extends + UsernamePasswordCredentials so you can use NTCredentials right throughout + your application if need be).
The realm for NTLM authentication is the domain name of the computer + being connected to, this can be troublesome as servers often have + multiple domain names that refer to them. Only the domain name that + HttpClient connects to (as specified by the HostConfiguration) is used to + look up the credentials. It is generally advised that while initially + testing NTLM authentication, you pass the realm in as null which is used + as the default.
NTLM authenticates a connection and not a request, so you need to + authenticate every time a new connection is made and keeping the + connection open during authentication is vital. Due to this, NTLM cannot + be used to authenticate with both a proxy and the server, nor can NTLM be + used with HTTP 1.0 connections or servers that do not support HTTP + keep-alives.

Axis2 version 0.95 Documentation

Getting Started with Axis2

+ +

Tools References

+ +

Additional References

+ +