/*
* 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.
*/
/**
* Transport implementation for the UDP protocol.
* <p>
* This package contains a transport implementation allowing Axis to
* send and receive UDP packets. It is an implementation of "raw" UDP in the
* sense that the message is directly extracted from the UDP payload without
* any intermediate application protocol. This has several important implications:
* <ul>
* <li>The only way to route the incoming message to the appropriate Axis service
* is to bind the service a specific UDP port. The port number must be
* explicitly defined in the service configuration. This is different
* from protocols such as HTTP where the message can be routed
* based on the URL in the request.</li>
* <li>The transport has no way to detect the content type of an incoming
* message. Indeed, there is no equivalent to HTTP's
* <tt>Content-Type</tt> header. Again the expected content type must be
* configured explicitly for the service.</li>
* <li>Since UDP doesn't provide any mean to correlate responses to requests,
* the transport can only be used for asynchronous communication.</li>
* </ul>
* See the documentation of {@link org.apache.synapse.transport.udp.UDPListener}
* for more information about how to configure a service to accept UDP packets.
* Endpoint references for the UDP transport are assumed to follow the following
* syntax:
* <pre>
* udp://<em>host</em>:<em>port</em>?contentType=...</pre>
* <p>
* The UDP transport can be enabled in the Axis configuration as follows:
* <pre>
* <transportReceiver name="udp" class="org.apache.synapse.transport.udp.UDPListener"/>
* <transportSender name="udp" class="org.apache.synapse.transport.udp.UDPSender"/></pre>
* It should be noted that given its characteristics, UDP is not a
* suitable transport protocol for SOAP, except maybe in very particular
* circumstances. Indeed, UDP is an unreliable protocol:
* <ul>
* <li>There is no delivery guarantee, i.e. packets may be lost.</li>
* <li>Messages may arrive out of order.</li>
* <li>Messages may be duplicated, i.e. delivered twice.</li>
* </ul>
* However the unit tests show an example of how to use this transport with SOAP
* and WS-Addressing to achieve two-way asynchronous communication.
* Note that the transport has not been designed to implement the
* <a href="http://specs.xmlsoap.org/ws/2004/09/soap-over-udp/soap-over-udp.pdf">SOAP
* over UDP specification</a> and will probably not be interoperable.
* <p>
* The main purpose of this transport implementation is to integrate Axis (and in
* particular Synapse) with existing UDP based protocols. See
* {@link org.apache.synapse.format.syslog} for an example of this kind
* of protocol.
*
* <h4>Known issues and limitations</h4>
*
* <ul>
* <li>Packets longer than the configured maximum packet size
* are silently truncated. Packet truncation should be detected
* and trigger an error.</li>
* <li>The listener doesn't implement all management operations
* specified by
* {@link org.apache.synapse.transport.base.ManagementSupport}.</li>
* <li>The listener assumes that services are bound to unique UDP ports
* and predispatches incoming requests based on port numbers.
* When SOAP with WS-Addressing is used, the packets could be
* received on a single port and dispatched based on the <tt>To</tt>
* header. This is not supported.</li>
* <li>It might be useful to allow configuration of the content type at the
* transport level rather than the service level. In this case, the
* <tt>contentType</tt> parameter would not be included in the endpoint
* reference. This is necessary for interoperability with the SOAP over UDP
* standard.</li>
* <li>Technically, it would be quite easy to support binding several UDP ports
* to the same service. However, the way endpoints are configured
* at the service level doesn't allow this for the moment. Indeed,
* using simple text properties only allows to specify the configuration
* of a single endpoint.</li>
* <li>The transport sender uses a randomly chosen UDP source port. Some
* UDP based services may check the source port and discard the packet.
* Also, in two-way communication scenarios, stateful firewalls will
* not be able to correlate the exchanged packets and may drop
* some of them.</li>
* </ul>
*/
package org.apache.axis2.transport.udp;