OpenMAMA C++ API
Wombat::Mama Class Reference

The Mama class provides methods global initialization and manipulating global options. More...

#include <mamacpp.h>

Static Public Member Functions

static mamaBridge loadBridge (const char *middleware)
 Load the bridge specified by middleware string. More...
 
static mamaBridge loadBridge (const char *middleware, const char *path)
 Load the bridge specified by middleware string using the path specified by the user. More...
 
static mamaPayloadBridge loadPayloadBridge (const char *payload)
 Load the payload bridge specified by payload string. More...
 
static mamaBridge getMiddlewareBridge (const char *middleware)
 Return a middleware bridge which matches the middleware string. More...
 
static mamaPayloadBridge getPayloadBridge (const char *payload)
 Return a payload bridge which matches the payload string. More...
 
static const char * getVersion (mamaBridge bridgeImpl)
 Returns the version of the mama binary. More...
 
static void open ()
 Initialize MAMA. More...
 
static unsigned int openCount ()
 Initialize MAMA. More...
 
static unsigned int openCount (const char *path, const char *filename)
 Initialize MAMA. More...
 
static void open (const char *path, const char *filename)
 Initialize MAMA. More...
 
static void registerEntitlementCallbacks (MamaEntitlementCallback *callback)
 Registers the callback methods to be called whenever the user receives a disconnect request or after a dynamic entitlements update occurrs. More...
 
static void setProperty (const char *name, const char *value)
 Set a specific property for the API. More...
 
static const char * getProperty (const char *name)
 Retrieve a specific property from the API. More...
 
static void close ()
 Close MAMA and free all associated resource. More...
 
static unsigned int closeCount ()
 Close MAMA and free all associated resources if no more references exist (e.g.if open has been called 3 times then it will require 3 calls to close in order for all resources to be freed). More...
 
static void start (mamaBridge bridgeImpl)
 Start processing messages on the internal queue. More...
 
static void startBackground (mamaBridge bridgeImpl, MamaStartCallback *callback)
 Start processing MAMA internal events in the background. More...
 
static void stop (mamaBridge bridgeImpl)
 Stop dispatching on the default event queue for the specified bridge. More...
 
static void stopAll (void)
 Stop dispatching on the default event queue for all bridges. More...
 
static void enableLogging (MamaLogLevel level, FILE *logFile)
 Enable logging and direct the output to the specified stream. More...
 
static void logToFile (const char *file, MamaLogLevel level)
 Enable logging to the specified file. More...
 
static void disableLogging (void)
 Disable logging. More...
 
static void setLogLevel (MamaLogLevel level)
 Set the logging level. More...
 
static MamaLogLevel getLogLevel (void)
 Get the logging level. More...
 
static void setLogSize (unsigned long size)
 Set the maxmum size of the log file (bytes) Default max size is 500 Mb. More...
 
static void setNumLogFiles (int numFiles)
 Set the number of rolled logfiles to keep before overwriting. More...
 
static void setLogFilePolicy (mamaLogFilePolicy policy)
 Set the policy regarding how to handle files when Max file size is reached. More...
 
static void setAppendToLogFile (bool append)
 Set the mode when opening an existing log file. More...
 
static bool loggingToFile (void)
 Get the status of loggingToFile Returns true if logging to a file, false if not. More...
 
static void setLogSizeCb (MamaLogFileCallback *callback)
 Set a callback for when the max log size is reached. More...
 
static void setApplicationName (const char *applicationName)
 Set the mama application name This should be called before Mama.open() More...
 
static void setApplicationClassName (const char *className)
 Set the mama application class This should be called before Mama.open() More...
 
static MamaQueuegetDefaultEventQueue (mamaBridge bridgeImpl)
 Get a pointer to the internal default MAMA event queue. More...
 
template<typename T >
static void deleteObject (T *object)
 Allow the MAMA API free memory for any objects which have been allocated by the API but responsibility for deleting has been handed to the application code. More...
 
static void setBridgeCallback (mamaBridge bridge, MamaBridgeCallback *callback)
 Set a MamaBridgeMessageCallback to be invoked whenever information messages are logged at the bridge level. More...
 
static void addStatsCollector (MamaStatsCollector *statsCollector)
 It adds the newly created statsCollector to the statsGenerator list. More...
 
static void removeStatsCollector (MamaStatsCollector *statsCollector)
 It removes the statsCollector from the statsGenerator list. More...
 

Detailed Description

The Mama class provides methods global initialization and manipulating global options.

Member Function Documentation

§ loadBridge() [1/2]

static mamaBridge Wombat::Mama::loadBridge ( const char *  middleware)
static

Load the bridge specified by middleware string.

If the bridge has already been loaded then the existing bridge instance will be returned.

Parameters
implThe bridge object
middlewareThe middleware string. Can be "wmw", "lbm" or "tibrv".
Returns
mama_status Whether the call was successful or not.

§ loadBridge() [2/2]

static mamaBridge Wombat::Mama::loadBridge ( const char *  middleware,
const char *  path 
)
static

Load the bridge specified by middleware string using the path specified by the user.

If the bridge has already been loaded then the existing bridge instance will be returned.

Parameters
implThe bridge object
middlewareThe middleware string. Can be "wmw", "lbm" or "tibrv".
pathThe path to the bridge library
Returns
mama_status Whether the call was successful or not.

§ loadPayloadBridge()

static mamaPayloadBridge Wombat::Mama::loadPayloadBridge ( const char *  payload)
static

Load the payload bridge specified by payload string.

If the bridge has already been loaded then the existing bridge instance will be returned.

Parameters
payloadThe payload to be loaded.
Returns
mamaPayloadBridge The payload bridge loaded.

§ getMiddlewareBridge()

static mamaBridge Wombat::Mama::getMiddlewareBridge ( const char *  middleware)
static

Return a middleware bridge which matches the middleware string.

Parameters
middlewareThe middleware to be returned
Returns
mamaBridge The middleware bridge to be returned. Returns NULL if none available.

§ getPayloadBridge()

static mamaPayloadBridge Wombat::Mama::getPayloadBridge ( const char *  payload)
static

Return a payload bridge which matches the payload string.

Parameters
payloadThe payload to be returned
Returns
mamaBridge The payload bridge to be returned. Returns NULL if none available.

§ getVersion()

static const char* Wombat::Mama::getVersion ( mamaBridge  bridgeImpl)
static

Returns the version of the mama binary.

The version of the underlying transport is also returned in parens after the mama version.

§ open() [1/2]

static void Wombat::Mama::open ( )
static

Initialize MAMA.

MAMA employs a reference count to track multiple calls to Mama::open() and Mama::close(). The count is incremented every time Mama::open() is called and decremented when Mama::close() is called. The resources are not actually released until the count reaches zero.

This function is thread safe.

§ openCount() [1/2]

static unsigned int Wombat::Mama::openCount ( )
static

Initialize MAMA.

MAMA employs a reference count to track multiple calls to Mama::open() and Mama::close(). The count is incremented every time Mama::open() is called and decremented when Mama::close() is called. The resources are not actually released until the count reaches zero.

This function is thread safe.

Returns
The reference count for the MAMA library after opening once. This will be non-zero and will match the amount of times a Mama::open() variant has been called.

§ openCount() [2/2]

static unsigned int Wombat::Mama::openCount ( const char *  path,
const char *  filename 
)
static

Initialize MAMA.

Allows users of the API to override the default behaviour of Mama.open() where a file mama.properties is required to be located in the directory specified by $WOMBAT_PATH.

The properties file must have the same structure as a standard mama.properties file.

If null is passed as the path the API will look for the properties file on the $WOMBAT_PATH.

If null is passed as the filename the API will look for the default filename of mama.properties.

MAMA employs a reference count to track multiple calls to Mama::open() and Mama::close(). The count is incremented every time Mama::open() is called and decremented when Mama::close() is called. The resources are not actually released until the count reaches zero.

Parameters
[in]pathFully qualified path to the directory containing the properties file
[in]filenameThe name of the file containing MAMA properties.
Returns
The reference count for the MAMA library after opening once. This will be non-zero and will match the amount of times a Mama::open() variant has been called.

§ open() [2/2]

static void Wombat::Mama::open ( const char *  path,
const char *  filename 
)
static

Initialize MAMA.

Allows users of the API to override the default behaviour of Mama.open() where a file mama.properties is required to be located in the directory specified by $WOMBAT_PATH.

The properties file must have the same structure as a standard mama.properties file.

If null is passed as the path the API will look for the properties file on the $WOMBAT_PATH.

If null is passed as the filename the API will look for the default filename of mama.properties.

MAMA employs a reference count to track multiple calls to Mama::open() and Mama::close(). The count is incremented every time Mama::open() is called and decremented when Mama::close() is called. The resources are not actually released until the count reaches zero.

Parameters
[in]pathFully qualified path to the directory containing the properties file
[in]filenameThe name of the file containing MAMA properties.

§ registerEntitlementCallbacks()

static void Wombat::Mama::registerEntitlementCallbacks ( MamaEntitlementCallback callback)
static

Registers the callback methods to be called whenever the user receives a disconnect request or after a dynamic entitlements update occurrs.

Parameters
callbackData structure containing the function to be invoked when disconnect request is received or after a dynamic entitlement update occurrs

§ setProperty()

static void Wombat::Mama::setProperty ( const char *  name,
const char *  value 
)
static

Set a specific property for the API.

If the property being set has already been given a value from a properties file that value will be replaced.

See the example mama.properties provided with the distribution for examples of property formatting. The properties set via this function should be formatted in the same manner as those specified in mama.properties.

The strings passed to the function are copied.

Parameters
nameThe name of the property
valueThe property value

§ getProperty()

static const char* Wombat::Mama::getProperty ( const char *  name)
static

Retrieve a specific property from the API.

If the property has not been set, a NULL value will be returned.

Parameters
nameThe name of the property to retrieve.
Returns
the value of the property or NULL if unset.

§ close()

static void Wombat::Mama::close ( )
static

Close MAMA and free all associated resource.

MAMA employs a reference count to track multiple calls to Mama::open() and Mama::close(). The count is incremented every time Mama::open() is called and decremented when Mama::close() is called. The resources are not actually released until the count reaches zero.

This function is thread safe.

§ closeCount()

static unsigned int Wombat::Mama::closeCount ( )
static

Close MAMA and free all associated resources if no more references exist (e.g.if open has been called 3 times then it will require 3 calls to close in order for all resources to be freed).

This function is thread safe.

Returns
The reference count for the MAMA library after closing once. If this is zero then MAMA and all resources will have been freed.

§ start()

static void Wombat::Mama::start ( mamaBridge  bridgeImpl)
static

Start processing messages on the internal queue.

This starts Mama's internal throttle, refresh logic, and other internal Mama processes as well as dispatching messages from the internal queue.

Mama::start( ) blocks until an invocation of Mama::stop() occurs.

MAMA employs a reference count to track multiple calls to Mama::start() and Mama::stop(). The count is incremented every time Mama::start() is called and decremented when Mama::stop() is called. The first Mama::start() call does not unblock until the count reaches zero.

This function is thread safe.

Parameters
[in]bridgeImplThe bridge specific structure.

§ startBackground()

static void Wombat::Mama::startBackground ( mamaBridge  bridgeImpl,
MamaStartCallback callback 
)
static

Start processing MAMA internal events in the background.

This method invokes Mama::start () in a separate thread.

Parameters
[in]bridgeImplThe middleware-specific bridge structure
[in]callbackThe callback for asynchronous status.

§ stop()

static void Wombat::Mama::stop ( mamaBridge  bridgeImpl)
static

Stop dispatching on the default event queue for the specified bridge.

MAMA employs a reference count to track multiple calls to Mama::start() and Mama::stop(). The count is incremented every time Mama::start() is called and decremented when Mama::stop() is called. The first Mama::start() call does not unblock until the count reaches zero.

This function is thread safe.

Parameters
[in]bridgeImplThe bridge specific structure.

§ stopAll()

static void Wombat::Mama::stopAll ( void  )
static

Stop dispatching on the default event queue for all bridges.

§ enableLogging()

static void Wombat::Mama::enableLogging ( MamaLogLevel  level,
FILE *  logFile 
)
static

Enable logging and direct the output to the specified stream.

Parameters
levelThe level
logFilethe log file.

§ logToFile()

static void Wombat::Mama::logToFile ( const char *  file,
MamaLogLevel  level 
)
static

Enable logging to the specified file.

Parameters
filethe log filename
levelThe level

§ disableLogging()

static void Wombat::Mama::disableLogging ( void  )
static

Disable logging.

§ setLogLevel()

static void Wombat::Mama::setLogLevel ( MamaLogLevel  level)
static

Set the logging level.

Parameters
levelThe level

§ getLogLevel()

static MamaLogLevel Wombat::Mama::getLogLevel ( void  )
static

Get the logging level.

Returns
the logging level

§ setLogSize()

static void Wombat::Mama::setLogSize ( unsigned long  size)
static

Set the maxmum size of the log file (bytes) Default max size is 500 Mb.

Parameters
sizethe max size of file (bytes)

§ setNumLogFiles()

static void Wombat::Mama::setNumLogFiles ( int  numFiles)
static

Set the number of rolled logfiles to keep before overwriting.

Default is 10

Parameters
numFilesthe max number of logfiles

§ setLogFilePolicy()

static void Wombat::Mama::setLogFilePolicy ( mamaLogFilePolicy  policy)
static

Set the policy regarding how to handle files when Max file size is reached.

Default is LOGFILE_UNBOUNDED - uses a single logfile unlimited in size. Other policies are: LOGFILE_ROLL - keeps N logfiles specified with setNumLogFiles(N). LOGFILE_OVERWRITE - uses a single logfile limited in size. LOGFILE_USER - if user has registered a callback it will be calledt. Otherwise the file will roll or get overwritten depending onthe value specified with setNumLogFiles(N).

Parameters
policythe policy to use when max size is reached

§ setAppendToLogFile()

static void Wombat::Mama::setAppendToLogFile ( bool  append)
static

Set the mode when opening an existing log file.

setAppendToLogFile(true) will add data to the end of an existing file. Default is false which will overwrite any existing data in the file.

Parameters
appendboolean flag to set append mode on or off

§ loggingToFile()

static bool Wombat::Mama::loggingToFile ( void  )
static

Get the status of loggingToFile Returns true if logging to a file, false if not.

Returns
the status of loggingToFile

§ setLogSizeCb()

static void Wombat::Mama::setLogSizeCb ( MamaLogFileCallback callback)
static

Set a callback for when the max log size is reached.

This will only be called if the policy has been set to LOGFILE_USER.

Parameters
LogSizeCallbackfunction pointer for the callback

§ setApplicationName()

static void Wombat::Mama::setApplicationName ( const char *  applicationName)
static

Set the mama application name This should be called before Mama.open()

Parameters
applicationName

§ setApplicationClassName()

static void Wombat::Mama::setApplicationClassName ( const char *  className)
static

Set the mama application class This should be called before Mama.open()

Parameters
className

§ getDefaultEventQueue()

static MamaQueue* Wombat::Mama::getDefaultEventQueue ( mamaBridge  bridgeImpl)
static

Get a pointer to the internal default MAMA event queue.

Parameters
bridgeImplThe middleware specific bridge structure.
Returns
A pointer to the internal MAMA default event queue.

§ deleteObject()

template<typename T >
static void Wombat::Mama::deleteObject ( T *  object)
static

Allow the MAMA API free memory for any objects which have been allocated by the API but responsibility for deleting has been handed to the application code.

This enables users of the API to provide alternate memory management implementations which may result in difficulties when deleting objects allocated internally by the MAMA API.

E.g. Detaching the MamaMsg in a subscription callback.

Currently supported types:

MamaMsg

§ setBridgeCallback()

static void Wombat::Mama::setBridgeCallback ( mamaBridge  bridge,
MamaBridgeCallback callback 
)
static

Set a MamaBridgeMessageCallback to be invoked whenever information messages are logged at the bridge level.

Information messages vary depenging on the underlying middleware. Currently only supported for LBM.

§ addStatsCollector()

static void Wombat::Mama::addStatsCollector ( MamaStatsCollector statsCollector)
static

It adds the newly created statsCollector to the statsGenerator list.

Parameters
statsCollector

§ removeStatsCollector()

static void Wombat::Mama::removeStatsCollector ( MamaStatsCollector statsCollector)
static

It removes the statsCollector from the statsGenerator list.

Parameters
statsCollector