<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="content-type" content="">
  <title>HTTP transports</title>
</head>

<body lang="en">
<a name="configTransport"/>
<h1>HTTP transports</h1>

<h3>CommonsHTTPTransportSender</h3>

<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-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.</p>

<p>Chunking support 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;<br/>        &lt;parameter name="PROTOCOL" locked="false"&gt;HTTP/1.1&lt;/parameter&gt;<br/>        &lt;parameter name="Transfer-Encoding"&gt;chunked&lt;/parameter&gt;<br/>&lt;/transportSender&gt;<br/></pre>

<p>Above code snippet shows the complete configuration of the transport
sender. &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. 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.</p>

<p>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.</p>

<h4>HTTPS support</h4>
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;<br/>        &lt;parameter name="PROTOCOL" locked="false"&gt;HTTP/1.1&lt;/parameter&gt;<br/>        &lt;parameter name="Transfer-Encoding"&gt;chunked&lt;/parameter&gt;<br/>&lt;/transportSender&gt;<br/></pre>
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.

<h2>Timeout Configuration</h2>

<p>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.</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/>
In runtime it's set as follows in the Stub. <source>
<pre>...
Options options = new Options();
options.setProperty(HTTPConstants.SO_TIMEOUT,new Integer(some_int_value));
options.setProperty(HTTPConstants.CONNECTION_TIMEOUT,new Integer(some_int_value));
...</pre>
</source>
<p></p>

<h2>HTTP Version Configuration</h2>
<p>The default HTTP version is 1.1. There are two methods in which user can change HTTP version to 1.0</p> 
<ol>
<li>By defining 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 user can change 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>

<h2>Proxy and NTLM Authentication</h2>

<p>HttpClient support "Basic, Digest and NTLM" authentication schemes. These
are used to authenticate with http servers and proxies.</p>

<p>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.</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;<br/></pre>

<p>For a particular proxy, if authentication is not available fill
"userName:domain:passWord"as "anonymous:anonymous:anonymous".</p>

<p>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,</p>
<pre>...
Options options = new Options();
....

HttpTransportProperties.ProxyProperties proxyProperties = new HttpTransportProperties.new ProxyProperties();
proxyProperties.setProxyHostName(....);
proxyProperties.setProxyPort(...);
...
options.setProperty(HttpConstants.PROXY, proxyProperties);
....</pre>

<p>The above code would eventually override the deployment proxy
configuration settings.</p>

<p>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.</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 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
    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.</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>
</body>
</html>