1_2/xdocs/@axis2_version_dir@/http-transport.html - axis-axis2-java-core - Git at Google

 <!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>
	<!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><transportSender/> element is used to define transport senders in
	the axis2.xml as follows:</p>
	<pre><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></pre>

	<p>The above code snippet shows the simplest configuration of a transport
	sender for common use. <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. 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><transportSender name="<b>https</b>" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
	<parameter name="PROTOCOL" locked="false">HTTP/1.1</parameter>
	<parameter name="Transfer-Encoding">chunked</parameter>
	</transportSender></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><parameter name="SO_TIMEOUT" locked="false">some_int_value</parameter></pre>

	<p>For Connection timeout:</p>
	<pre> <parameter name="CONNECTION_TIMEOUT" locked="false">some_int_value</parameter></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> <parameter name="PROTOCOL" locked="false">HTTP/1.0</parameter></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><transportSender name="<b>http</b>" 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></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>