You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commons-dev@ws.apache.org by ve...@apache.org on 2009/03/21 15:38:49 UTC
svn commit: r756950 - in
/webservices/commons/trunk/modules/transport/src/site: apt/
apt/http-transport.apt apt/tcp-transport.apt site.xml xdoc/http.xml
xdoc/tcp.xml
Author: veithen
Date: Sat Mar 21 14:38:49 2009
New Revision: 756950
URL: http://svn.apache.org/viewvc?rev=756950&view=rev
Log:
Copied the documentation for the HTTP and TCP transports from the Axis2 documentation (converted to APT but not edited).
Added:
webservices/commons/trunk/modules/transport/src/site/apt/
webservices/commons/trunk/modules/transport/src/site/apt/http-transport.apt
webservices/commons/trunk/modules/transport/src/site/apt/tcp-transport.apt
Removed:
webservices/commons/trunk/modules/transport/src/site/xdoc/http.xml
webservices/commons/trunk/modules/transport/src/site/xdoc/tcp.xml
Modified:
webservices/commons/trunk/modules/transport/src/site/site.xml
Added: webservices/commons/trunk/modules/transport/src/site/apt/http-transport.apt
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/transport/src/site/apt/http-transport.apt?rev=756950&view=auto
==============================================================================
--- webservices/commons/trunk/modules/transport/src/site/apt/http-transport.apt (added)
+++ webservices/commons/trunk/modules/transport/src/site/apt/http-transport.apt Sat Mar 21 14:38:49 2009
@@ -0,0 +1,299 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+HTTP Transport
+
+ This document covers the sending and receiving of SOAP messages with Axis2 using HTTP
+ as the transport mechanism.
+
+* {Contents}
+
+%{toc|section=1|fromDepth=1}
+
+* {CommonsHTTPTransportSender}
+
+ 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 commons-httpclient-3.0.1.
+ For maximum flexibility, this sender supports both the HTTP GET and POST interfaces.
+ (REST in Axis2 also supports both interfaces.)
+
+ Commons HttpClient also provides HTTP 1.1, Chunking and KeepAlive support for Axis2.
+
+ The \<transportSender/\> element defines transport senders in
+ the axis2.xml configuration file as follows:
+
++----------------------------------------------------------------------------------------------+
+<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+ <parameter name="PROTOCOL">HTTP/1.1</parameter>
+ <parameter name="Transfer-Encoding">chunked</parameter>
+</transportSender>
++----------------------------------------------------------------------------------------------+
+
+ The above code snippet shows the simplest configuration of a transport
+ sender for common use. The \<parameter/\> 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 "chunked" 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.
+
+ 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:
+
+----------------------------------------------------
+options.setProperty(HTTPConstants.CHUNKED, "false");
+----------------------------------------------------
+
+ Some absolute properties are provided at runtime instead. For example, character
+ encoding style (UTF-8, UTF-16, etc.) is provided via MessageContext.
+
+** {HTTPS support}
+
+ CommonsHTTPTransportSender can be also used to communicate over https.
+
++-----------------------------------------------------------------------------------------------+
+<transportSender name="https" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+ <parameter name="PROTOCOL">HTTP/1.1</parameter>
+ <parameter name="Transfer-Encoding">chunked</parameter>
+</transportSender>
++-----------------------------------------------------------------------------------------------+
+
+ 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 "https" 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
+ {{http://jakarta.apache.org/commons/httpclient/sslguide.html}}
+
+* {Timeout Configuration}
+
+ 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.
+
+ For Socket timeout:
+
+-----------------------------------------------------------
+<parameter name="SO_TIMEOUT">some_integer_value</parameter>
+-----------------------------------------------------------
+
+ For Connection timeout:
+
+-----------------------------------------------------------
+<parameter name="CONNECTION_TIMEOUT">some_integer_value</parameter>
+-----------------------------------------------------------
+
+ For runtime configuration, it can be set as follows within the client stub:
+
++----------------------------------------------------------------------------------------+
+...
+Options options = new Options();
+options.setProperty(HTTPConstants.SO_TIMEOUT, new Integer(timeOutInMilliSeconds));
+options.setProperty(HTTPConstants.CONNECTION_TIMEOUT, new Integer(timeOutInMilliSeconds));
+
+// or
+options.setTimeOutInMilliSeconds(timeOutInMilliSeconds);
+...
++----------------------------------------------------------------------------------------+
+
+* {HTTP Version Configuration}
+
+ The default HTTP version is 1.1. There are two methods in which the user
+ can change the HTTP version to 1.0
+
+ * By defining the version in axis2.xml as shown below.
+
+-----------------------------------------------------
+<parameter name="PROTOCOL">HTTP/1.0</parameter></pre>
+-----------------------------------------------------
+
+ * By changing the version at runtime by using code similar to the following:
+
++-----------------------------------------------------------------------------------------+
+...
+options.setProperty(org.apache.axis2.context.MessageContextConstants.HTTP_PROTOCOL_VERSION,
+ org.apache.axis2.transport.http.HTTPConstants.HEADER_PROTOCOL_10);
+...
++-----------------------------------------------------------------------------------------+
+
+* {Proxy Authentication}
+
+ 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.
+
++----------------------------------------------------------------------------------------------+
+<transportSender name="http" class="org.apache.axis2.transport.http.CommonsHTTPTransportSender">
+ <parameter name="PROTOCOL">HTTP/1.1</parameter>
+ <parameter name="PROXY" proxy_host="proxy_host_name" proxy_port="proxy_host_port"
+ >userName:domain:passWord</parameter>
+</transportSender>
++----------------------------------------------------------------------------------------------+
+
+ For a particular proxy, if authentication is not available, enter the
+ "userName:domain:passWord" as "anonymous:anonymous:anonymous".
+
+ Prior shown configuration has been deprecated after Axis2 1.2 release and we strongly recommend using the new
+ proxy configuration as below.
+
+ New proxy configuration would require the user to add a TOP level parameter in the axis2.xml named "Proxy".
+
++------------------------------------------+
+<parameter name="Proxy">
+ <Configuration>
+ <ProxyHost>example.org</ProxyHost>
+ <ProxyPort>5678</ProxyPort>
+ <ProxyUser>EXAMPLE\saminda</ProxyUser>
+ <ProxyPassword>ppp</ProxyPassword>
+ </Configuration>
+</parameter>
++------------------------------------------+
+
+ Thus, if its a open proxy, user can ignore ProxyUser and ProxyPassword elements.
+
+ 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
+-----------------------------------------------------
+
+ 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:
+
++----------------------------------------------------------------------------------------------------------+
+...
+Options options = new Options();
+...
+
+HttpTransportProperties.ProxyProperties proxyProperties = new HttpTransportProperties.new ProxyProperties();
+proxyProperties.setProxyHostName(....);
+proxyProperties.setProxyPort(...);
+...
+options.setProperty(HttpConstants.PROXY, proxyProperties);
+...
++----------------------------------------------------------------------------------------------------------+
+
+ The above code will override the deployment proxy configuration settings.
+
+* {Basic, Digest and NTLM Authentication}
+
+ 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.
+
+ 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.
+
+ 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.
+
+ [[1]] 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).
+
+ [[2]] 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.
+
+ [[3]] 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.
+
+ []
+
+ Axis2 also allows adding a custom Authentication Scheme to HttpClient.
+
+ 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:
+
++------------------------------------------------------------------------------------+
+...
+Options options = new Options();
+
+HttpTransportProperties.Authenticator
+ auth = new HttpTransportProperties.Authenticator();
+auth.setUsername("username");
+auth.setPassword("password");
+// set if realm or domain is known
+
+options.setProperty(org.apache.axis2.transport.http.HTTPConstants.AUTHENTICATE, auth);
+...
++------------------------------------------------------------------------------------+
+
+* {Reusing the httpclient object}
+
+ 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:
+
+-------------------------------------------------------------
+options.setProperty(HTTPConstants.REUSE_HTTP_CLIENT, "true");
+-------------------------------------------------------------
+
+* {Setting the cached httpclient object}
+
+ 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:
+
++-------------------------------------------------------------------------+
+MultiThreadedHttpConnectionManager conmgr = new
+MultiThreadedHttpConnectionManager();
+conmgr.getParams().setDefaultMaxConnectionsPerHost(10);
+HttpClient client = new HttpClient(conmgr);
+configurationContext.setProperty(HTTPConstants.CACHED_HTTP_CLIENT, client);
++-------------------------------------------------------------------------+
Added: webservices/commons/trunk/modules/transport/src/site/apt/tcp-transport.apt
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/transport/src/site/apt/tcp-transport.apt?rev=756950&view=auto
==============================================================================
--- webservices/commons/trunk/modules/transport/src/site/apt/tcp-transport.apt (added)
+++ webservices/commons/trunk/modules/transport/src/site/apt/tcp-transport.apt Sat Mar 21 14:38:49 2009
@@ -0,0 +1,118 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+TCP Transport
+
+ This document explains how to send and receive SOAP messages via TCP in Axis2.
+
+* {Content}
+
+%{toc|section=1|fromDepth=1}
+
+* {Introduction}
+
+ Axis2 supports TCP as a transport. It supports both sending and receiving SOAP
+ messages via TCP. A TCP transport does not have any application level headers
+ and the SOAP message that is sent should be self-contained. This makes the
+ interaction fast and simple. However, since there are no application headers,
+ it does not have the privilege of having a request URI, and Service
+ dispatching should be done by an alternative method. Thus,
+ RequestURIBasedDispatcher cannot be used. The following are the two main
+ alternatives available for dispatching in the Axis2 environment:
+
+ [[1]] Use the name space URI of the first child element of SOAPBody.
+ (SOAPMessageBodyBasedDispatcher).
+
+ [[2]] Enable WS-Addressing. In the case of version 1.1 and 1.1.1 releases
+ Addressing is default (SOAPActionBasedDispatcher).
+
+ []
+
+ When the TCP request is sent, it is the user's responsibility to use
+ either Addressing or the SOAP body base mechanism.
+
+* {How to Start the TCPServer}
+
+ The TCP server can be started by running the class
+ org.apache.axis2.transport.tcp.TCPServer with two parameters -
+ repository and port number, as arguments. This
+ class needs all the Axis dependency JARs in the classpath. New services can
+ be added in the usual way by dropping the archives to the repository.
+
+* {How to Send SOAP Messages Using TCP Transport}
+
+ TCP transport can be enabled easily from the call API. The following code
+ segment demonstrates how this can be done.
+
++------------------------------------------------------+
+OMElement payload = ...
+ServiceClient serviceClient = new ServiceClient();
+Options options = new Options();
+options.setTo(targetEPR);
+options.useSeparateListener(false);
+serviceClient.setOptions(options);
+OMElement response = serviceClient.sendReceive(payload);
++------------------------------------------------------+
+
+ The transport that should be invoked is inferred from the targetEPR
+ (tcp://...). In this case it is TCP and the listener is also TCP. The SOAP
+ message has to be self contained in order to use Addressing. The other option
+ is to use the URI of the first child of the SOAP Body to dispatch the
+ service. The parameter is of the type OMElement,
+ the XML representation of Axis2.
+
+* {Samples}
+
+ A sample for a TCP Client can be found from the
+ samples/userguide/src/userguide/clients/TCPClient.java in the binary
+ distribution. This accesses the same Web service explained in the
+ Axis2 Advanced User's Guide. The client first
+ starts the TCPServer with the same repository used for the
+ Axis2 Advanced User's Guide samples. Since the
+ sample is already deployed in the repository, as per the userguide, it will
+ be automatically available.
+
+ In order to run the TCPClient.java, addressing should be engaged both in
+ the client and server sides. On the client side, you can engage addressing by
+ copying the addressing-@axis2_version@.mar (AXIS2_HOME/repository/module) to
+ AXIS2_HOME/lib directory.
+
+* {Transport Components}
+
+ The Axis2 TCP transport has two components, a transport Listener for
+ receiving the messages and a transport Sender to send the SOAP Messages. The
+ Axis2 installation has both the components built into itself by default. In
+ the axis2.xml configuration file, the two TCP transport components can be
+ configured as shown below.
+
+ The following XML lines initialize the TCPTransport Receiver:
+
++-----------------------------------------------------------------------------+
+<transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPServer">
+ <parameter name="port">6060</parameter>
+</transportReceiver>
++-----------------------------------------------------------------------------+
+
+ The following XML lines add the TCPTransport Sender:
+
++-------------------------------------------------------------------------------------+
+<transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/>
++-------------------------------------------------------------------------------------+
+
+ Note: If the TCP server is started manually, this configuration does not take
+ effect. In return, this affects the transport Listener's start by Axis2.
+ (e.g. Listener started by the Complete Async interaction)
Modified: webservices/commons/trunk/modules/transport/src/site/site.xml
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/transport/src/site/site.xml?rev=756950&r1=756949&r2=756950&view=diff
==============================================================================
--- webservices/commons/trunk/modules/transport/src/site/site.xml (original)
+++ webservices/commons/trunk/modules/transport/src/site/site.xml Sat Mar 21 14:38:49 2009
@@ -32,11 +32,11 @@
<menu name="Transport">
<item name="About" href="index.html"/>
<item name="Documentation">
- <item name="HTTP" href="http.html"/>
+ <item name="HTTP" href="http-transport.html"/>
<item name="JMS" href="jms.html"/>
<item name="Mail" href="mail.html"/>
<item name="Local" href="local.html"/>
- <item name="TCP" href="tcp.html"/>
+ <item name="TCP" href="tcp-transport.html"/>
<item name="XMPP" href="xmpp.html"/>
</item>
</menu>