Author: hiranya
Date: Mon Aug 19 23:40:26 2013
New Revision: 1515668
URL: http://svn.apache.org/r1515668
Log:
Transport documentation update
Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/fix.xml
Modified:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml
Added:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/fix.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/fix.xml?rev=1515668&view=auto
==============================================================================
---
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/fix.xml
(added)
+++
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/fix.xml
Mon Aug 19 23:40:26 2013
@@ -0,0 +1,483 @@
+<?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 - Financial Information eXchange
Transport</title>
+ </properties>
+ <body>
+ <section name="Financial Information eXchange (FIX) Transport"
id="Contents">
+ <ul>
+ <li>
+ <a href="#Introduction">Introduction</a>
+ </li>
+ <li>
+ <a href="#Configuration">Transport Configuration</a>
+ <ul>
+ <li><a href="#Listener">FIX Transport Listener</a></li>
+ <li><a href="#Sender">FIX Transport Sender</a></li>
+ </ul>
+ </li>
+ </ul>
+ </section>
+ <section name="Introduction" id="Introduction">
+ <p>
+ <a href="http://www.fixtradingcommunity.org";>FIX</a> is a
public-domain messaging
+ standard developed specifically for the real-time electronic
exchange of securities
+ transactions. It has a large user base, and the protocol
specifications are
+ developed by the collaborative effort of banks,
broker-dealers, exchanges, industry
+ utilities, institutional investors, and IT providers around
the world.
+ </p>
+ <p>
+ The FIX protocol specifications can be divided into two
sections - the FIX session
+ protocol and the FIX application protocol. The session
protocol is concerned with
+ the delivery of data, while the application protocol defines
business-related data
+ content.
+ </p>
+ <p>
+ Apache Synapse supports sending and receiving FIX messages via
its FIX transport.
+ This transport is based on <a
href="http://www.quickfixj.org";>Quickfix/J</a>, a
+ popular open source library used to develop applications based
on the FIX protocol.
+ The FIX transport enables Synapse to operate as both a FIX
acceptor and a FIX
+ initiator. If you have some prior experience working with
Quickfix/J, you will realize
+ that most of the features and configuration options available
in Quickfix/J are
+ applicable to the Synapse FIX transport as well.
+ </p>
+ <p>
+ To learn more about the FIX protocol and the Synapse FIX
transport, please refer
+ 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>
+ </section>
+ <section name="Transport Configuration" id="Configuration">
+ <p>
+ Synapse binary distribution does not contain the Quickfix/J
libraries. To use the
+ FIX transport, you must <a
href="http://www.quickfixj.org/downloads/";>download Quickfix/J</a>
+ separately, and deploy the necessary jar files into the
Synapse installation. We
+ recommend using Quickfix/J 1.4.0 with Synapse. Copy the
following jar files from the
+ Quickfix/J binary distribution to the
<strong>SYNAPSE_HOME/lib</strong> 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>
+ Similar to the <a href="vfs.html">file transport</a>, the FIX
transport is also mostly
+ configured at the proxy service and endpoint level. To receive
FIX messages, we
+ expose a proxy service over the FIX transport, and specify the
FIX connection settings
+ as proxy service parameters. To send FIX messages, we define
an address endpoint
+ with a URL containing the FIX connection settings.
+ </p>
+ <subsection name="FIX Transport Listener" id="Listener">
+ <p>
+ FIX transport listener enables Synapse to receive FIX
messages from remote
+ applications. Synapse may operate as a FIX acceptor or as
an initiator
+ when receiving FIX messages. To enable the FIX transport
listener, uncomment
+ the following transport receiver configuration in the
<strong>SYNAPSE_HOME/repository/conf/axis2.xml</strong>
+ file.
+ </p>
+ <div class="xmlConf"><transportReceiver name="fix"
class="org.apache.synapse.transport.fix.FIXTransportListener">
+ <parameter name="non-blocking">true</parameter>
+</transportReceiver></div>
+ <p>
+ Now you may expose proxy services over the FIX transport
by setting the "transports"
+ attribute on the proxy service element to "fix":
+ </p>
+ <div class="xmlConf"><proxy name="MyFIXService"
transports="fix">
+...
+</proxy></div>
+ <p>
+ It's also possible to expose a proxy service on FIX
transport and several other
+ transports. Simply specify the required transports as a
space-separated list in
+ the "transports" attribute:
+ </p>
+ <div class="xmlConf"><proxy name="MyFIXService"
transports="fix http https">
+...
+</proxy></div>
+ <p>
+ Exposing a proxy service over FIX is not sufficient. We
must configure the proxy
+ service with FIX session and connection details. This is
done by setting
+ a number of parameters on the proxy service configuration.
Please refer <a href="../samples/sample257.html">sample 257</a>
+ for an example that demonstrates how this is done.
Following table lists all the
+ FIX-specific parameters that can be set on a Synapse proxy
service.
+ </p>
+ <table>
+ <tr>
+ <th>Parameter Name</th>
+ <th>Description/Example</th>
+ <th>Required</th>
+ <th>Default</th>
+ </tr>
+ <tr>
+ <td>transport.fix.AcceptorConfigURL</td>
+ <td>
+ If a proxy service wishes to listen to incoming
FIX messages from a remote
+ initiator, then Synapse needs to start a FIX
acceptor. This parameter
+ specifies the URL to a file, which contains the
FIX configuration
+ for the acceptor. The URL may point to a file in
the local file system
+ or a remotely hosted file accessible over a
standard protocol such as HTTP.
+ The file itself should be a standard <a
href="http://www.quickfixj.org/quickfixj/usermanual/1.4.0/usage/configuration.html#Sample%20Settings%20File";>.cfg
file</a>,
+ typically used to
+ configure FIX acceptors in Quickfix/J. Parameter
is required if the proxy
+ service should receive FIX traffic as an acceptor.
+ <div class="xmlConf"><parameter
name="transport.fix.AcceptorConfigURL">file:conf/acceptor.cfg</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>transport.fix.InitiatorConfigURL</td>
+ <td>
+ If a proxy service wishes to listen to incoming
FIX messages from a remote
+ acceptor, then Synapse needs to start a FIX
initiator. This parameter
+ specifies the URL to a file, which contains the
FIX configuration
+ for the initiator. The URL may point to a file in
the local file system
+ or a remotely hosted file accessible over a
standard protocol such as HTTP.
+ The file itself should be a standard <a
href="http://www.quickfixj.org/quickfixj/usermanual/1.4.0/usage/configuration.html#Sample%20Settings%20File";>.cfg
file</a>,
+ typically used to
+ configure FIX initiators in Quickfix/J. Parameter
is required if the proxy
+ service should receive FIX traffic as an initiator.
+ <div class="xmlConf"><parameter
name="transport.fix.InitiatorConfigURL">file:conf/initiator.cfg</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>transport.fix.AcceptorMessageStore</td>
+ <td>
+ The type of message store to be used with the
acceptor. Allowed values for
+ this parameter are 'file', 'jdbc', 'memory' and
'sleepycat'. Additional
+ <a
href="http://www.quickfixj.org/quickfixj/usermanual/1.4.0/usage/configuration.html#Storage";>parameters</a>
+ required to configure the message store should be
specified in the
+ acceptor configuration file. Ignored if the proxy
service is not operating
+ in the acceptor mode.
+ <div class="xmlConf"><parameter
name="transport.fix.AcceptorMessageStore">file</parameter></div>
+ </td>
+ <td>No</td>
+ <td>memory</td>
+ </tr>
+ <tr>
+ <td>transport.fix.InitiatorMessageStore</td>
+ <td>
+ The type of message store to be used with the
initiator. Allowed values for
+ this parameter are 'file', 'jdbc', 'memory' and
'sleepycat'. Additional
+ <a
href="http://www.quickfixj.org/quickfixj/usermanual/1.4.0/usage/configuration.html#Storage";>parameters</a>
+ required to configure the message store should be
specified in the
+ initiator configuration file. Ignored if the proxy
service is not operating
+ in the initiator mode.
+ <div class="xmlConf"><parameter
name="transport.fix.InitiatorMessageStore">file</parameter></div>
+ </td>
+ <td>No</td>
+ <td>memory</td>
+ </tr>
+ <tr>
+ <td>transport.fix.AcceptorLogFactory</td>
+ <td>
+ Specifies the type of FIX 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
+ <a
href="http://www.quickfixj.org/quickfixj/usermanual/1.4.0/usage/configuration.html#Logging";>parameters</a>
+ required to configure each of the lof factories
should be specified
+ in the acceptor configuration file. Ignored if the
proxy service is not
+ operating in the acceptor mode.
+ <div class="xmlConf"><parameter
name="transport.fix.AcceptorLogFactory">file</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>transport.fix.InitiatorLogFactory</td>
+ <td>
+ Specifies the type of FIX log factory to be used
to log messages going
+ through the initiator. 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
+ <a
href="http://www.quickfixj.org/quickfixj/usermanual/1.4.0/usage/configuration.html#Logging";>parameters</a>
+ required to configure each of the lof factories
should be specified
+ in the initiator configuration file. Ignored if
the proxy service is not
+ operating in the initiator mode.
+ <div class="xmlConf"><parameter
name="transport.fix.InitiatorLogFactory">file</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>transport.fix.UseThreadedConnectors</td>
+ <td>
+ Use multi-threaded acceptors and initiators.
Setting this parameter to
+ true is equivalent to setting both
transport.fix.UseThreadedAcceptor and
+ transport.fix.UseThreadedInitiator to true.
+ <div class="xmlConf"><parameter
name="transport.fix.UseThreadedConnectors">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.UseThreadedAcceptor</td>
+ <td>
+ Run the FIX acceptor in the multi-threaded mode.
That is use separate
+ threads for each acceptor session. Allowed values
are true or false.
+ Has more priority than
transport.fix.UseThreadedConnectors.
+ <div class="xmlConf"><parameter
name="transport.fix.UseThreadedAcceptor">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.UseThreadedInitiator</td>
+ <td>
+ Run the FIX initiator in the multi-threaded mode.
That is use separate
+ threads for each initiator session. Allowed values
are true or false.
+ Has more priority than
transport.fix.UseThreadedConnectors.
+ <div class="xmlConf"><parameter
name="transport.fix.UseThreadedInitiator">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.UseThreadedInitiator</td>
+ <td>
+ Run the FIX initiator in the multi-threaded mode.
That is use separate
+ threads for each initiator session. Allowed values
are true or false.
+ <div class="xmlConf"><parameter
name="transport.fix.UseThreadedInitiator">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.ProcessSingleThreaded</td>
+ <td>
+ Mediate all received FIX messages on the same
thread used by Quickfix/J
+ to perform network I/O. Use this parameter to
ensure that Synapse
+ mediates the FIX messages in the received order.
By default Synapse
+ uses a pool of threads to process received FIX
messages in parallel, which
+ may change their order. Also, using a single
thread has the side effect
+ of forcing the FIX transport to control the
request intake based on how
+ fast Synapse processes them. In some cases this
turns out to be the
+ preferred behavior.
+ <div class="xmlConf"><parameter
name="transport.fix.ProcessSingleThreaded">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.AcceptorSingleThreaded</td>
+ <td>
+ Mediate all FIX messages received as an acceptor
on the same thread used
+ by Quickfix/J to perform network I/O. This has
more priority over
+ transport.fix.ProcessSingleThreaded.
+ <div class="xmlConf"><parameter
name="transport.fix.AcceptorSingleThreaded">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.InitiatorSingleThreaded</td>
+ <td>
+ Mediate all FIX messages received as an initiator
on the same thread used
+ by Quickfix/J to perform network I/O. This has
more priority over
+ transport.fix.ProcessSingleThreaded.
+ <div class="xmlConf"><parameter
name="transport.fix.InitiatorSingleThreaded">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.AcceptorSessionEventHandler</td>
+ <td>
+ Use this parameter to register a custom acceptor
session event handler.
+ Can be used when it's required to inject some
custom logic into the way
+ how the FIX transport handles key FIX session
events. The value of this
+ parameter should be the full qualified name of a
class that implements the
+ <a
href="https://synapse.apache.org/apidocs/org/apache/synapse/transport/fix/SessionEventHandler.html";>org.apache.synapse.transport.fix.SessionEventHandler</a>
interface.
+ <div class="xmlConf"><parameter
name="transport.fix.AcceptorSessionEventHandler">foo.bar.MyEventHandler</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>transport.fix.InitiatorSessionEventHandler</td>
+ <td>
+ Use this parameter to register a custom initiator
session event handler.
+ Can be used when it's required to inject some
custom logic into the way
+ how the FIX transport handles key FIX session
events. The value of this
+ parameter should be the full qualified name of a
class that implements the
+ <a
href="https://synapse.apache.org/apidocs/org/apache/synapse/transport/fix/SessionEventHandler.html";>org.apache.synapse.transport.fix.SessionEventHandler</a>
interface.
+ <div class="xmlConf"><parameter
name="transport.fix.AcceptorSessionEventHandler">foo.bar.MyEventHandler</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ </table>
+ </subsection>
+ <subsection name="FIX Transport Sender" id="Sender">
+ <p>
+ To enable the FIX transport sender, uncomment the
following transport sender
+ configuration in the
<strong>SYNAPSE_HOME/repository/conf/axis2.xml</strong> file.
+ </p>
+ <div class="xmlConf"><transportSender name="fix"
class="org.apache.synapse.transport.fix.FIXTransportSender">
+ <parameter name="non-blocking">true</parameter>
+</transportSender></div>
+ <p>
+ To send a message using the FIX transport, define a
Synapse endpoint with an
+ address that starts with the prefix 'fix://'. The rest of
the address should
+ specify the target hostname, port and other FIX session
settings. An example is
+ shown below:
+ </p>
+ <div class="xmlConf"><endpoint>
+ <address
uri="fix://localhost:19876?BeginString=FIX.4.0&SenderCompID=SYNAPSE&TargetCompID=EXEC"/>
+</endpoint></div>
+ <p>
+ The above endpoint describes a FIX 4.0 session with the
SenderCompID set to
+ 'SYNAPSE' and the TargetCompID set to 'EXEC'. If this
session already exists
+ (created earlier by the proxy service), the message will
be sent using that
+ session. Otherwise, the FIX transport sender will create a
new initiator
+ session using the available session information and send
the message using this
+ new session.
+ </p>
+ <p>
+ Following list shows all the FIX session settings that can
be configured at
+ the endpoint level, as URL query parameters.
+ </p>
+ <ul>
+ <li>BeginString</li>
+ <li>SenderCompID</li>
+ <li>SenderSubID</li>
+ <li>SenderLocationID</li>
+ <li>TargetCompID</li>
+ <li>TargetSubID</li>
+ <li>TargetLocationID</li>
+ <li>DeliverToCompID</li>
+ <li>DeliverToSubID</li>
+ <li>DeliverToLocationID</li>
+ <li>SessionQualifier</li>
+ </ul>
+ <p>
+ The DeliverTo* fields will be actually set on the
messages, as they are forwarded
+ to the remote FIX endpoint.
+ </p>
+ <p>
+ There are several parameters that can be set at the proxy
service level to
+ configure the behavior of the FIX transport sender. A
complete list is given
+ below.
+ </p>
+ <table>
+ <tr>
+ <th>Parameter Name</th>
+ <th>Description/Example</th>
+ <th>Required</th>
+ <th>Default</th>
+ </tr>
+ <tr>
+ <td>transport.fix.BeginStringValidation</td>
+ <td>
+ Use this parameter to enable BeginString
validation for all outgoing
+ FIX messages. That is the BeginString value
currently set on the message
+ (typically this is set by the original source
application that sent the
+ message to Synapse), must match with the
BeginString field of the target
+ FIX session. Allowed values are true or false.
+ <div class="xmlConf"><parameter
name="transport.fix.BeginStringValidation">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.DropExtraResponses</td>
+ <td>
+ Sometimes FIX endpoints respond to requests with
multiple responses. This
+ could be problematic, if Synapse received the
original request via a protocol
+ like HTTP. In situations such as these, this
parameter can be used to
+ force Synapse to only mediate the first response
received from the remote
+ endpoint and discard the others. Allowed values
are true or false.
+ <div class="xmlConf"><parameter
name="transport.fix.DropExtraResponses">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.SendAllToInSequence</td>
+ <td>
+ In some integration scenarios it becomes necessary
treat all received
+ FIX messages (both requests and responses) as a
single message stream
+ and mediate them through the in-sequence of the
proxy service. This parameter
+ enables doing that. Allowed values are true or
false.
+ <div class="xmlConf"><parameter
name="transport.fix.SendAllToInSequence">true</parameter></div>
+ </td>
+ <td>No</td>
+ <td>false</td>
+ </tr>
+ <tr>
+ <td>transport.fix.ResponseDeliverToCompID</td>
+ <td>
+ Configure the DeliverToCompID value that should be
set on the response
+ messages sent by the proxy service. To set the
DeliverToCompID on
+ requests, set the DeliverToCompID directly on the
target FIX endpoint
+ as a query parameter.
+ <div class="xmlConf"><parameter
name="transport.fix.ResponseDeliverToCompID">APP</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>transport.fix.ResponseDeliverToSubID</td>
+ <td>
+ Configure the DeliverToSubID value that should be
set on the response
+ messages sent by the proxy service. To set the
DeliverToSubID on
+ requests, set the DeliverToSubID directly on the
target FIX endpoint
+ as a query parameter.
+ <div class="xmlConf"><parameter
name="transport.fix.ResponseDeliverToSubID">APP</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ <tr>
+ <td>transport.fix.ResponseDeliverToLocationID</td>
+ <td>
+ Configure the DeliverToLocationID value that
should be set on the response
+ messages sent by the proxy service. To set the
DeliverToLocationID on
+ requests, set the DeliverToLocationID directly on
the target FIX endpoint
+ as a query parameter.
+ <div class="xmlConf"><parameter
name="transport.fix.ResponseDeliverToLocationID">APP</parameter></div>
+ </td>
+ <td>No</td>
+ <td>N/A</td>
+ </tr>
+ </table>
+ </subsection>
+ </section>
+ </body>
+</document>
\ No newline at end of file
Modified:
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml
URL:
http://svn.apache.org/viewvc/synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml?rev=1515668&r1=1515667&r2=1515668&view=diff
==============================================================================
---
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml
(original)
+++
synapse/trunk/java/modules/documentation/src/site/xdoc/userguide/transports/vfs.xml
Mon Aug 19 23:40:26 2013
@@ -130,7 +130,8 @@
<p>
A proxy service configured with the VFS listener, can be
further customized by
setting a number of parameters (some of which are
required). Following table
- lists all the supported service parameters.
+ lists all the supported service parameters. Please refer
<a href="../samples/sample254.html">sample 254</a>
+ for an example that demonstrates how to use some of these
settings.
</p>
<table>
<tr>
