blob: 131c5310dda1889afff8f36e659c006b740a3c98 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2018-05-19
| Rendered using Apache Maven Fluido Skin 1.6
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20180519" />
<meta http-equiv="Content-Language" content="en" />
<title>Apache Axis2 &#x2013; HTTP transports</title>
<link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" />
<link rel="stylesheet" href="../css/site.css" />
<link rel="stylesheet" href="../css/print.css" media="print" />
<script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script>
<meta http-equiv="content-type" content="" /> </head>
<body class="topBarDisabled">
<div class="container-fluid">
<div id="banner">
<div class="pull-left"><a href="http://www.apache.org/" id="bannerLeft"><img src="http://www.apache.org/images/asf_logo_wide.png" alt="Apache Axis2"/></a></div>
<div class="pull-right"><a href=".././" id="bannerRight"><img src="../images/axis.jpg" /></a></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2018-05-19<span class="divider">|</span>
</li>
<li id="projectVersion">Version: 1.7.8<span class="divider">|</span></li>
<li class=""><a href="http://www.apache.org" class="externalLink" title="Apache">Apache</a><span class="divider">/</span></li>
<li class=""><a href="../index.html" title="Axis2/Java">Axis2/Java</a><span class="divider">/</span></li>
<li class="active ">HTTP transports</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li class="nav-header">Axis2/Java</li>
<li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li>
<li><a href="../download.html" title="Downloads"><span class="none"></span>Downloads</a> </li>
<li><a href="javascript:void(0)" title="Release Notes"><span class="icon-chevron-down"></span>Release Notes</a>
<ul class="nav nav-list">
<li><a href="../release-notes/1.6.1.html" title="1.6.1"><span class="none"></span>1.6.1</a> </li>
<li><a href="../release-notes/1.6.2.html" title="1.6.2"><span class="none"></span>1.6.2</a> </li>
<li><a href="../release-notes/1.6.3.html" title="1.6.3"><span class="none"></span>1.6.3</a> </li>
<li><a href="../release-notes/1.6.4.html" title="1.6.4"><span class="none"></span>1.6.4</a> </li>
<li><a href="../release-notes/1.7.0.html" title="1.7.0"><span class="none"></span>1.7.0</a> </li>
<li><a href="../release-notes/1.7.1.html" title="1.7.1"><span class="none"></span>1.7.1</a> </li>
<li><a href="../release-notes/1.7.2.html" title="1.7.2"><span class="none"></span>1.7.2</a> </li>
<li><a href="../release-notes/1.7.3.html" title="1.7.3"><span class="none"></span>1.7.3</a> </li>
<li><a href="../release-notes/1.7.4.html" title="1.7.4"><span class="none"></span>1.7.4</a> </li>
<li><a href="../release-notes/1.7.5.html" title="1.7.5"><span class="none"></span>1.7.5</a> </li>
<li><a href="../release-notes/1.7.6.html" title="1.7.6"><span class="none"></span>1.7.6</a> </li>
<li><a href="../release-notes/1.7.7.html" title="1.7.7"><span class="none"></span>1.7.7</a> </li>
<li><a href="../release-notes/1.7.8.html" title="1.7.8"><span class="none"></span>1.7.8</a> </li>
</ul>
</li>
<li><a href="../modules/index.html" title="Modules"><span class="none"></span>Modules</a> </li>
<li><a href="../tools/index.html" title="Tools"><span class="none"></span>Tools</a> </li>
<li class="nav-header">Documentation</li>
<li><a href="../docs/toc.html" title="Table of Contents"><span class="none"></span>Table of Contents</a> </li>
<li><a href="../docs/installationguide.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li>
<li><a href="../docs/quickstartguide.html" title="QuickStart Guide"><span class="none"></span>QuickStart Guide</a> </li>
<li><a href="../docs/userguide.html" title="User Guide"><span class="none"></span>User Guide</a> </li>
<li><a href="../docs/jaxws-guide.html" title="JAXWS Guide"><span class="none"></span>JAXWS Guide</a> </li>
<li><a href="../docs/pojoguide.html" title="POJO Guide"><span class="none"></span>POJO Guide</a> </li>
<li><a href="../docs/spring.html" title="Spring Guide"><span class="none"></span>Spring Guide</a> </li>
<li><a href="../docs/webadminguide.html" title="Web Administrator's Guide"><span class="none"></span>Web Administrator's Guide</a> </li>
<li><a href="../docs/migration.html" title="Migration Guide (from Axis1)"><span class="none"></span>Migration Guide (from Axis1)</a> </li>
<li class="nav-header">Resources</li>
<li><a href="../faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li>
<li><a href="../articles.html" title="Articles"><span class="none"></span>Articles</a> </li>
<li><a href="http://wiki.apache.org/ws/FrontPage/Axis2/" class="externalLink" title="Wiki"><span class="none"></span>Wiki</a> </li>
<li><a href="../refLib.html" title="Reference Library"><span class="none"></span>Reference Library</a> </li>
<li><a href="../apidocs/index.html" title="Online Java Docs"><span class="none"></span>Online Java Docs</a> </li>
<li class="nav-header">Get Involved</li>
<li><a href="../overview.html" title="Overview"><span class="none"></span>Overview</a> </li>
<li><a href="../svn.html" title="Checkout the Source"><span class="none"></span>Checkout the Source</a> </li>
<li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li>
<li><a href="../release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li>
<li><a href="../guidelines.html" title="Developer Guidelines"><span class="none"></span>Developer Guidelines</a> </li>
<li><a href="../siteHowTo.html" title="Build the Site"><span class="none"></span>Build the Site</a> </li>
<li class="nav-header">Project Information</li>
<li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li>
<li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li>
<li><a href="http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/" class="externalLink" title="Source Code"><span class="none"></span>Source Code</a> </li>
<li><a href="../thanks.html" title="Acknowledgements"><span class="none"></span>Acknowledgements</a> </li>
<li class="nav-header">Apache</li>
<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="License"><span class="none"></span>License</a> </li>
<li><a href="http://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li>
<li><a href="http://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li>
<li><a href="http://www.apache.org/security/" class="externalLink" title="Security"><span class="none"></span>Security</a> </li>
</ul>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<html xmlns="http://www.w3.org/1999/xhtml" version="-//W3C//DTDXHTML1.1//EN">
<a name="configTransport"></a>
<h1>HTTP Transport</h1>
<p>This document covers the sending and receiving of SOAP messages with Axis2 using HTTP
as the transport mechanism.</p>
<div class="section">
<h2><a name="Contents"></a>Contents</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>
<li><a href="#reusing_httpclient_object">Reusing the httpclient object</a></li>
<li><a href="#setting_cached_httpclient_object">Setting the cached httpclient object</a></li>
</ul>
<a name="CommonsHTTPTransportSender"></a>
<div class="section">
<h2><a name="CommonsHTTPTransportSender"></a>CommonsHTTPTransportSender</h2>
<p>CommonsHTTPTransportSender is the transport sender that is used by default in both
the Server and Client APIs. As its name implies, it is based on <a class="externalLink" href="http://hc.apache.org/httpclient-3.x/">commons-httpclient-3.1</a>.
For maximum flexibility, this sender supports both the HTTP GET and POST interfaces.
(REST in Axis2 also supports both interfaces.)</p>
<p>Axis2 uses a single HTTPClient instance per ConfigurationContext (which usually means per instance
of ServiceClient). This pattern allows for HTTP 1.1 to automatically reuse TCP connections - in earlier versions of Axis2 the REUSE_HTTP_CLIENT configuration property was necessary to enable this functionality, but as of 1.5 this is no longer necessary.</p>
<p>Commons HttpClient also provides HTTP 1.1, Chunking and KeepAlive support for Axis2.</p>
<p>The &lt;transportSender/&gt; element defines transport senders in
the axis2.xml configuration file as follows:</p>
<div>
<pre>
&lt;transportSender name=&quot;http&quot; class=&quot;org.apache.axis2.transport.http.CommonsHTTPTransportSender&quot;&gt;
&lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/1.1&lt;/parameter&gt;
&lt;parameter name=&quot;Transfer-Encoding&quot;&gt;chunked&lt;/parameter&gt;
&lt;/transportSender&gt;
</pre></div>
<p>The above code snippet shows the simplest configuration of a transport
sender for common use. The &lt;parameter/&gt; element is used to specify additional
constraints that the sender should comply with. The HTTP PROTOCOL parameter
should be set as HTTP/1.0 or HTTP/1.1. The default version is HTTP/1.1. Note that
chunking support is available only for HTTP/1.1. Thus, even if &quot;chunked&quot; is specified
as a parameter, if the HTTP version is 1.0, this setting will be
ignored by the transport framework. Also, KeepAlive is enabled by default in
HTTP/1.1.</p>
<p>If you use HTTP1.1 for its Keep-Alive ability, but you need to disable
chunking at runtime (some servers don't allow chunked requests to
prevent denial of service), you can do so in the Stub:
</p>
<div>
<pre>
options.setProperty(HTTPConstants.CHUNKED, &quot;false&quot;);
</pre></div>
<p>Some absolute properties are provided at runtime instead. For example, character
encoding style (UTF-8, UTF-16, etc.) is provided via MessageContext.</p>
<a name="httpsupport"></a>
<div class="section">
<h3><a name="HTTPS_support"></a>HTTPS support</h3>
CommonsHTTPTransportSender can be also used to communicate over https.
<div>
<pre>
&lt;transportSender name=&quot;<b>https</b>&quot; class=&quot;org.apache.axis2.transport.http.CommonsHTTPTransportSender&quot;&gt;
&lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/1.1&lt;/parameter&gt;
&lt;parameter name=&quot;Transfer-Encoding&quot;&gt;chunked&lt;/parameter&gt;
&lt;/transportSender&gt;
</pre></div>
<p>Please note that by default HTTPS works only when the server does not
expect to authenticate the clients (1-way SSL only) and where the
server has the clients' public keys in its trust store.
If you want to perform SSL client authentication (2-way SSL), you may
use the Protocol.registerProtocol feature of HttpClient. You can
overwrite the &quot;https&quot; protocol, or use a different protocol for your
SSL client authentication communications if you don't want to mess
with regular https. Find more information at
<a class="externalLink" href="http://jakarta.apache.org/commons/httpclient/sslguide.html">http://jakarta.apache.org/commons/httpclient/sslguide.html</a></p>
<a name="timeout_config"></a>
</div>
<div class="section">
<h2><a name="Timeout_Configuration"></a>Timeout Configuration</h2>
<p>Two timeout instances exist in the transport level, Socket timeout
and Connection timeout. These can be configured either at deployment
or run time. If configuring at deployment time, the user has to add the
following lines in axis2.xml.</p>
<p>For Socket timeout:</p>
<div>
<pre>&lt;parameter name=&quot;SO_TIMEOUT&quot;&gt;some_integer_value&lt;/parameter&gt;</pre></div>
<p>For Connection timeout:</p>
<div>
<pre> &lt;parameter name=&quot;CONNECTION_TIMEOUT&quot;&gt;some_integer_value&lt;/parameter&gt;</pre></div>
<br />
For runtime configuration, it can be set as follows within the client stub:
<div>
<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></div>
<a name="version_config"></a>
<div class="section">
<h2><a name="HTTP_Version_Configuration"></a>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>
<ul>
<li>By defining the version in axis2.xml as shown below.
<div>
<pre> &lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/1.0&lt;/parameter&gt;</pre></div></li>
<li>By changing the version at runtime by using code similar to the following:
<div>
<pre>
...
options.setProperty(org.apache.axis2.context.MessageContextConstants.HTTP_PROTOCOL_VERSION,
org.apache.axis2.transport.http.HTTPConstants.HEADER_PROTOCOL_10);
...
</pre></div></li>
</ul>
<a name="auth"></a>
<div class="section">
<h2><a name="Proxy_Authentication"></a>Proxy Authentication</h2>
<p>The Commons-http client has built-in support for 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 is available for both HTTP and
HTTPS.</p>
<div>
<pre>
&lt;transportSender name=&quot;<b>http</b>&quot; class=&quot;org.apache.axis2.transport.http.CommonsHTTPTransportSender&quot;&gt;
&lt;parameter name=&quot;PROTOCOL&quot;&gt;HTTP/1.1&lt;/parameter&gt;
&lt;parameter name=&quot;PROXY&quot; proxy_host=&quot;proxy_host_name&quot; proxy_port=&quot;proxy_host_port&quot;&gt;userName:domain:passWord&lt;/parameter&gt;
&lt;/transportSender&gt;</pre></div>
<p>For a particular proxy, if authentication is not available, enter the
&quot;userName:domain:passWord&quot; as &quot;anonymous:anonymous:anonymous&quot;.</p>
<p>Prior shown configuration has been deprecated after Axis2 1.2 release and we strongly recommend using the new
proxy configuration as below. </p>
<p>
New proxy configuration would require the user to add a TOP level parameter in the axis2.xml named &quot;Proxy&quot;.
</p>
<div>
<pre>
&lt;parameter name=&quot;Proxy&quot;&gt;
&lt;Configuration&gt;
&lt;ProxyHost&gt;example.org&lt;/ProxyHost&gt;
&lt;ProxyPort&gt;5678&lt;/ProxyPort&gt;
&lt;ProxyUser&gt;EXAMPLE\saminda&lt;/ProxyUser&gt;
&lt;ProxyPassword&gt;ppp&lt;/ProxyPassword&gt;
&lt;/Configuration&gt;
&lt;/parameter&gt;
</pre></div>
<p> Thus, if its a open proxy, user can ignore ProxyUser and ProxyPassword elements. </p>
<p>In addition to this, if you don't want to go through writing the above parameter you could
use Java Networking Properties for open proxies,
-Dhttp.proxyHost=10.150.112.254 -Dhttp.proxyPort=8080 </p>
<p>At runtime, the user can override the PROXY settings using the
HttpTransportProperties.ProxyProperties object. Within your client stub,
create an instance of this object, configure proxy values for it,
and then set it to the MessageContext's property bag via options.setProperty().
For example:</p>
<div>
<pre>
...
Options options = new Options();
...
HttpTransportProperties.ProxyProperties proxyProperties = new HttpTransportProperties.new ProxyProperties();
proxyProperties.setProxyHostName(....);
proxyProperties.setProxyPort(...);
...
options.setProperty(HttpConstants.PROXY, proxyProperties);
...
</pre></div>
<p>The above code will override the deployment proxy configuration settings.</p>
<a name="preemptive_auth"></a>
<div class="section">
<h2><a name="Basic_Digest_and_NTLM_Authentication"></a>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 method is NTLM and the Basic
is the least secure.</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: &quot;axis2&quot; is correct
whereas &quot;DOMAIN\axis2&quot; 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 style="list-style-type: decimal">
<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 become 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 its default value.</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. Because of 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 adding 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 how to configure the transport
framework to use Basic Authentication:</p>
<div>
<pre>
...
Options options = new Options();
HttpTransportProperties.Authenticator
auth = new HttpTransportProperties.Authenticator();
auth.setUsername(&quot;username&quot;);
auth.setPassword(&quot;password&quot;);
// set if realm or domain is known
options.setProperty(org.apache.axis2.transport.http.HTTPConstants.AUTHENTICATE, auth);
...
</pre></div>
<a name="reusing_httpclient_object"></a>
<div class="section">
<h2><a name="Reusing_the_httpclient_object"></a>Reusing the httpclient object</h2>
<p>By default, a new httpclient object is created for each send. It may
be worthwhile to reuse the same httpclient object to take advantage of
HTTP1.1 Keep-Alive, especially in HTTPS environment, where the SSL
handshake may not be of negligible cost. To reuse the same httpclient
object, you can set the relevant property in the Stub:
</p>
<div>
<pre>options.setProperty(HTTPConstants.REUSE_HTTP_CLIENT, &quot;true&quot;);</pre></div>
<a name="setting_cached_httpclient_object"></a>
<div class="section">
<h2><a name="Setting_the_cached_httpclient_object"></a>Setting the cached httpclient object</h2>
To control the max connections per host attempted in parallel by a
reused httpclient (this can be worthwhile as the default value is 2
connections per host), or any other advanced parameters, you need to
set the cached httpclient object when your application starts up
(before any actual axis request). You can set the relevant property in
the Stub:
<div>
<pre>
MultiThreadedHttpConnectionManager conmgr = new MultiThreadedHttpConnectionManager();
conmgr.getParams().setDefaultMaxConnectionsPerHost(10);
HttpClient client = new HttpClient(conmgr);
configurationContext.setProperty(HTTPConstants.CACHED_HTTP_CLIENT, client);
</pre></div>
<a name="setting_cached_httpstate_object"></a>
<div class="section">
<h2><a name="Setting_the_cached_httpstate_object"></a>Setting the cached httpstate object</h2>
HttpState object can be set as property to the options of a given Axis2 client.
HttpState keeps HTTP attributes that may persist from request to request, such
as cookies and authentication credentials. So, it is possible to re-use one and
the same HttpState object if appropriate.
The idea is to provide the capability to specify/associate a separate HttpState
with every client and still reuse one and the same HttpClient. So, this make
sense only when CACHED_HTTP_CLIENT is re-used between different clients
from different threads which may invoke different hosts with different credentials
and cookies. This is really complicated scenario, but is absolutely possible one.
If you re-use a common HttpClient between different clients then the clients will
re-use, the internal for the HttpClient, HttpState object. Doing so authentication
credentials are exposed to all clients sharing one and the same HttpClient.
This is definitely not a good idea. The problem with Cookies is different. The
problem here is that if two distinct clients invoke one and the same service
at a specific host then the session established with a given cookie by one of
the clients can wrongly be shared among them, too, if it has not expired. This
will cause problems since the two client may need different sessions, which is
the more probable scenario.
Sample configuration:
<div>
<pre>
HttpState myHttpState = new HttpState();
options.setProperty(WSClientConstants.CACHED_HTTP_STATE, myHttpState);
</pre></div>
Doing so the HttpState is attached to the client. Respectively this is automatically propagated to all MessageContext objects used by the client.
Underneath this just instructs Axis2 that the CACHED_HTTP_STATE set should be passed as a parameter when HttpClient#executeMethod is invoked.
</html>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p>Copyright &copy;2004&#x2013;2018
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All rights reserved.</p>
</div>
</div>
</footer>
</body>
</html>