| <?xml version="1.0" encoding="ISO-8859-1" ?> |
| |
| <!-- |
| ~ 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. |
| --> |
| |
| <document> |
| <properties> |
| <title>Apache Synapse - Transports Catalog</title> |
| </properties> |
| <body> |
| <section name="Transports Catalog" id="Introduction"> |
| <p> |
| 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: |
| </p> |
| <ul> |
| <li> |
| A non blocking HTTP transport that gives better performance in a highly |
| asynchronous environment like Synapse. |
| </li> |
| <li> |
| A VFS transport that can read messages from files and write outgoing messages to |
| a file system. The file system can be local or remote, and several remote |
| protocols are supported, such as FTP, SSH, WebDAV, etc. |
| </li> |
| <li> |
| A transport supporting the |
| <a class="externalLink" href="http://www.fixprotocol.org">Financial Information eXchange</a> |
| protocol. FIX is a public-domain messaging standard developed specifically for |
| the real-time electronic exchange of securities transactions. It has a large user |
| base and is developed by the collaborative effort of banks, broker-dealers, |
| exchanges, industry utilities and associations, institutional investors, and IT |
| providers around the world. |
| </li> |
| </ul> |
| <p>Note that while these transports are developed as part of the Synapse project, |
| they can be used with any Axis2 based application. |
| </p> |
| <p> |
| The Synapse distribution also comes bundled with the following transports from |
| the <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/index.html">Axis2 Transport</a> |
| project: |
| </p> |
| <ul> |
| <li> |
| A |
| <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/jms.html">JMS transport</a> |
| supporting any JMS 1.0 or 1.1 provider. |
| </li> |
| <li> |
| A |
| <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/mail.html">Mail transport</a> |
| able to send messages using SMTP and poll messages from a POP3 or IMAP account. |
| <p> |
| Apache Synapse is also compatible with the following transport implementations |
| from the Apache Axis2 Transports project: |
| </p> |
| </li> |
| <li> |
| <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/tcp-transport.html">TCP transport</a> |
| </li> |
| <li> |
| <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/sms.html">SMS transport</a> |
| </li> |
| <li>UDP transport</li> |
| <li> |
| XMPP transport |
| <p> |
| These transports are not shipped with Apache Synapse by default and hence they |
| should be |
| <a class="externalLink" href="http://axis.apache.org/axis2/java/transports/download.cgi">downloaded separately</a> |
| from the Axis2 transport website and installed in the Synapse runtime. |
| </p> |
| </li> |
| </ul> |
| </section> |
| <section name="Content" id="Content"> |
| <ul> |
| <li> |
| <a href="#Introduction">Introduction</a> |
| </li> |
| <li> |
| <a href="#Contents">Contents</a> |
| </li> |
| <li> |
| <a href="#Non-blocking_HTTP_transport">Non-blocking HTTP transport</a> |
| <ul> |
| <li> |
| <a href="#Example_configurations">Example configurations</a> |
| </li> |
| <li> |
| <a href="#Transport_listener_parameters">Transport listener parameters</a> |
| </li> |
| <li> |
| <a href="#Transport_sender_parameters">Transport sender parameters</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#VFS_transport">VFS transport</a> |
| <ul> |
| <li> |
| <a href="#Transport_listener">Transport listener</a> |
| </li> |
| <li> |
| <a href="#Transport_sender">Transport sender</a> |
| </li> |
| <li> |
| <a href="#Using_SFTP">Using SFTP</a> |
| </li> |
| <li> |
| <a href="#Known_issues">Known issues</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a href="#FIX_transport">FIX transport</a> |
| <ul> |
| <li> |
| <a href="#Setting_up_the_FIX_Transport">Setting up the FIX Transport</a> |
| </li> |
| <li> |
| <a href="#FIX_Transport_Parameters">FIX Transport Parameters</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </section> |
| <section name="Non-blocking HTTP transport" id="Non-blocking_HTTP_transport"> |
| <subsection name="Example configuration" id="Example_configurations"> |
| <div class="xmlConf"><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></div> |
| </subsection> |
| <subsection name="Transport listener parameters" id="Transport_listener_parameters"> |
| <p>The following parameters are supported by both the HTTP and the HTTPS listener:</p> |
| <dl> |
| <dt> |
| <tt>port</tt> |
| </dt> |
| <dd>The TCP port to bind the listener to.</dd> |
| <dt> |
| <tt>bind-address</tt> |
| </dt> |
| <dd> |
| The IP address to bind the listener to. This can be used on hosts that have |
| more than one network interface or IP address to run multiple Synapse instances |
| listening to the same port. If this parameter is not specified, the |
| listener will accept connections on any IP address. |
| </dd> |
| <dt> |
| <tt>hostname</tt> |
| </dt> |
| <dd> |
| The host name to use when computing endpoint references in generated WSDL files. |
| The default value is the host name as provided by the operation system or |
| <tt>localhost</tt> if the host name can't be determined. The value of this |
| parameter is ignored if <tt>WSDLEPRPrefix</tt> is specified. |
| </dd> |
| <dt> |
| <tt>WSDLEPRPrefix</tt> |
| </dt> |
| <dd> |
| The URL prefix to use when computing endpoint references in generated WSDL files. |
| The value must be a valid URL with at least a protocol and host. If this value |
| is unspecified, endpoint references will be computed based on the listener type |
| (HTTP or HTTPS) and <tt>hostname</tt> and <tt>port</tt> parameters. |
| <p> |
| 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 <tt>...?wsdl</tt> URLs. |
| </p> |
| </dd> |
| </dl> |
| <p>The following parameters are specific to the HTTPS listener: </p> |
| <dl> |
| <dt> |
| <tt>keystore</tt> |
| </dt> |
| <dd> |
| The keystore configuration. The value of this parameter must be a |
| <tt><KeyStore></tt> |
| element as shown in the example configurations above. |
| </dd> |
| <dt> |
| <tt>truststore</tt> |
| </dt> |
| <dd> |
| The truststore configuration. The value of this parameter must be a |
| <tt><TrustStore></tt> |
| element as shown in the example configurations above. |
| </dd> |
| <dt> |
| <tt>SSLVerifyClient</tt> |
| </dt> |
| <dd> |
| This parameter has the same meaning as the corresponding |
| <a class="externalLink" href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslverifyclient">mod_ssl directive</a> |
| and sets the desired certificate verification level for client authentication: |
| <ul> |
| <li> |
| <tt>none</tt> (default): no client certificate is required at all |
| </li> |
| <li> |
| <tt>optional</tt>: the client may present a valid certificate, but is |
| not required to do so |
| </li> |
| <li> |
| <tt>require</tt>: the client has to present a valid certificate, |
| otherwise the connection request will be terminated during SSL handshake |
| </li> |
| </ul> |
| </dd> |
| </dl> |
| </subsection> |
| <subsection name="Transport sender parameters" id="Transport_sender_parameters"> |
| <p> |
| 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. |
| </p> |
| <dl> |
| <dt> |
| <tt>warnOnHTTP500</tt> |
| </dt> |
| <dd> |
| A list of content-types for which Synapse shall output a warning when receiving |
| an HTTP 500 response (each value each separated by a |). By default Synapse |
| outputs a warning for any HTTP 500 response, irrespective of the content-type. |
| Consequently, also for each SOAP fault a warning will be logged. If only for |
| specific content-types a warning shall be logged, please provide a |-separated |
| list. To output the warning for messages which do not have a content-type set, |
| please use the value 'none'. |
| <p> |
| Example value: x-application/hessian|none |
| </p> |
| </dd> |
| </dl> |
| <p> |
| 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 |
| <tt><transportSender></tt> or as system properties. |
| </p> |
| <dl> |
| <dt> |
| <tt>http.proxyHost</tt> |
| </dt> |
| <dd>The host name or address of the proxy server.</dd> |
| <dt> |
| <tt>http.proxyPort</tt> |
| </dt> |
| <dd>The TCP port of the proxy server.</dd> |
| <dt> |
| <tt>http.nonProxyHosts</tt> |
| </dt> |
| <dd> |
| The hosts to which the HTTP sender should connect directly and not through |
| the proxy server. The value can be a list of hosts, each separated by a |, and |
| in addition a wildcard character (*) can be used for matching. |
| <p> |
| Example value: |
| <tt>*.foo.com|localhost</tt> |
| </p> |
| </dd> |
| </dl> |
| <p>Note that the HTTPS sender has no proxy support yet.</p> |
| <p>The following parameters are specific to the HTTP sender:</p> |
| <dl> |
| <dt> |
| <tt>keystore</tt> |
| </dt> |
| <dd> |
| The keystore configuration. The value of this parameter must be a |
| <tt><KeyStore></tt> element as shown in the example configurations |
| above. |
| </dd> |
| <dt> |
| <tt>truststore</tt> |
| </dt> |
| <dd> |
| The truststore configuration. The value of this parameter must be a |
| <tt><TrustStore></tt> |
| element as shown in the example configurations above. |
| </dd> |
| <dt> |
| <tt>novalidatecert</tt> |
| </dt> |
| <dd> |
| When set to <tt>true</tt>, this parameter disables server certificate |
| validation (trust). The default value is <tt>false</tt>. This parameter will |
| be ignored if <tt>truststore</tt> is set. |
| <p> |
| Setting his parameter to <tt>true</tt> |
| 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. |
| </p> |
| </dd> |
| <dt> |
| <tt>HostnameVerifier</tt> |
| </dt> |
| <dd> |
| This optional parameter specifies the policy to apply when checking that the |
| hostname of the server matches the names stored inside the X.509 certificate |
| presented by the server. Possible values are <tt>Strict</tt>, <tt>AllowAll</tt> |
| and <tt>DefaultAndLocalhost</tt>. See the |
| <a href="../apidocs/org/apache/synapse/transport/nhttp/HostnameVerifier.html">HostnameVerifier Javadoc</a> |
| for more details. |
| </dd> |
| </dl> |
| </subsection> |
| </section> |
| <section name="VFS transport" id="VFS_transport"> |
| <subsection name="Transport listener" id="Transport_listener"> |
| |
| <p> |
| 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. |
| </p> |
| <p> |
| The transport is based on |
| <a class="externalLink" href="http://commons.apache.org/vfs/">Apache Commons VFS</a> |
| and supports any protocol for which a VFS provider is available. The transport is |
| pre-configured with providers for local files ( |
| <tt>file:</tt> |
| scheme), HTTP, HTTPS, FTP and SFTP (i.e. file transfer over SSH). |
| </p> |
| <p> |
| 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. |
| </p> |
| <p>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: |
| </p> |
| <div class="xmlConf"><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></div> |
| <p> |
| In this example the file system location |
| <tt>file:///var/spool/synapse/in</tt> |
| is explicitly bound to |
| <tt>MyVFSService</tt> |
| , 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. |
| </p> |
| <p>The VFS transport recognizes the following service parameters:</p> |
| <dl> |
| <dt> |
| <tt>transport.vfs.FileURI</tt>(Required) |
| </dt> |
| <dd> |
| The primary File (or Directory) URI in the vfs* transport format, for this |
| service |
| </dd> |
| <dt> |
| <tt>transport.vfs.ContentType</tt> (Required) |
| </dt> |
| <dd> |
| The expected content type for files retrieved for this service. The VFS |
| transport uses this information to select the appropriate message builder. |
| <p>Examples:</p> |
| <ul> |
| <li> |
| <tt>text/xml</tt> for plain XML or SOAP |
| </li> |
| <li> |
| <tt>text/plain; charset=ISO-8859-1</tt> for text files |
| </li> |
| <li> |
| <tt>application/octet-stream</tt> for binary data |
| </li> |
| </ul> |
| </dd> |
| <dt> |
| <tt>transport.vfs.FileNamePattern</tt> |
| (Optional) |
| </dt> |
| <dd> |
| A file name regex pattern to match files against a directory specified by |
| the FileURI |
| </dd> |
| <dt> |
| <tt>transport.PollInterval</tt> (Optional) |
| </dt> |
| <dd> The poll interval (in seconds)</dd> |
| <dt> |
| <tt>transport.vfs.ActionAfterProcess</tt> (Optional) |
| </dt> |
| <dd> DELETE or MOVE</dd> |
| <dt> |
| <tt>transport.vfs.MoveAfterProcess</tt> (Optional) |
| </dt> |
| <dd> |
| The directory to move files after processing (i.e. all files process |
| successfully) |
| </dd> |
| <dt> |
| <tt>transport.vfs.ActionAfterErrors</tt> (Optional) |
| </dt> |
| <dd> DELETE or MOVE</dd> |
| <dt> |
| <tt>transport.vfs.MoveAfterErrors</tt> (Optional) |
| </dt> |
| <dd> |
| The directory to move files after errors (i.e. some of the files succeed |
| but some fail) |
| </dd> |
| <dt> |
| <tt>transport.vfs.ActionAfterFailure</tt> (Optional) |
| </dt> |
| <dd> DELETE or MOVE</dd> |
| <dt> |
| <tt>transport.vfs.MoveAfterFailure</tt> (Optional) |
| </dt> |
| <dd> The directory to move after failure (i.e. all files fail)</dd> |
| <dt> |
| <tt>transport.vfs.ReplyFileURI</tt> (Optional) |
| </dt> |
| <dd> Reply file URI</dd> |
| <dt> |
| <tt>transport.vfs.ReplyFileName</tt> (Optional) |
| </dt> |
| <dd> Reply file name (defaults to response.xml)</dd> |
| <dt> |
| <tt>transport.vfs.MoveTimestampFormat</tt> (Optional) |
| </dt> |
| <dd> |
| Timestamp prefix format for processed file name. java.text.SimpleDateFormat |
| compatible string. e.g. yyMMddHHmmss'-' |
| </dd> |
| <dt> |
| <tt>transport.vfs.Locking</tt> (Optional) |
| </dt> |
| <dd> |
| By-default file locking is turned on in the VFS transport, and this parameter |
| lets you configure the locking behaviour on a per service basis. Possible values are |
| <tt>enable</tt> or <tt>disable</tt>, and both these values are important because |
| the locking can be disabled at the global level by specifying that at the |
| receiver level and selectively enable locking only for a set of services. |
| </dd> |
| <dt> |
| <tt>transport.vfs.Streaming</tt> (Optional) |
| </dt> |
| <dd> |
| If this parameter is set to <tt>true</tt>, the transport will attempt to use a |
| <tt>javax.activation.DataSource</tt> (instead of a <tt>java.io.InputStream</tt> |
| ) object to pass the content of the file to the message builder. Note that this |
| is only supported by some message builders, e.g. for plain text and binary. |
| <p> |
| This allows processing of the message without storing the entire content |
| in memory. It also has two other side effects: |
| </p> |
| <ul> |
| <li> |
| The incoming file (or connection in case of a remote file) will only |
| be opened on demand. |
| </li> |
| <li> |
| Since the data is not cached, the file might be read several times. |
| </li> |
| </ul> |
| <p> |
| 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. |
| </p> |
| </dd> |
| </dl> |
| <p> |
| 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 which is optional and the transport listener is enabled in |
| <tt>axis2.xml</tt> |
| simply as follows: |
| </p> |
| <div class="xmlConf"><transportReceiver name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportListener"> |
| <parameter name="transport.vfs.Locking">enable | disable</parameter> ? |
| </transportReceiver></div> |
| </subsection> |
| <subsection name="Transport sender" id="Transport_sender"> |
| <p> |
| 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. |
| </p> |
| <p> |
| The sender is enabled be the following directive in |
| <tt>axis2.xml</tt> file locking which is by-default enabled can be configured |
| using the <tt>transport.vfs.Locking</tt> parameter: |
| </p> |
| <div class="xmlConf"><transportSender name="vfs" class="org.apache.synapse.transport.vfs.VFSTransportSender"> |
| <parameter name="transport.vfs.Locking">enable | disable</parameter> ? |
| </transportSender></div> |
| <p> |
| To send a message using the VFS transport, the destination URI must start with |
| <tt>vfs:</tt> followed by a valid VFS URL. For example, in a Synapse mediation, |
| one would use: |
| </p> |
| <div class="xmlConf"><endpoint> |
| <address uri="vfs:file:///var/spool/synapse/out"/> |
| </endpoint></div> |
| <p> |
| Other examples of valid VFS URLs are (see |
| <a class="externalLink" href="http://commons.apache.org/vfs/filesystems.html">http://commons.apache.org/vfs/filesystems.html</a> |
| for more samples): |
| </p> |
| <ul> |
| <li> |
| <tt>file:///directory/filename.ext</tt> |
| </li> |
| <li> |
| <tt>file:////somehost/someshare/afile.txt</tt> |
| </li> |
| <li> |
| <tt>jar:../lib/classes.jar!/META-INF/manifest.mf</tt> |
| </li> |
| <li> |
| <tt>jar:zip:outer.zip!/nested.jar!/somedir</tt> |
| </li> |
| <li> |
| <tt>ftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz[?vfs.passive=true]</tt> |
| </li> |
| </ul> |
| <p> |
| The global configuration of the file locking can be overriden by providing the |
| <tt>transport.vfs.Locking</tt> as a URL parameter with the appropriate value ( |
| <tt>enable</tt>, or <tt>disable</tt>) on a given endpoint. |
| </p> |
| <p> |
| 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: |
| </p> |
| <div class="xmlConf"><property action="set" name="OUT_ONLY" value="true"/></div> |
| </subsection> |
| <subsection name="Using SFTP" id="Using_SFTP"> |
| <p> |
| 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. |
| </p> |
| <p> |
| The VFS transports supports SFTP through the |
| <a class="externalLink" href="http://www.jcraft.com/jsch/">JSch</a> |
| 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. |
| </p> |
| <p> |
| Jsch loads the list of known hosts from a file called <tt>known_hosts</tt> in |
| the <tt>.ssh</tt> sub-directory of the user's home directory, i.e. <tt>$HOME/.ssh</tt> |
| in Unix and <tt>%HOMEPATH%\.ssh</tt> in Windows. The location and format of this |
| file are compatible with the <a class="externalLink" href="http://www.openssh.com/">OpenSSH</a> |
| client. |
| </p> |
| <p> |
| Since the file not only contains a list of host names 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 <tt>known_hosts</tt> 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 <tt>known_hosts</tt> file, this error can be ignored. |
| </p> |
| </subsection> |
| <subsection name="Known issues" id="Known_issues"> |
| <p> |
| 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. |
| </p> |
| <p> |
| It should also be noted that the VFS transport sender doesn't create files atomically. |
| </p> |
| </subsection> |
| </section> |
| <section name="FIX transport" id="FIX_transport"> |
| <p>A general overview about the FIX transport can be found in the following articles:</p> |
| <ul> |
| <li> |
| <a class="externalLink" href="http://wso2.org/library/3449">Apache Synapse FIX'ed</a> |
| </li> |
| <li> |
| <a class="externalLink" href="http://wso2.org/library/3837">Using the WSO2 ESB and FIX</a> |
| (also applies to Synapse) |
| </li> |
| </ul> |
| <subsection name="Setting up the FIX Transport" id="Setting_up_the_FIX_Transport"> |
| <p> |
| To use the FIX transport, you need a local |
| <a class="externalLink" href="http://www.quickfixj.org">Quickfix/J</a> |
| installation. Download Quickfix/J from |
| <a class="externalLink" href="http://www.quickfixj.org/downloads">http://www.quickfixj.org/downloads</a> |
| . |
| </p> |
| <p> |
| 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). |
| </p> |
| <ul> |
| <li>quickfixj-core.jar</li> |
| <li>quickfixj-msg-fix40.jar</li> |
| <li>quickfixj-msg-fix41.jar</li> |
| <li>quickfixj-msg-fix42.jar</li> |
| <li>quickfixj-msg-fix43.jar</li> |
| <li>quickfixj-msg-fix44.jar</li> |
| <li>mina-core.jar</li> |
| <li>slf4j-api.jar</li> |
| <li>slf4j-jdk14.jar</li> |
| </ul> |
| <p>All these jars are shipped with the Quickfix/J binary distribution.</p> |
| </subsection> |
| <subsection name="FIX Transport Parameters" id="FIX_Transport_Parameters"> |
| <p> |
| 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. |
| </p> |
| <dl> |
| <dt> |
| <tt>transport.fix.AcceptorConfigURL</tt> |
| </dt> |
| <dd> |
| If a service needs to listen to incoming FIX messages from a remote initiator |
| then Synapse needs to create an acceptor. This parameter should contain the |
| URL of the file which contains the FIX configuration for the acceptor. |
| (See sample 257) |
| </dd> |
| <dt> |
| <tt>transport.fix.InitiatorConfigURL</tt> |
| </dt> |
| <dd> |
| If a service needs to send FIX messages to a remote acceptor Synapse should |
| create an initiator. This parameter should contain the URL of the file which |
| contains the FIX configuration for the initiator. (See sample 257) |
| </dd> |
| <dt> |
| <tt>transport.fix.AcceptorMessageStore</tt> |
| </dt> |
| <dd> |
| The type of message store to be used with the acceptor. Allowed values for |
| this parameter are 'file', 'jdbc', 'memory' and 'sleepycat'. If not specified |
| memory based message store will be used by default. Additional parameters |
| required to configure each of the message stores should be specified in the |
| acceptor configuration file. |
| </dd> |
| <dt> |
| <tt>transport.fix.InitiatorMessageStore</tt> |
| </dt> |
| <dd> |
| Same as the above but applies only for the initiators. Additional parameters |
| required to configure each of the message stores should be specified in the |
| initiator configuration file. |
| </dd> |
| <dt> |
| <tt>transport.fix.AcceptorLogFactory</tt> |
| </dt> |
| <dd> |
| Specifies the transport level log factory to be used to log messages going |
| through the acceptor. FIX messages are logged without putting them in SOAP |
| envelopes at this level. Accepted values are 'console', 'file' and 'jdbc'. |
| If not specified no logging will be done at the transport level. Additional |
| parameters required to configure each of the lof factories should be specified |
| in the acceptor configuration file. |
| </dd> |
| <dt> |
| <tt>transport.fix.InitiatorLogFactory</tt> |
| </dt> |
| <dd> |
| Specifies the transport level log factory to be used to log messages going |
| through the initiator. Functionality is similar to the above. Additional |
| parameters required to configure each of the lof factories should be specified |
| in the initiator configuration file. |
| </dd> |
| <dt> |
| <tt>transport.fix.ResponseDeliverToCompID</tt> |
| </dt> |
| <dd> |
| If a response FIX message sent from Synapse to a remote FIX engine should be |
| forwarded from the remote engine to another party this parameter can be used |
| to set the DeliverToCompID field of the messages at Synapse. |
| </dd> |
| <dt> |
| <tt>transport.fix.ResponseDeliverToSubID</tt> |
| </dt> |
| <dd> |
| If a response FIX message sent from Synapse to a remote FIX engine should be |
| forwarded from the remote engine to another party this parameter can be used |
| to set the DeliverToSubID field of the messages at Synapse. |
| </dd> |
| <dt> |
| <tt>transport.fix.ResponseDeliverToLocationID</tt> |
| </dt> |
| <dd> |
| If a response FIX message sent from Synapse to a remote FIX engine should be |
| forwarded from the remote engine to another party this parameter can be used |
| to set the DeliverToLocationID field of the messages at Synapse. |
| </dd> |
| <dt> |
| <tt>transport.fix.ServiceName</tt> |
| </dt> |
| <dd> |
| Used when messages coming over a different protocol has to be forwarded over |
| FIX. The value must be equal to the name of the service and the scope must be |
| 'axis2-client' (See sample 258) |
| </dd> |
| <dt> |
| <tt>transport.fix.SendAllToInSequence</tt> |
| </dt> |
| <dd> |
| When there are multiple responses to a FIX request and when we need only one |
| of them to be sent to the original requester this parameter has to be set to |
| 'false'. This mostly comes handy when the original requester is communicating |
| over a different protocol (like HTTP). If this parameter is not set to 'false' |
| at such scenarios messages might get into a loop. (See sample 258) |
| </dd> |
| <dt> |
| <tt>transport.fix.BeginStringValidation</tt> |
| </dt> |
| <dd> |
| When the FIX messages sent to Synapse should not be forwarded to a FIX session |
| with a different BeginString value this parameter can be set to 'true'. Setting |
| this parameter to 'true' will enforce this restriction. |
| </dd> |
| </dl> |
| </subsection> |
| </section> |
| |
| </body> |
| </document> |
