OpenMAMA C++ API
Wombat::MamaDictionary Class Reference

The MamaDictionary class maps field identifiers (FIDs) to human readable strings. More...

#include <MamaDictionary.h>

Public Member Functions

virtual ~MamaDictionary ()
 
 MamaDictionary (void)
 
virtual void create (MamaQueue *queue, MamaDictionaryCallback *callback, MamaSource *source, int retries=MAMA_DEFAULT_RETRIES, double timeout=MAMA_DEFAULT_TIMEOUT, void *closure=NULL)
 Create a dictionary subscription. More...
 
virtual const char * getFeedName ()
 Return the dictionary source feed name. More...
 
virtual const char * getFeedHost ()
 Return the dictionary source feed host. More...
 
virtual MamaFieldDescriptorgetFieldByFid (mama_fid_t fid)
 Return the field with the specified field FID. More...
 
virtual const MamaFieldDescriptorgetFieldByFid (mama_fid_t fid) const
 Return the field with the specified field FID. More...
 
virtual MamaFieldDescriptorgetFieldByIndex (size_t index)
 Return the field with the corresponding zero based index. More...
 
virtual const MamaFieldDescriptorgetFieldByIndex (size_t index) const
 Return the field with the corresponding zero based index. More...
 
virtual MamaFieldDescriptorgetFieldByName (const char *name)
 Return the field with the specified name. More...
 
virtual const MamaFieldDescriptorgetFieldByName (const char *name) const
 Return the field with the specified name. More...
 
virtual mama_fid_t getMaxFid (void) const
 Return the highest field identifier. More...
 
virtual size_t getSize (void) const
 Return the number of fields in the dictionary. More...
 
virtual bool hasDuplicates (void) const
 Return true if there are multiple fields with the same name. More...
 
virtual MamaDictionaryCallbackgetCallback (void) const
 Return the callback. More...
 
virtual void setCallback (MamaDictionaryCallback *callback)
 Set the callback to receive notifications when creation is complete or an error occurs. More...
 
virtual mamaDictionary getDictC ()
 Return the underlying C mamaDictionary. More...
 
virtual const mamaDictionary getDictC () const
 Return the underlying C mamaDictionary. More...
 
virtual void * getClosure (void) const
 Return the closure for the dictionary. More...
 
virtual MamaMsggetDictionaryMessage () const
 Returns a MamaMsg representing the data dictionary. More...
 
virtual void buildDictionaryFromMessage (MamaMsg &msg)
 Recreate a data dictionary from the MamaMsg supplied. More...
 
virtual MamaFieldDescriptorcreateFieldDescriptor (mama_fid_t fid, const char *name, mamaFieldType type)
 Add a new field descriptor to a dictionary. More...
 
virtual void setMaxFid (mama_size_t maxFid)
 Tell the dictionary what the probable maximum fid in the data dictionary may be. More...
 
virtual void writeToFile (const char *fileName)
 Write the data dictionary to a file. More...
 
virtual void populateFromFile (const char *fileName)
 Populate a dictionary from the contents of a file. More...
 

Public Attributes

DictionaryImpl * mPimpl
 

Detailed Description

The MamaDictionary class maps field identifiers (FIDs) to human readable strings.

Incoming MamaMsgs may contain FIDs but no field names. The dictionary allows applications to determine the name associated with a given FID. On some platforms, the inbound messages may have names, but not fids in which case the dictionary can map names to fids.

Constructor & Destructor Documentation

§ ~MamaDictionary()

virtual Wombat::MamaDictionary::~MamaDictionary ( )
virtual

§ MamaDictionary()

Wombat::MamaDictionary::MamaDictionary ( void  )

Member Function Documentation

§ create()

virtual void Wombat::MamaDictionary::create ( MamaQueue queue,
MamaDictionaryCallback callback,
MamaSource source,
int  retries = MAMA_DEFAULT_RETRIES,
double  timeout = MAMA_DEFAULT_TIMEOUT,
void *  closure = NULL 
)
virtual

Create a dictionary subscription.

The caller supplied DictionaryCallback.onComplete will be invoked after the dictionary is fully constructed.

If there is an error creating the dictionary Mama invokes the onError callback, and the returned dictionary is not valid. In the event of a timeout, Mama invokes the onTimeout callback. This method uses the default timeout and retry values (SubscriptionBridge.DEFAULT_TIMEOUT and SubscriptionBridge.DEFAULT_RETRIES.

Parameters
queueThe mama queue.
callbackThe dictionary callback.
sourceThe dictionary source. Depends upon feed handler configuration. See feed handler documentation for details
timeoutThe timeout in seconds.
retriesThe number of times to retry before failing.
closureThe caller supplied closure.

§ getFeedName()

virtual const char* Wombat::MamaDictionary::getFeedName ( )
virtual

Return the dictionary source feed name.

Parameters
dictionaryThe dictionary.
Returns
the feed name

§ getFeedHost()

virtual const char* Wombat::MamaDictionary::getFeedHost ( )
virtual

Return the dictionary source feed host.

Parameters
dictionaryThe dictionary.
Returns
the feed host

§ getFieldByFid() [1/2]

virtual MamaFieldDescriptor* Wombat::MamaDictionary::getFieldByFid ( mama_fid_t  fid)
virtual

Return the field with the specified field FID.

This method is very efficient.

Parameters
fidThe field id.
Returns
The field.

§ getFieldByFid() [2/2]

virtual const MamaFieldDescriptor* Wombat::MamaDictionary::getFieldByFid ( mama_fid_t  fid) const
virtual

Return the field with the specified field FID.

This method is very efficient.

Parameters
fidThe field id.
Returns
The field.

§ getFieldByIndex() [1/2]

virtual MamaFieldDescriptor* Wombat::MamaDictionary::getFieldByIndex ( size_t  index)
virtual

Return the field with the corresponding zero based index.

This method is O (N) with respect to the size of the dictionary.

Parameters
indexThe index.
Returns
The field.

§ getFieldByIndex() [2/2]

virtual const MamaFieldDescriptor* Wombat::MamaDictionary::getFieldByIndex ( size_t  index) const
virtual

Return the field with the corresponding zero based index.

This method is O (N) with respect to the size of the dictionary.

Parameters
indexThe index.
Returns
The field.

§ getFieldByName() [1/2]

virtual MamaFieldDescriptor* Wombat::MamaDictionary::getFieldByName ( const char *  name)
virtual

Return the field with the specified name.

If there is more than one field with the same name, the one with the lowest field id is returned.

Parameters
nameThe name of the field.
Returns
The field with the specified name or null if there is no such field.

§ getFieldByName() [2/2]

virtual const MamaFieldDescriptor* Wombat::MamaDictionary::getFieldByName ( const char *  name) const
virtual

Return the field with the specified name.

If there is more than one field with the same name, the one with the lowest field id is returned.

Parameters
nameThe name of the field.
Returns
The field with the specified name or null if there is no such field.

§ getMaxFid()

virtual mama_fid_t Wombat::MamaDictionary::getMaxFid ( void  ) const
virtual

Return the highest field identifier.

Returns
The highest FID.

§ getSize()

virtual size_t Wombat::MamaDictionary::getSize ( void  ) const
virtual

Return the number of fields in the dictionary.

Returns
The number of entries in the dictionary.

§ hasDuplicates()

virtual bool Wombat::MamaDictionary::hasDuplicates ( void  ) const
virtual

Return true if there are multiple fields with the same name.

Returns
true if there are duplicates.

§ getCallback()

virtual MamaDictionaryCallback* Wombat::MamaDictionary::getCallback ( void  ) const
virtual

Return the callback.

See also
MamaDictionaryCallback
Returns
The callback

§ setCallback()

virtual void Wombat::MamaDictionary::setCallback ( MamaDictionaryCallback callback)
virtual

Set the callback to receive notifications when creation is complete or an error occurs.

Parameters
callbackThe callback.

§ getDictC() [1/2]

virtual mamaDictionary Wombat::MamaDictionary::getDictC ( )
virtual

Return the underlying C mamaDictionary.

§ getDictC() [2/2]

virtual const mamaDictionary Wombat::MamaDictionary::getDictC ( ) const
virtual

Return the underlying C mamaDictionary.

§ getClosure()

virtual void* Wombat::MamaDictionary::getClosure ( void  ) const
virtual

Return the closure for the dictionary.

Returns
the closure.

§ getDictionaryMessage()

virtual MamaMsg* Wombat::MamaDictionary::getDictionaryMessage ( ) const
virtual

Returns a MamaMsg representing the data dictionary.

This message can be published or used to create a new MamaDictionary object. A new MamaMsg is created for each invocation of the method. It is the responsibility of the caller to delete the message when no longer needed.

Returns
Pointer to a new MamaMsg for the dictionary.

§ buildDictionaryFromMessage()

virtual void Wombat::MamaDictionary::buildDictionaryFromMessage ( MamaMsg msg)
virtual

Recreate a data dictionary from the MamaMsg supplied.

The MamaMsg is copied and can therefore be deleted after the method has returned.

Parameters
msgReference to a MamaMsg representing a data dictionary.

§ createFieldDescriptor()

virtual MamaFieldDescriptor* Wombat::MamaDictionary::createFieldDescriptor ( mama_fid_t  fid,
const char *  name,
mamaFieldType  type 
)
virtual

Add a new field descriptor to a dictionary.

New fields can be added to an existing dictionary obtained from the MAMA infrastructure. This function can also be used to manually build a data dictionary.

Parameters
fidThe fid for the new field descriptor.
nameThe name for the new field descriptor.
typeThe type for the new field descriptor.

§ setMaxFid()

virtual void Wombat::MamaDictionary::setMaxFid ( mama_size_t  maxFid)
virtual

Tell the dictionary what the probable maximum fid in the data dictionary may be.

This is not necessary but will aid performance for manually creating a new dictionary or adding new fields to an existing dictionary.

Calling this function ensures that there is capacity in the dictionary for field descriptors with fids up to the maximum specified.

Fields with fids greater than specified can be added to the dictionary but this will incur the overhead of allocating more memory and copying dictionary elements.

Parameters
maxFidThe probable maximum fid being added to the dictionary.

§ writeToFile()

virtual void Wombat::MamaDictionary::writeToFile ( const char *  fileName)
virtual

Write the data dictionary to a file.

The dictionary will be written in the form: fid|fieldName|fieldType

Parameters
fileNameThe name of the file to serialize the dictionary to. This can be a fully qualified name, relative or a file on the $WOMBAT_PATH

§ populateFromFile()

virtual void Wombat::MamaDictionary::populateFromFile ( const char *  fileName)
virtual

Populate a dictionary from the contents of a file.

Can be used to add additional fields to an existing dictionary or to populate a new dictionary.

Parameters
fileNameThe file from which to populate the dictionary. This can be a fully qualified name, relative or a file on the $WOMBAT_PATH

Member Data Documentation

§ mPimpl

DictionaryImpl* Wombat::MamaDictionary::mPimpl