Bridge Incorporation Guidelines

The purpose of this document is to clarify the process by which a newly developed bridge may be incorporated into OpenMAMA. This includes both the actual code changes required as well as the submission process.

Submission Guidelines

• Enumeration requests are submitted to the OpenMAMA-Dev mailing list. This request should contain the enum and enum value requested, and in the case of middleware requests, the string also.
• Along with the information above, a short description of the intended use of the enumeration should also be included. It remains the right of the code maintainer to deallocate enumerations and make corresponding changes to the OpenMAMA source code if it is felt that the intention of the allocation was not that of participation in the OpenMAMA community.
• After receiving a reply confirming the allocation of enumerations, a patch must be submitted (see [[Submission Process]]) which makes the changes to OpenMAMA source code implementing the enumerations allocated.
• This patch submission must be completed within a month of receiving the confirmation of the enumeration allocation. If this is not the case the enumeration will be come available for allocation to the next request submitted to the mailing list.

Code Integration

Middleware

Currently, bridge enumerations are allocated on a first come first served basis although in the future it is intended that middleware bridges will be loaded dynamically, making the enumerations deprecated. The currently allocated enumerations are shown below.

Required Middleware Changes

Note: The example changes below have deliberately limited lists of current enums. This is intentional to improve readability. Please consult the full table of enums above to check if the enum you wish is available.

In order to incorporate a middleware bridge into OpenMAMA, it must be allocated an enumeration. This is done through the modification of middleware.h and middleware.c:

middleware.h changes:

typedef enum mamaMiddleware_ { 
MAMA_MIDDLEWARE_WMW = 0; 

MAMA_MIDDLEWARE_LBM = 1; 

MAMA_MIDDLEWARE_TIBRV =3; 

...
+ MAMA_MIDDLEWARE_<NEW> = 10; 

MAMA_MIDDLEWARE_MAX = 11; 

MAMA_MIDDLEWARE_UNKNOWN = 99; 

} mamaMiddleware;

As shown above, the chosen enumeration must be added to typedef enum mamaMiddleware_ and MAMA_MIDDLEWARE_MAX incremented. In a similar manner the bridge being added must also be included in mamaMiddleware_convertFromString and mamaMiddleware_convertToString in middleware.c (see diff below). Please note that it is preferred that the string used for a new middleware be less than 10 characters and in block capitals.

middleware.c changes:

mamaMiddleware mamaMiddleware_convertFromString (const char* str) 
{ 
if (!str) 
    return MAMA_MIDDLEWARE_UNKNOWN; 

if (strcasecmp (str, "wmw") == 0) 
    return MAMA_MIDDLEWARE_WMW; 

if (strcasecmp (str, "lbm") == 0) 
    return MAMA_MIDDLEWARE_LBM; 

if (strcasecmp (str, "tibrv") == 0) 
    return MAMA_MIDDLEWARE_TIBRV; 

if (strcasecmp (str, "avis") == 0) 
    return MAMA_MIDDLEWARE_AVIS; 
...

+ if (strcasecmp (str, "<new>") == 0)
+   return MAMA_MIDDLEWARE_<NEW>;

return MAMA_MIDDLEWARE_UNKNOWN; 

const char* mamaMiddleware_convertToString (mamaMiddleware middleware) { 

switch (middleware) { 
    case MAMA_MIDDLEWARE_WMW: 
        return "wmw"; 
    case MAMA_MIDDLEWARE_LBM:
        return "lbm"; 
    case MAMA_MIDDLEWARE_TIBRV:
        return "tibrv"; 
    case MAMA_MIDDLEWARE_AVIS: 
        return "AVIS"; 
...
+    case MAMA_MIDDLEWARE_<NEW>: 
+        return "<MIDDLEWARE>";
    default: 
        return "unknown"; 
    }
}

Payload

Again, the payload enumerations are allocated on a first come first served basis . The currently allocated payload enumerations are shown below:

Required Payload Changes

Note: The example changes below have deliberately limited lists of current enums. This is intentional to improve readability. Please consult the full table of enums above to check if the enum you wish is available.

In a manner similar to that of middleware bridges, payload enumerations are set through modification of msg.h and msg.c: Again, the chosen payload enumeration must be added to msg.h as shown above and the new payload added to mamaPayload_convertToString within msg.c.

msg.h changes:

typedef enum mamaPayloadType_ { 
    MAMA_PAYLOAD_WOMBAT_MSG = ’W’,
    MAMA_PAYLOAD_TIBRV = 'R',
    MAMA_PAYLOAD_FAST = 'F',
    ... 
+    MAMA_PAYLOAD_<NEW> = '<M>', 
    MAMA_PAYLOAD_UNKNOWN = 'U'
} mamaPayloadType;

msg.c changes:

const char* 
mamaPayload_convertToString (mamaPayloadType payloadType) { 
    switch (payloadType) { 
        case MAMA_PAYLOAD_WOMBAT_MSG: 
            return "WombatMsg"; 
        case MAMA_PAYLOAD_TIBRV: 
            return "TIBRV"; 
        case MAMA_PAYLOAD_FAST: 
            return "FAST";
...
+        case MAMA_PAYLOAD_<NEW>: 
+            return "<PAYLOAD>"; 
        default: 
            return "unknown"; 
    } 
}

Once these changes are made and committed to your local Git repository, you will need to submit them. For information on submitting changes to OpenMAMA see [[here|Submission Process]].