OpenMAMA Client Library
============================

Project Page
------------

http://www.openmama.org 

Overview
--------

OpenMAMA is a lightweight wrapper that provides a common API interface to
different middleware and messaging solutions across a variety of platforms and
languages.

OpenMAMDA is a framework that adds Market Data functionality, such as order book
handling on top of MAMA.

Please see the project page above for more information, as well as the mailing
list for questions, discussions, and development.

Supported Platforms
-------------------

Currently C, C++ and JNI/Java on Linux and Windows are the supported platforms.

Supported distributions are

    * Redhat 4
    * Redhat 5
    * Redhat 6
    * SLERT
    * SuSe 10
    * Windows XP +
    * Java SE 6 (from Oracle)

Requirements for End Users
--------------------------

OpenMAMA is designed to have minimal build requirements. 

Linux
-----

These are the base requirements to build and use OpenMAMA from a source package
(as described below):

  * GNU-compatible Make or gmake
  * POSIX-standard shell
  * C99 compiler
  * Apache Ant (for JNI/Java builds)
  * gnu flex (fast lexical analyzer) available from http://flex.sourceforge.net
    or as part of many Linux distributions

To use OpenMAMA you will need a middleware/payload. An example middleware bridge
and payload is included for Avis. Avis can be obtained from the following
website:

    http://avis.sourceforge.net.

OpenMAMA API reference documentation depends on:

    * doxygen (C/C++)
    
Unit tests are dependent on the Google Testing Framework (C/C++) or JUnit
(JNI/Java), which are available from:

http://code.google.com/p/googletest/
http://www.junit.org/

OpenMAMA's own regression tests also rely on:

    *Python version 2.3 or newer

Windows
-----
Visual Studio 8 or later
 

Getting the Source
------------------

Use one of the following methods to obtain the OpenMAMA source code:

    * Download a stable source release in archive format
    * Check out the source from our GIT repository.
    
The GIT checkout requires a few extra steps, and extra software packages to be
installed on your system. However, it provides easier tracking of the latest
development and make patches.

### Source Package ###

OpenMAMA is released in versioned source packages that can be downloaded from:

  http://www.openmama.org/downloads 

Once the package is downloaded, extract it. The following directory, containing
all the source code, will be created:
 
 openmama-X.Y.Z 


### GIT Checkout ###

To check out the main branch of OpenMAMA, complete the instructions on the
following site:

http://www.openmama.org/downloads/git-repository

OpenMAMA Directory Structure
----------------------------

configure                     configure script.
Makefile                      GNU Makefile
README                        this file
COPYING                       Licence

common/c_cpp/
    configure.ac              autoconf script
    Makefile.am               autoconf makefile
    Makefile.common.vcc       windows makefile
    src/c/                    c files for common library
    src/c/linux/              linux specific c files for common library
    src/c/windows/            windows specific c files for common library
    src/c/windows/wombat/     windows specific header for common library
    src/c/wombat/             header files for common library
    src/cpp/                  cpp files for common library
    src/cpp/wombat/           cpp header files for common library                 
common/jni/
    src/com/wombat/common/    java files for common library
    
mama/c_cpp/
    configure.ac              autoconf script
    Makefile.am               autoconf makefile
    Makefile.base.vcc         windows makefile
    Makefile.bridge.vcc       windows makefile
    Makefile.mama.vcc         windows makefile
    Makefile.mamac.vcc        windows makefile
    Makefile.mamacpp.vcc      windows makefile
    Makefile.mak              windows makefile
    doxyconfig-c.in           doxygen config for C reference guide
    doxyconfig-cpp.in         doxygen config for C++ reference guide
    doc/                      
    doc/images/               reference guide images
    
mama/c_cpp/src/c/             c files for mama C library
    bridge/avis/              c files for avis middleware bridge 
    conflation/               c files for mama conflation component
    mama/                     header files for mama
    payload/avismsg /         c files for avis payload bridge implementation
    playback/                 c files for mama playback component

mama/c_cpp/src/cpp/           cpp files for mama C++ library
    conflation                cpp files for mama conflation component
    fieldcache                cpp files for mama fieldcache component
    fieldcache/mama           header files for mama fieldcache component
    mama                      header files for mama

mama/c_cpp/src/examples/     
    mama.properties           example mama.properties file
    c/                        c files for mama example applications
    c/Makefile.sample         Makefile to build C examples only
    cpp/                      cpp files for mama example applications
    cpp/Makefile.sample       Makefile to build C++ examples only
    cpp/perf/

mama/c_cpp/src/gunittest/     
    c/                        c files for mama gunittest applications
    cpp/                      cpp files for mama gunittest applications

mama/c_cpp/src/regression/
    c_cpp/scripts/            regression scripts for C and C++
    c_cpp/tools/              regression tests for C and C++ 
    
mama/c_cpp/src/testtools/     test tools for c++ API
    capturereplay/c/          capture and replay apps using C API
    load/c/                   load testing apps for C API
    load/cpp/                 load testing apps for C++ API
    performance/c/            performance testing apps for C API
    performance/cpp/          performance testing apps for C++ API

mama/jni/
    build.xml                 java build file
    configure.ac              autoconf script
    Makefile.am               autoconf makefile
    Makefile.vcc              windows makefile
    doc/                      reference guide files

mama/jni/src/c/               c files for mama JNI library
    Makefile.am               autoconf makefile
    mamajni/                  header files for mamajni

mama/jni/src/com/wombat/mama/ java files for mama JNI library
    examples/                 java files for mama example applications
    testtools/load/           load testing apps for JNI api
    testtools/performance/    performance testing apps for JNI api

mama/jni/src/junittests/      java unittests

mama/jni/src/regression/
    scripts/                  regression scripts for java
    tools/                    regression tests for java

mamda/c_cpp/
    configure.ac              autoconf script
    Makefile.am               autoconf makefile
    Makefile.base.vcc         windows makefile
    Makefile.mamda.vcc        windows makefile
    Makefile.news.vcc         windows makefile
    Makefile.options.vcc      windows makefile
    Makefile.orderbooks.vcc   windows makefile
    Makefile.mak              windows makefile
    doxyconfig-cpp.in         doxygen config for C++ reference guide
    doc/                      reference guide style
    doc/images/               reference guide images

mamda/c_cpp/src/cpp/          mamda C++ files
    mamda/                    mamda header files
    news/                     mamda news C++ files
    news/mamda/               mamda news header files
    options/                  mamda options C++ files
    options/mamda/            mamda options header files
    orderbooks/               mamda orderbooks C++ files
    orderbooks/mamda/         mamda orderbooks header files

mamda/c_cpp/src/examples/     mamda C++ standard example apps
    news/                     mamda C++ news example apps
    orderbooks/               mamda C++ orderbook example apps
    orderbooks/test/          mamda C++ orderbook test apps

mamda/c_cpp/src/gunittest/
    common/                   general C++ mamda unittests
    orderbooks/               mamda C++ orderbook unittests
    orderImbalances/          mamda C++ order imbalance unittests
    quotes/                   mamda C++ quote unittests
    secstatus/                mamda C++ security status unittests
    trades/                   mamda C++ trade unittests

mamda/c_cpp/sec/testtools/    mamda test apps

mamda/java/
    build.xml                 java build file

mamda/java/com/wombat/mamda/  mamda java files
    examples/                 mamda java example apps
    locks/                    mamda java lock files
    options/                  mamda java option files
    orderbooks/               mamda java orderbook files

mamda/java/junittests/
    orderBooks/               mamda java orderbook unittests
    orderImbalances/          mamda java order imbalance unittests
    quotes/                   mamda java quote unittests
    secstatus/                mamda java security status unittests
    trades/                   mamda java trade unittests



                              
Building OpenMAMA
--------------------

### Avis Install ###

Currently OpenMAMA assumes Avis is the middleware to be built with, as this is
currently the only opensource middleware supported.  Therefore, the Avis client
libraries must be available.  

The Avis router (avisd) is avalaible from:
    http://sourceforge.net/projects/avis/viles/Avis%20router/

To build the avis client:
    download the source from: 
         http://downloads.sourceforge.net/avis/avis-client-1.2.4.tar.gz
    tar -xzf avis-client-1.2.4.tar.gz
    cd avis-client-1.2.4
    ./configure --prefix=${AVIS_HOME}
    make install

The default install of Avis is missing a header file. This needs to be moved
manually in the include directory.  The OpenMAMA configure script checks for
this header and will exit with an error if not found.

  mv ${AVIS_SOURCE}/platforms/gnu_automake/avis_client_config.h ${AVIS_HOME}/include/avis



### Google Test Install ###

OpenMAMA uses the static google test library and expects the files to be in the
following location. 

${GTEST_HOME}/include - include files
${GTEST_HOME}/lib - library files



### GNU Automake Instructions ###

The following uses the default settings to build the OpenMAMA library and
example applications.  This assumes that Avis middleware is available in
/usr/local, and will install OpenMAMA to /opt/OpenMAMA

If you are building source code cloned from the OpenMAMA git repository run the
following command before following the remaining instructions:

  ./generateBuildFiles.sh

For source downloaded as an archive from http://www.openmama.org, it is not
necessary to run generateBuildFiles.sh. 

  ./configure --with-avis=/usr/local
  make
  sudo make install
  
  

### Configure arguments ###

The following arguments can be passed to the configure script if you wish to use
non-default paths, or build extra components of OpenMAMA:

specify an alternative install location:
--prefix=${INSTALL_DIR}

specify non default Avis install:
--avis-path=${AVIS_HOME}

build unittests, specify google test location:
--gtest-path=${GTEST_HOME}

build testtools:
--with-testtools



### Building the API Reference ###
 
To build the latest API reference guide, use the following command after
Configure:
 
     make docs
     
This will build the reference in the mama/c_cpp/src/doc folder.

 
 
### Running Unit tests ###
 
After the build is complete, an extra binary can be found in the bin folder of
the install.
 
 MainUnitTestC
 
This runs the full set of unit tests using the google test framework.
 
The following command line argument is available, as well as the normal Google
test options:
 
 -m ${MIDDLEWARE}


 
### Windows C/C++ build ###

Set the AVIS_HOME environment variable appropriately.  This should contain
debug, release, and include folders.

Set the JAVA_HOME environment variable appropriately (for mamajni). This should
contain an include folder.

Set the ANT_HOME environment variable appropriately (for mamajni).

Set the GTEST_HOME environment variable appropriately (optional for unittests).
This should contain debug, release, and include folders.

Insure Flex is included in your path.

Open OpenMama.sln

Build common, then mama, then mamda. Avis folder should also be built, if not
previously done.

Concurrent building of multiple products may cause build fail.
Flex perbuild command is run when building common.


### Windows Java build ###

Follow the above steps to build MAMA in C, which the JNI files depend on.

For MAMA JNI, in the mama folder, run ant on the build.xml file.  ant {optional
arguments} -f build.xml

The following build arguments are optional:
-DwithTestBed=true
-DwithDocs=true

For MAMDA JNI, in the mamda folder, run ant on the build.xml file with target
dist ant -f build.xml dist

Run generatewindist in the root OpenMAMA folder. This will create a directory called 'install' containing all the files for distribution.



### Running regression tests ###
 
OpenMAMA regression test suite 
==============================
The OpenMAMA regression suite is implemented as python unittests.
 
Directories:

scripts: Contains python scripts.
tools: Contains modified mama sample apps.

Complete the following steps to run the test suite:
1. Set LD_LIBRARY_PATH to the lib directory of OpenMAMA.
  
   export LD_LIBRARY_PATH=/path/to/OpenMAMA/lib

2. To run with avis, add avis libraries to LD_LIBRARY_PATH (avis only)

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/avis/client/lib

3. Set WOMBAT_PATH to mama.properties file (Not required for avis running on
   default port) 
 
   export WOMBAT_PATH=/path/to/mamaproperties/

4. Set CLASSPATH to both the tools directory and the OpenMAMA jars (to test jni)
    export CLASSPATH=/path/to/tools:/path/to/OpenMAMA/lib/xxx.jar:$CLASSPATH

5. In tools directory,set API_HOME in sample make file to OpenMAMA root
   directory, that contains lib directory (to test OpenMAMA c and c++)

    API_HOME=/path/to/OpenMAMA/root/directory   
    #parent directory of lib in step 1
    
6. In tools directory, execute the following command to compile c and cpp apps
using make

    make -f Makefile.sample

7. In tools directory, compile the java apps (to test OpenMAMA jni) javac
   BasicPubJava.java BasicSubJava.java BasicInboxJava.java
   BasicFtMemberJava.java
    
9. For details about optional arguments run
  
   python regression.py --help

10. In scripts directory, run regression.py (python versions 2.4 till 2.7
    supported)

    python regression.py    # Runs all tests with avis, avis router should be
                            # running on default port

    python regression.py --m lbm --tport pub sub --test all --timeout 10 --q    
    #run all tests without verbose output

N.B. In the first run, pubsub tests will fail as it requires expected log files.
    Make a copy of pubsub subscption log as expected log.
   cp pubsub_basicsubc.out pubsub_expectedsubc.out          # for c
   cp pubsub_basicsubcpp.out pubsub_expectedsubcpp.out      # for c++
   cp pubsub_basicsubjava.out pubsub_expectedsubjava.out    # for java
   
   
  
Contributing
-------------

Can be done through the OpenMAMA website
http://www.openmama.org/developers


License
--------

The OpenMAMA library is distributed under the terms of the GNU Lesser General
Public license version 2.  Please see COPYING for full licence text.