<?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 - FIX Setup Guide</title>
    </properties>
    <body>
        <section name="FIX Setup Guide">
            <p>
                This document explains how to setup the FIX transport sender and listener
                in Synapse as required by the samples. Further it describes how to setup the
                sample FIX applications (Executor and Banzai) which are essential for trying
                out the FIX samples.
            </p>
        </section>
        <section name="Contents">
            <ul>
                <li><a href="#intro">Introduction</a></li>
                <li><a href="#pre">Prerequisites</a></li>
                <li><a href="#synapse">Enabling FIX Transport in Synapse</a></li>
                <li><a href="#services">Configuring Services for FIX Transport</a></li>
                <li>
                    <a href="#samples">Setting Up the Sample FIX Applications</a>
                    <ul>
                        <li><a href="#exec">Configuring the Executor</a></li>
                        <li><a href="#banzai">Configuring Banzai</a></li>
                    </ul>
                </li>
                
            </ul>
        </section>
        <section name="Introduction" id="intro">
            <p>
                <a href="http://www.fixprotocol.org">FIX (Financial Information eXchange)</a>
                is a domain specific communication protocol widely used in the finance sector for
                securities transactions. The protocol specification spans across the application layer
                and the session layer of the OSI reference model of networking. Apache Synapse comes
                with a FIX transport adapter which enables the Synapse ESB to communicate with FIX
                acceptors and initiators. This allows users to seamlessly integrate FIX applications
                together and even link FIX applications with other systems that use different protocols.
            </p>
            <p>
                This article describes how to enable and configure the FIX transport listener and
                sender for Apache Synapse. It also describes how to setup various sample FIX applications
                required to try out the FIX protocol related examples.
            </p>
        </section>
        <section name="Prerequisites" id="pre">
            <p>
                The FIX transport adapter of Synapse is built on top of the <a href="http://www.quickfixj.org">Quickfix/J</a>
                open source FIX engine. Therefore the users must deploy the Quickfix/J libraries
                into Synapse before using the FIX transport. Also in order to try out the FIX
                samples described in this documentation, it is required to have the 2 sample FIX
                applications (Banzai and Executor) that come bundled with Quickfix/J. Therefore as
                the first step <a href="http://www.quickfixj.org/downloads/">download</a> the latest
                binary distribution of Quickfix/J and extract the downloaded archive to a suitable
                location on the local disk (let's refer to this location as QFJ_HOME).
            </p>
            <p>
                All the necessary Quickfix/J libraries are available in the Quickfix/J binary
                distribution. You have to copy the following jar files from Quickfix/J installation
                to the 'lib' directory of Synapse.
            </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>
            </ul>
            <p>
                The last 2 jar files can be found in the QFJ_HOME/bin directory and all other
                files should be available in the QFJ_HOME itself.
            </p>
        </section>
        <section name="Enabling FIX Transport in Synapse" id="synapse">
            <p>
                FIX transport listener and the FIX transport sender of Synapse can be enabled by
                uncommenting the following sections in the repository/conf/axis2.xml file.
            </p>
            <div class="xmlConf">&lt;transportReceiver name="fix" class="org.apache.synapse.transport.fix.FIXTransportListener"/&gt;</div>
            <div class="xmlConf">&lt;transportSender name="fix" class="org.apache.synapse.transport.fix.FIXTransportSender"/&gt;</div>
            <p>
                This will initialize the FIX transport adapter and have it up and running to be
                used by the proxy services. However some additional setting should be applied at
                the service level before a service can make use of the FIX transport.
            </p>
        </section>
        <section name="Configuring Services for FIX Transport" id="services">
            <p>
                When a service needs to be exposed over the FIX transport, we should add the
                following parameter to the service configuration.
            </p>
            <div class="xmlConf">&lt;parameter name="transport.fix.AcceptorConfigURL"&gt;url&lt;/parameter&gt;</div>
            <p>
                The value of this parameter must be a valid URL which points to a Quickfix/J session
                configuration file. All the FIX sample configurations are already equipped with this
                parameter and they are pointing to the sample Quickfix/J configuration files that
                comes with Synapse. These files can be found in the repository/sample/resources/fix
                directory. One such configuration file (fix-synapse.cfg) is shown below.
            </p>
            <div class="consoleOutput">[default]
FileStorePath=repository/fix/store/acceptor
ConnectionType=acceptor
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ValidOrderTypes=1,2,F
SenderCompID=EXEC
TargetCompID=SYNAPSE
UseDataDictionary=Y
DefaultMarketPrice=12.30

[session]
BeginString=FIX.4.0
SocketAcceptPort=9876</div>
            <p>
                One of the most important parameters in this configuration is the SocketAcceptPort
                setting. This defines the port used by the Synapse proxy service to receive
                incoming FIX messages.
            </p>
            <p>
                As far as the FIX samples are considered you don't have to make any changes to
                these Quickfix/J configuration files or the Synapse sample configurations. Default
                settings should work out of the box without any issues. However some samples may
                require you to make minor changes to these files.
            </p>
        </section>
        <section name="Setting Up the Sample FIX Applications" id="samples">
            <p>
                Two sample FIX applications are available in the Quickfix/J binray distribution
                which can be used to send and receive FIX messages. By default these applications
                are configured to directly communicate with each other. So we should make a few
                modifications to the configuration to get them to communicate with Synapse. The
                binaries of these sample programs are available in the quickfixj-examples.jar file
                in QFJ_HOME. Startup scripts needed to run them can be found in the QFJ_HOME/bin
                directory.
            </p>
            <subsection name="Configuring the Executor" id="exec">
                <p>
                    Executor is the sample acceptor program. To configure this application to
                    receive messages from Synapse, put the following entries to a file named
                    'executor.cfg'.
                </p>
                <div class="consoleOutput">[default]
FileStorePath=examples/target/data/executor
ConnectionType=acceptor
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ValidOrderTypes=1,2,F
SenderCompID=EXEC
TargetCompID=SYNAPSE
UseDataDictionary=Y
DefaultMarketPrice=12.30

[session]
BeginString=FIX.4.0
SocketAcceptPort=19876</div>
                <p>
                    Note that TargetCompID parameter has been set to 'SYNAPSE' and the port number
                    has been set to 9876. You can launch the Executor using the above configuration
                    as follows.
                </p>
                <div class="command">Unix/Linux: sh executor.sh &lt;path to executor.cfg&gt;<br/>
Windows: executor.bat &lt;path to executor.cfg&gt;</div>
                <p>
                    For some samples you will have to make some minor modifications to this
                    configuration file.
                </p>
            </subsection>
            <subsection name="Configuring Banzai" id="banzai">
                <p>
                    Banzai is a sample FIX initiator that comes with Quickfix/J. This can be
                    used to send FIX messages to a defined FIX acceptor. In case of samples,
                    Synapse will act as the acceptor. In order to send messages to Synapse, we
                    should start Banzai using the following configuration.
                </p>
                <div class="consoleOutput">[default]
FileStorePath=examples/target/data/banzai
ConnectionType=initiator
SenderCompID=BANZAI
TargetCompID=SYNAPSE
SocketConnectHost=localhost
StartTime=00:00:00
EndTime=00:00:00
HeartBtInt=30
ReconnectInterval=5

[session]
BeginString=FIX.4.0
SocketConnectPort=9876</div>
                <p>
                    Note that TargetCompID has been set to 'SYNAPSE' and the socket connect port
                    is specified to be 9876, which is the port used by Synapse. To start Banzai
                    with this configuration, save the above in a file named 'banzai.cfg' and
                    launch the sample application as follows.
                </p>
                <div class="command">Unix/Linux: sh banzai.sh &lt;path to banzai.cfg&gt;<br/>
Windows: banzai.bat &lt;path to banzai.cfg&gt;</div>
            </subsection>
        </section>
    </body>
</document>