<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type" content="">
  <title>HTTP transports</title>
  <link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
  media="all">
</head>

<body lang="en">
<a name="configTransport"></a>

<h1>HTTP Transport</h1>

<p>This document is all about HTTP sender and HTTP receiver, and how they
work in Axis2.</p>

<p><i>Send your feedback or questions to: <a
href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>.
(Subscription details are available on the <a
href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly
prefix subject with [Axis2]. </p>

<h2>Content</h2>
<ul>
  <li><a href="#CommonsHTTPTransportSender">CommonsHTTPTransportSender</a>
    <ul>
      <li><a href="#httpsupport">HTTPS support</a></li>
    </ul>
  </li>
  <li><a href="#timeout_config">Timeout Configuration</a></li>
  <li><a href="#version_config">HTTP Version Configuration</a></li>
  <li><a href="#auth">Proxy Authentication</a></li>
  <li><a href="#preemptive_auth">Basic,Digest and NTLM Authentication</a></li>
</ul>
<a name="CommonsHTTPTransportSender"></a>

<h2>CommonsHTTPTransportSender</h2>

<p>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.1. In
order to acquire the maximum flexibility, this sender has implemented POST
interface and GET interface. GET and HTTP interfaces are also involved in
Axis2 REST support.</p>

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

<p>&lt;transportSender/&gt; element is used to define transport senders in
the axis2.xml as follows:</p>
<pre>&lt;transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt;
     &lt;parameter name="PROTOCOL" locked="false"&gt;HTTP/1.1&lt;/parameter&gt;
     &lt;parameter name="Transfer-Encoding"&gt;chunked&lt;/parameter&gt;
      &lt;/transportSender&gt;</pre>

<p>The above code snippet shows the simplest configuration of a transport
sender for common use. &lt;parameter/&gt; element introduces the additional
parameters that should be compliant with the sender. HTTP PROTOCOL version
sets as HTTP/1.0 or HTTP/1.1. The default version is HTTP/1.1. It should be
noted that chunking support is available only for HTTP/1.1. Thus, even if the
user turns on "chunking", if the HTTP version is 1.0, this setting will be
ignored by the transport framework. KeepAlive is a default property in
version 1.1.</p>

<p>Some absolute properties are provided at runtime, such as character
encoding style (UTF-8, UTF-16 etc) is provided via MessageContext.</p>
<a name="httpsupport"></a>

<h3>HTTPS support</h3>
It should be noted that CommonsHTTPTransportSender can be used to communicate
over https. <code></code>
<pre>&lt;transportSender name="<b>https</b>" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt;
     &lt;parameter name="PROTOCOL" locked="false"&gt;HTTP/1.1&lt;/parameter&gt;
    &lt;parameter name="Transfer-Encoding"&gt;chunked&lt;/parameter&gt;
 &lt;/transportSender&gt;</pre>

<p>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.</p>
<a name="timeout_config"></a>

<h2>Timeout Configuration</h2>

<p>Two timeout instances exist in the transport level. They are called,
Socket timeout and Connection timeout. This can be configured at deployment
time or run time. At the time of deployment, the user has to add the
following lines in axis2.xml.</p>

<p>For Socket timeout:</p>
<pre>&lt;parameter name="SO_TIMEOUT" locked="false"&gt;some_int_value&lt;/parameter&gt;</pre>

<p>For Connection timeout:</p>
<pre> &lt;parameter name="CONNECTION_TIMEOUT" locked="false"&gt;some_int_value&lt;/parameter&gt;</pre>
<br>
At runtime, it is set as follows in the Stub. <source>
<pre>...
Options options = new Options();
options.setProperty(HTTPConstants.SO_TIMEOUT,new Integer(timeOutInMilliSeconds));
options.setProperty(HTTPConstants.CONNECTION_TIMEOUT,new Integer(timeOutInMilliSeconds));

// or

options.setTimeOutInMilliSeconds(timeOutInMilliSeconds);
...</pre>
</source><a name="version_config"></a>

<h2>HTTP Version Configuration</h2>

<p>The default HTTP version is 1.1. There are two methods in which the user
can change the HTTP version to 1.0</p>
<ol>
  <li>By defining the version in axis2.xml as shown below.</li>
  <pre> &lt;parameter name="PROTOCOL" locked="false"&gt;HTTP/1.0&lt;/parameter&gt;</pre>
  <li>Or the user can change the version at runtime by doing the
  following</li>
  <pre>...
options.setProperty(org.apache.axis2.context.MessageContextConstants.HTTP_PROTOCOL_VERSION,org.apache.axis2.transport.http.HTTPConstants.HEADER_PROTOCOL_10);
...</pre>
</ol>
<a name="auth"></a>

<h2>Proxy Authentication</h2>

<p>The Commons-http client has the inbuilt ability to support proxy
authentication. Axis2 uses deployment time and runtime mechanisms to
authenticate proxies. At deployment time, the user has to change the
axis2.xml as follows. This authentication will be available in HTTP and
HTTPS.</p>
<pre>&lt;transportSender name="<b>http</b>" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender"&gt;
        &lt;parameter name="PROTOCOL" locked="false"&gt;HTTP/1.1&lt;/parameter&gt;
        &lt;parameter name="PROXY" proxy_host="proxy_host_name" proxy_port="proxy_host_port" locked="true&gt;userName:domain:passWord&lt;/parameter&gt;
&lt;/transportSender&gt;</pre>

<p>For a particular proxy, if authentication is not available, enter thel
"userName:domain:passWord"as "anonymous:anonymous:anonymous".</p>

<p>At runtime, the user can override the PROXY settings with an Object of
HttpTransportProperties.ProxyProperties. On the stub, initiate an object of
the prior setting and set it to the MessageContext's property bag via
HttpConstants.PROXY. On the stub, it depicts as follows,</p>
<source><pre>...
Options options = new Options();
....

HttpTransportProperties.ProxyProperties proxyProperties = new HttpTransportProperties.new ProxyProperties();
proxyProperties.setProxyHostName(....);
proxyProperties.setProxyPort(...);
...
options.setProperty(HttpConstants.PROXY, proxyProperties);
....</pre>
</source>
<p>The above code would eventually override the deployment proxy
configuration settings.</p>
<a name="preemptive_auth"></a>

<h2>Basic, Digest and NTLM Authentication</h2>

<p>HttpClient supports three different types of HTTP authentication schemes:
Basic, Digest and NTLM. Based on the challenge provided by the server,
httpclient automatically selects the authentication scheme with which the
request should be authenticated.. The most secure will be NTLM and the least
secure will be Basic.</p>

<p>NTLM is the most complex of the authentication protocols supported by
HttpClient. It requires an instance of NTCredentials to 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.</p>

<p>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.</p>
<ol>
  <li>NTLM authentication works almost exactly the same way 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).</li>
  <li>The realm for NTLM authentication is the domain name of the computer to
    which you are being connected. This can be troublesome as servers often
    have multiple domain names that refer to them. Only the domain name that
    the 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 as null, which
    is used by default.</li>
  <li>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.</li>
</ol>

<p>Axis2 also allows to add a custom Authentication Scheme to httpclient.</p>

<p>The static inner bean Authenticator of HttpTransportProperties will hold
the state of the server to be authenticated with. Once filled, it has to be
set to the Options's property bag with the key as HTTPConstants.AUTHENTICATE.
The following code snippet shows the way of configuring the transport
framework to use Basic Authentication:</p>
<source><pre> ...
 Options options = new Options();
 
 HttpTransportProperties.Authenticator
                       auth = new HttpTransportProperties.Authenticator();
            auth.setUsername("username");
            auth.setPassword("password");
            // set if realm or domain is know

 options.setProperty(org.apache.axis2.transport.http.HTTPConstants.BASIC_AUTHENTICATE,auth);
 ...
 </pre>
</source></body>
</html>