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

Release: 2.3.1
Change Log: http://git.openmama.org/?p=OpenMAMA.git;a=shortlog;h=refs/tags/OpenMAMA-2.3.1-release

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. Example middleware bridges
and payloads are included for Avis and QPID. These middlewares can be obtained
from the following websites:

    http://avis.sourceforge.net
    http://qpid.apache.org/proton

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

The Qpid Proton middleware has an additional dependency on the libevent event
management library, which is used for it's IO implementation.

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

The primary OpenMAMA git repository is located at:

http://git.openmama.org/OpenMAMA.git

Navigating to the site will also allow interactive web access to the
repository.

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

configure                     configure script.
Makefile                      GNU Makefile
README                        this file
COPYING                       Licence
SConstruct                    Main entry point for SCons build system
site_scons                    Additional code used for SCons build system

common/c_cpp/
    configure.ac              autoconf script
    Makefile.am               autoconf makefile
    Makefile.common.vcc       windows makefile
    SConscript                Configuration and setup for common SCons build
    SConscript.win            Equivalent for Windows builds
    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
    SConscript                Configuration and setup for MAMA SCons build
    SConscript.win            Equivalent SCons file for Windows build
    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 
    bridge/qpid/              c files for qpid proton middleware bridge 
    conflation/               c files for mama conflation component
    mama/                     header files for mama
    payload/avismsg/          c files for avis payload bridge implementation
    payload/qpidmsg/          c files for qpid proton 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
    SConscript                Configuration and setup for MAMA JNI SCons build
    SConscript.win            Equivalent SCons file for Windows builds
    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
    SConscript                Configuration and setup for MAMDA SCons build
    SConscript.win            Equivalent SCons file for Windows builds
    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
    SConscript                Configuration and setup for MAMDA Java SCons build
    SConscript.win            Equivalent SCons file for Windows builds

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 unless told
otherwise. To build the avis client libraries:

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. Use
--with-avis=/path/to/avis to specify where to find avis if it is not installed
to a default location.

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


### Qpid Proton Install ###

To build with the Qpid Proton bridge, the Qpid Proton bridge must already be
compiled and installed. Note that the recommended version for use with OpenMAMA
is 0.5.

The qpid proton release can be downloaded and compiled from their website:
    http://qpid.apache.org/proton/

Alternatively, Qpid Proton can be often be installed using common package
managers. For example, to install using "Yum" on a RedHat, Centos or Fedora
system, use:

    sudo yum install qpid-proton-c-devel

Once compiled and installed, OpenMAMA can be compiled with Proton support using
the following additions to the SCons command:

    scons middleware=qpid qpid_home=/path/to/proton

If building on Windows, you'll also need to include the "libevent_home" command
line argument, pointing to your local libevent install.

For more information, checkout the documentation on the OpenMAMA Wiki, at:

    http://wiki.openmama.org

#### Legacy Build System ####
If building with the legacy Autotools system, OpenMAMA can be compiled with
proton support by using the following command *if you are using
mama/c_cpp/configure*:
    ./configure --with-proton=/path/to/proton

If you are using the *top level* configure script, you can do the equivalent
by running:
    ./configure --proton-path=/path/to/proton

For more information on the Qpid Proton bridge, see:
    http://wiki.openmama.org/index.php/Qpid_Bridge

### 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


### SCons Instructions ###

The following uses the default settings to build the OpenMAMA and OpenMAMDA
libraries and example applications, along with the Qpid Proton Bridge. This
assumes Qpid is installed in /usr, and will install OpenMAMA to an
openmama_install_* directory within the current directory.

In the top level directory for the OpenMAMA source files:

    scons middleware=qpid

### SCons Arguments ###

vis_home: Path to Avis ( /path/to/avis_home )
 Default: /usr/local/ [ /usr/local/ ]

blddir: Object directory ( /path/to/blddir )
 Default: #objdir [ #objdir ]

cache_dir: Path to object cache ( /path/to/cache_dir )
 Default: None [ None ]

compiler: Compiler to use for building OpenMAMA (default|gcc|clang|clang-analyzer)
 Default: default [ clang ]

entitled: Whether the build is entitled or unentitled (yes|no)
 Default: False [ False ]

gtest_home: Path to Google Test home ( /path/to/gtest_home )
 Default: None [ /usr/local ]

java_home: JAVA Home folder ( /path/to/java_home )
 Default: None [ /usr/java/latest/ ]

logfile: Output Log File ( /path/to/logfile )
 Default: scons.log [ scons.log ]

middleware: Middleware(s) to be compiled in
    (all|none|comma-separated list of names)
    allowed names: avis qpid
 Default: avis [ qpid ]

package: Whether to tar up the installation directory (yes|no)
 Default: False [ False ]

prefix: Installation prefix ( /path/to/prefix )
 Default: #openmama_install_6.0.1rc2 [ /home/damian/workspace/openmama/OpenMAMA-dev/install ]

product: Product to be built (mamda|mamajni|common|mamdajni|mama)
 Default: mamda [ mama ]

qpid_home: Path to QPID Proton Libraries ( /path/to/qpid_home )
 Default: /usr/local/ [ /home/damian/lib/proton-0.5/ ]

verbose: Whether to print verbose output (yes|no)
 Default: True [ True ]

with_docs: Build with documentation (yes|no)
 Default: False [ False ]

with_examples: Build with test tools (yes|no)
 Default: True [ True ]

with_testtools: Build with test tools (yes|no)
 Default: False [ True ]

with_unittest: Build with gunit tests (yes|no)
 Default: False [ True ]

Use scons -H for help about command-line options.


### Windows Build Using SCons ###

The following uses the default settings to build the OpenMAMA library and
example applications. It assumes you have a local install of Qpid Proton and
libevent, as well as JDK and Flex binaries available.

Begin by setting the appropriate environment variables:

    set PATH=%PATH%;C:\PROGRA~2\GnuWin32\bin
    set PATH=%PATH%;C:\PROGRA~1\Java\jdk1.7.0_45\bin
    set JAVA_HOME=C:\PROGRA~1\Java\jdk1.7.0_45\bin
    set PATH=%PATH%;C:\Python27\Scripts\

Then in the top level of the OpenMAMA source, execute the following:

    scons middleware=qpid qpid_home=C:\Path\To\Qpid 
    libevent_home=C:\Path\To\libevent product=mama

More detailed Windows build instructions (including details for resolving
the build dependencies can be found at:

    http://wiki.openmama.org/index.php/Build_instructions_(Windows)


### Legacy 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}

specify non default Qpid Proton install:
--proton-path=${AVIS_HOME}

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

build testtools:
--with-testtools



### Legacy 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 (built with the with_unittests flag set to true, and
gtest_home directed to a local gtest installation), a series of extra binaries
can be found in the bin folder of the install.

 UnitTestCommonC
 UnitTestMamaC
 UnitTestMamaCPP
 UnitTestMama*

Each runs a subset of the available MAMA unit tests, using the Google test
framework. 
 
The following command line argument is available, as well as the normal Google
test options:
 
 -m ${MIDDLEWARE}

Tests which interact with the underlying payload directly also accept the
following:

 -p ${PAYLOAD}


### Legacy 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.


### Legacy 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 middleware, add middleware libraries to LD_LIBRARY_PATH

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/middleware/lib

3. Set WOMBAT_PATH to mama.properties file
 
   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/get-involved


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.