The Synapse project has developed a set of transport implementations that provide protocol support and/or features that go beyond what is provided out of the box by Axis2:
Note that while these transports are developed as part of the Synapse project, they can be used with any Axis2 based application.
The Synapse distribution also comes bundled with the following transports from the Axis2 Transport project:
Apache Synapse is also compatible with the following transport implementations from the Apache Axis2 Transports project:
These transports are not shipped with Apache Synapse by default and hence they should be downloaded separately from the Axis2 transport website and installed in the Synapse runtime.
<transportReceiver name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOListener">
<parameter name="port">8280</parameter>
<parameter name="non-blocking">true</parameter>
</transportReceiver>
<transportReceiver name="https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLListener">
<parameter name="port" locked="false">8243</parameter>
<parameter name="non-blocking" locked="false">true</parameter>
<parameter name="keystore" locked="false">
<KeyStore>
<Location>lib/identity.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
</parameter>
<parameter name="truststore" locked="false">
<TrustStore>
<Location>lib/trust.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</parameter>
</transportReceiver>
<transportSender name="http" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSender">
<parameter name="non-blocking" locked="false">true</parameter>
<parameter name="warnOnHTTP500" locked="false">*</parameter>
</transportSender>
<transportSender name="https" class="org.apache.synapse.transport.nhttp.HttpCoreNIOSSLSender">
<parameter name="non-blocking" locked="false">true</parameter>
<parameter name="warnOnHTTP500" locked="false">*</parameter>
<parameter name="keystore" locked="false">
<KeyStore>
<Location>lib/identity.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
<KeyPassword>password</KeyPassword>
</KeyStore>
</parameter>
<parameter name="truststore" locked="false">
<TrustStore>
<Location>lib/trust.jks</Location>
<Type>JKS</Type>
<Password>password</Password>
</TrustStore>
</parameter>
</transportSender>
The following parameters are supported by both the HTTP and the HTTPS listener:
This parameter should be used if clients connect to Synapse through a frontend server, e.g. a (load balancing) Apache, and these clients rely on the address information in the WSDL documents exposed through ...?wsdl URLs.
The following parameters are specific to the HTTPS listener:
The following property can be used to control based on content-types whether the HTTP/HTTPS sender shall output a warning for responses with HTTP status code 500.
Example value: x-application/hessian|none
The following properties can be used to configure the HTTP sender to use a proxy. They can be specified either as transport parameters in declared in <transportSender> or as system properties.
Example value: *.foo.com|localhost
Note that the HTTPS sender has no proxy support yet.
The following parameters are specific to the HTTP sender:
Setting his parameter to true is useful in development and test environments, but should not be used in production environments. If validation is disabled, a warning message will be logged at startup.
The VFS transport listener receives messages dropped in a given local or remote file system location. The location is specified by a URL that either identifies a single file or a directory. The transport listener will periodically poll the specified location and process any file(s) found. After a file has been processed it will be deleted or moved to another location. Note that this is absolutely mandatory to prevent the listener from processing files multiple times. Therefore the VFS transport listener can only be used in situations where it has write access to the file system location and where deleting or moving the dropped files is acceptable.
The transport is based on Apache Commons VFS and supports any protocol for which a VFS provider is available. The transport is preconfigured with providers for local files (file: scheme), HTTP, HTTPS, FTP and SFTP (i.e. file transfer over SSH).
There is a fundamental difference between the VFS transport and transports such as HTTP and it is important to understand this difference to be able to use the VFS transport correctly. The HTTP transport binds to a single protocol endpoint, i.e. a TCP port on which it accepts incoming HTTP requests. These requests are then dispatched to the right service based on the request URI. On the other hand, the VFS transport only receives the payload of a message, but no additional information that could be used to dispatch the message to a service. This means that file system locations must be explicitly mapped to services. This is done using a set of service parameters.
For Synapse this means that the VFS transport listener can only be used in conjunction with proxy services. The relevant service parameters are then specified as follows:
<proxy name="MyVFSService" transports="vfs">
<parameter name="transport.vfs.FileURI">file:///var/spool/synapse/in</parameter>
<parameter name="transport.vfs.ContentType">application/xml</parameter>
...
<target>
...
</target>
</proxy>
In this example the file system location file:///var/spool/synapse/in is explicitly bound to MyVFSService , i.e. any message dropped in that location will be predispatched to that service, bypassing any other configured dispatch mechanisms that would apply to messages received through HTTP.
The VFS transport recognizes the following service parameters:
Examples:
This allows processing of the message without storing the entire content in memory. It also has two other side effects:
This option can be used to achieve streaming of large payloads. Note that this feature is still somewhat experimental and might be superseded by a more flexible mechanism in a future release.
Note that since the VFS endpoints are configured at the level of the service, the only parameter that is available at the listener is the file locking configuration parameter whcih is optional and the transport listener is enabled in axis2.xml simply as follows:
<transportReceiver name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportListener">
<parameter name="transport.vfs.Locking">enable | disable</parameter> ?
</transportReceiver>
The VFS transport sender allows to write outgoing messages to local or remote files. As with the listener, the transport sender supports any protocol for which there is a VFS provider.
The sender is enabled be the following directive in axis2.xml file locking which is by-default enabled can be configured using the transport.vfs.Locking parameter:
<transportSender name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportSender">
<parameter name="transport.vfs.Locking">enable | disable</parameter> ?
</transportSender>
To send a message using the VFS transport, the destination URI must start with vfs: followed by a valid VFS URL. For example, in a Synapse mediation, one would use:
<endpoint>
<address uri="vfs:file:///var/spool/synapse/out"/>
</endpoint>
Other examples of valid VFS URLs are (see http://commons.apache.org/vfs/filesystems.html for more samples):
The global configuration of the file locking can be overriden by providing the transport.vfs.Locking as a URL parameter with the appropriate value (enable , or disable ) on a given endpoint.
It should be noted that by its nature, the VFS transport sender doesn't support synchronous responses and should only be invoked using the out-only message exchange pattern. In a Synapse mediation, this can be forced using the following mediator:
<property action="set" name="OUT_ONLY" value="true"/>
To avoid man-in-the-middle attacks, SSH clients will only connect to hosts with a known host key. When connecting for the first time to an SSH server, a typical command line SSH client would request confirmation from the user to add the server and its fingerprint to the list of known hosts.
The VFS transports supports SFTP through the JSch library and this library also requires a list of known hosts. Since Synapse is not an interactive process, it can't request confirmation from the user and is therefore unable to automatically add a host to the list. This implies that the list of known hosts must be set up manually before the transport can connect.
Jsch loads the list of known hosts from a file called known_hosts in the .ssh subdirectory of the user's home directory, i.e. $HOME/.ssh in Unix and %HOMEPATH%\.ssh in Windows. The location and format of this file are compatible with the OpenSSH client.
Since the file not only contains a list of hostnames but also the fingerprints of their host keys, the easiest way to add a new host to that file is to simply use the OpenSSH client to open an SSH session on the target host. The client will then ask to add the credentials to the known_hosts file. Note that if the SSH server is configured to only allow SFTP sessions, but no interactive sessions, the connection will actually fail. Since this doesn't rollback the change to the known_hosts file, this error can be ignored.
The VFS listener will start reading a file as soon as it appears in the configured location. To avoid processing half written files, the creation of these files should be made atomic. On most platforms this can be achieved by writing the data to a temporary file and then moving the file to the target location. Note however that a move operation is only atomic if the source and destination are on the same physical file system. The location for the temporary file should be chosen with that constraint in mind.
It should also be noted that the VFS transport sender doesn't create files atomically.
A general overview about the FIX transport can be found in the following articles:
To use the FIX transport, you need a local Quickfix/J installation. Download Quickfix/J from http://www.quickfixj.org/downloads .
To enable the FIX transport, you need to uncomment the FIX transport sender and FIX transport receiver configurations in the SYNAPSE_HOME/repository/conf/axis2.xml. Simply locate and uncomment the FIXTransportSender and FIXTransportListener sample configurations. Also add the following jars to the Synapse class path (SYNAPSE_HOME/lib directory).
All these jars are shipped with the Quickfix/J binary distribution.
This is the list of all parameters accepted by the FIX transport. Refer the sample 257 and 258 to see how some of them are used in practice.