src/site/apt/docs/tcp-transport.apt

~~ 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

* {Content}

%{toc|section=1|fromDepth=1}

* {Transport listener}

** {Listener configuration}

  The TCP transport listener is configured in <<<axis2.xml>>> using the following declaration:

+----------------------------+
<transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportListener"/>
+----------------------------+

  Depending on how the TCP transport is set up, additional parameters may be required inside the
  <<<transportReceiver>>> element (see next section).

** {Endpoint configuration}

  Endpoints can be configured both at the transport level and at the service level. Each endpoint
  opens a TCP server socket for listening. TCP requests received on a port that is configured on a
  service will be pre-dispatched to that service. Packets received by a port that is configured
  at the transport level need to be dispatched using one of the following mechanisms:

  [[1]] Using the namespace URI of the first child element of SOAPBody
  (SOAPMessageBodyBasedDispatcher).

  [[2]] Using WS-Addressing headers (SOAPActionBasedDispatcher).

  Endpoints are configured by adding <<<parameter>>> elements to the <<<transportReceiver>>>
  element in <<<axis2.xml>>> or to a <<<service>>> element in an <<<services.xml>>> file. The
  set of parameters is the same for both scenarios:

  [<<<transport.tcp.port>>> (required)]
  The port number over which the TCP server socket should be opened.

  [<<<transport.tcp.hostname>>> (optional)]
  The hostname to which the TCP server socket should be bound.

  [<<<transport.tcp.contentType>>> (optional, defaults to text/xml)]
  Specifies the content type of the messages received on the endpoint.

  [<<<transport.tcp.backlog>>> (optional, defaults to 50)]
  The length of the backlog (queue) supported by the TCP server socket.

* {Transport sender}

  The TCP transport sender can be enabled in <<<axis2.xml>>> using the following declaration:

+----------------------------+
<transportSender name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportSender"/>
+----------------------------+

* {Examples}

** {Enabling TCP listener at the transport level}

  The following declaration in <<<axis2.xml>>> initializes a TCP server socket on port 6060
  and allows all services (for which TCP is in the list of exposed transports) to receive
  messages over that port:

+----------------------------+
<transportReceiver name="tcp" class="org.apache.axis2.transport.tcp.TCPTransportListener">
  <parameter name="transport.tcp.port">6060</parameter>
</transportReceiver>
+----------------------------+

  For this to work, WS-Addressing must be enabled, and messages sent to port 6060 must
  have the relevant WS-Addressing headers.

+----------------------------+
<module ref="addressing"/>
+----------------------------+

  With the configuration shown above, the TCP transport would generate bindings with the
  following EPR:

+----------------------------+
tcp://localhost:6060/services/Version?contentType=text/xml
+----------------------------+

  Similar EPRs will be generated for services when the transport is configured at service
  level.

  The following example shows a message that can be sent to the Version service over TCP:

+----------------------------+
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:wsa="http://www.w3.org/2005/08/addressing">
    <SOAP-ENV:Header>
        <wsa:MessageID>1234</wsa:MessageID>
        <wsa:To>tcp://localhost:6060/services/Version?contentType=text/xml</wsa:To>
        <wsa:Action>urn:getVersion</wsa:Action>
    </SOAP-ENV:Header>
    <SOAP-ENV:Body>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
+----------------------------+

  Axis2 client API can be used to easily send TCP requests to a remote service.
  The following code snippet shows how to do that. The TCP transport sender
  must be enabled in the <<axis2.xml>> in order for this to work.

+------------------------------------------------------+

String url = "tcp://localhost:6060/services/Version?contentType=text/xml";
OMElement payload = ...

ServiceClient serviceClient = new ServiceClient();
Options options = new Options();
EndpointReference targetEPR = new EndpointReference(url);
options.setTo(targetEPR);
serviceClient.setOptions(options);
OMElement response = serviceClient.sendReceive(payload);
+------------------------------------------------------+

  The transport sender 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 parameter is of the type OMElement, the XML representation of Axis2.

  A TCP URL may contain an optional timeout value, as a query parameter, to
  indicate how long (in milliseconds) the client should wait for a response.
  Once this period has expired, the client TCP socket will timeout:

+----------------------------+
tcp://localhost:6060/services/Version?contentType=text/xml&timeout=10000
+----------------------------+

  If the Axis2 client API is used to send a request to the above URL, the client
  socket will timeout after waiting for 10 seconds, for the response.