<!--
  ~ 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>&lt;transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPServer"&gt;
    &lt;parameter name="port"&gt;6060&lt;/parameter&gt;
&lt;/transportReceiver&gt;</pre>
</source>
<p>The following XML lines add the TCPTransport Sender:</p>
<source><pre>&lt;transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/&gt;</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>