| <!-- |
| ~ 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. |
| --> |
| |
| <html> |
| <head> |
| <meta http-equiv="content-type" content=""/> |
| <title>TCP transport</title> |
| <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" |
| media="all"/> |
| </head> |
| |
| <body lang="en"> |
| <h1>TCP Transport</h1> |
| This document explains how to send and receive SOAP messages via TCP in Axis2. |
| |
| <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>. |
| Prefix subject with [Axis2]. Subscription details are available on the <a |
| href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>. |
| </p> |
| |
| <h2>Content</h2> |
| <ul> |
| <li><a href="#intro">Introduction</a></li> |
| <li><a href="#start">How to Start the TCPServer</a></li> |
| <li><a href="#send">How to Send SOAP Messages Using TCP Transport</a></li> |
| <li><a href="#samples">Samples</a></li> |
| <li><a href="#components">Transport Components</a></li> |
| </ul> |
| <a name="intro"></a> |
| |
| <h2>Introduction</h2> |
| |
| <p>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:</p> |
| <ol> |
| <li>Use the name space URI of the first child element of SOAPBody. |
| (SOAPMessageBodyBasedDispatcher).</li> |
| <li>Enable WS-Addressing. In the case of version 1.1 and 1.1.1 releases |
| Addressing is default (SOAPActionBasedDispatcher).</li> |
| </ol> |
| |
| <p>When the TCP request is sent, it is the user's responsibility to use |
| either Addressing or the SOAP body base mechanism.</p> |
| <a name="start"></a> |
| |
| <h2>How to Start the TCPServer</h2> |
| |
| <p>The TCP server can be started by running the class |
| org.apache.axis2.transport.tcp.TCPServer with two parameters - <a |
| href="../faq.html#c5">repository</a> 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 (See <a |
| href="adv-userguide.html">Advanced User's Guide</a> for more information)</p> |
| <!--<p>Alternatively the TCP Server can run with tcp-server.bat/ tcp-server.sh |
| file in the bin directory of the Binary distribution of TCP Server.</p>--> |
| <a name="send"></a> |
| |
| <h2>How to Send SOAP Messages Using TCP Transport</h2> |
| |
| <p>TCP transport can be enabled easily from the call API. The following code |
| segment demonstrates how this can be done.</p> |
| <source><pre>OMElement payload = ... |
| ServiceClient serviceClient = new ServiceClient(); |
| Options options = new Options(); |
| options.setTo(targetEPR); |
| <!--options.useSeperateListener(false);--> |
| |
| <!--commented off as there is an error: "The method useSeperateListener(boolean)is undefined for the type Options"--> |
| |
| serviceClient.setOptions(options); |
| |
| OMElement response = serviceClient.sendReceive(payload);</pre> |
| </source> |
| <p>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 <a href="../faq.html#a2">OMElement</a>, |
| the XML representation of Axis2.</p> |
| <a name="samples"></a> |
| |
| <h2>Samples</h2> |
| |
| <p>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 <a |
| href="adv-userguide.html">Axis2 Advanced User's Guide</a>. The client first |
| starts the TCPServer with the same repository used for the <a |
| href="adv-userguide.html">Axis2 Advanced User's Guide</a> samples. Since the |
| sample is already deployed in the repository, as per the userguide, it will |
| be automatically available.</p> |
| |
| <p>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.</p> |
| <a name="components"></a> |
| |
| <h2>Transport Components</h2> |
| |
| <p>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.</p> |
| |
| <p>The following XML lines initialize the TCPTransport Receiver:</p> |
| <source><pre><transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPServer"> |
| <parameter name="port">6060</parameter> |
| </transportReceiver></pre> |
| </source> |
| <p>The following XML lines add the TCPTransport Sender:</p> |
| <source><pre><transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/></pre> |
| </source> |
| |
| <p>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)</p> |
| |
| </body> |
| </html> |
