1.1.1. Assignment Methods

UM provides four basic methods for using configuration options to set attributes:

• XML configuration files - customized defaults used during object creation

• plain text configuration files - a different manner of customized defaults, also used during object creation

• attributes objects - application-specific option values used during object creation

• function calls (setopt) - used after object creation

Figure 1-1 shows the different ways option values are stored and assigned before, during, and after primitive object creation (primitive objects being sources, receivers, wildcard receivers, event queues, contexts, or HFX objects). The ultimate result is a primitive object created with the desired values residing in current attributes.

The initial default attributes is the set of factory defaults residing in UM. The current default attributes are derived from the initial default attributes, but modified by option setting in the plain text configuration file. This is the starting point for all created primitive objects.

An instantiated primitive object has its attribute settings held in current attributes, which are influenced by the current default attributes, the XML config table, and, if applicable, any settings stored in a custom attributes objects.

An XML configuration file can pass its setting to an object being created in two ways: by directly populating UM's XML config table, or by creating a custom attributes object with its settings.

1.1.2. Assignment Flow

The above diagram implies, but does not fully explain, the flow of attribute value assignment that UM performs when an application creates a primitive object. This flow is described below, and is important in understanding how and when default values are overridden:

1. If applicable, copy plain text configuration file values to current default attributes.

2. Start creating object.

3. Custom attributes object(s) created/populated (if applicable).

4. If lbm_*_create() has a NULL attr, copy current default attributes into current attributes. Otherwise, copy custom attributes object values into current attributes.

5. Read applicable options from the XML config table into the current attributes. Do not overwrite options set with lbm_config(), or lbm_*_attr_setopt(), which were tagged when modified.

6. Finish object creation.

7. current attributes can be changed further (only certain options) via lbm_*_setopt().

1.1.3. Definitions

Before discussing how UM options can be set, some terminology is in order.

• Option - A single configuration item that controls some aspect of UM operation. An option typically resides in a configuration file, but can also be assigned a value via a function call. We use options to assign values to an object's attributes.

• Attribute - An operational characteristic of an object. An attribute's value is set by an option, hence, there is a one-to-one correspondence between options and attributes. (Note: This use of the term "attribute" is unrelated to, and not to be confused with, "attribute" in XML syntax. In this document, we refer to the latter as "XML attribute".)

• XML attribute - See above. In XML syntax, XML attributes are parameters for XML elements.

• Custom attributes object A UM object that contains custom attribute values (set by options) for a specific UM object. Separate (and multiple) sets of attributes can exist for each application, though only one can be used when creating a primitive object.

• Initial default attributes - The default attributes values built into UM. UM and your applications use these if you have not set any options for the attributes.

• Primitive object - Specifically, an object that is a source, receiver, wildcard receiver, event queue, context, or HFX object.

• Configuration file - This comes in two types: XML and plain text. Configuration files contain assigned values for options, but the different types are read/copied at different times during the creation of an object.

• XML config table - Contains option values that are read from the XML configuration file.

• Current default attributes - The attributes values used to create an object in the absence of custom attributes values.

• Current attributes - The attribute values for an instantiated UM object that control the current operation of that object.

• Scope - The type of object to which an option can apply. Possible scopes are context, source, receiver, wildcard_receiver, event_queue, and hfx.

1.1.4. Which Method Should I Use?

For the four basic assignment methods listed above, following are some scenarios where specific methods are selected.

• To change a default option value and apply it to all objects you create, call lbm_config() for one or more configuration files. For example, to use LBT-RM rather than TCP for all sources, create a plain text configuration file containing

  source transport LBTRM
  

  and pass its file name to lbm_config().

  Note: The C API offers functions lbm_*_attr_create_default() to change a current default value back to the initial (factory) default value. No such corresponding method exists for the Java or .NET APIs.

• To customize specific options before an object is created for a specific object instance, use a custom attributes object. Also, you can assign XML data to the XML config table directly from your application via lbm_config_xml_string().

• To create sets of custom values to be used when creating primitive objects, call lbm_config_xml_file() and specify an XML configuration file. This is useful for setting specific default options on a per-topic or per-context basis, which cannot be done with a plain text configuration file. For an example where a sending application uses specific options and values, create an XML configuration file with the application's name (optional) that specifies those options and values. Then pass the XML file name and application name to lbm_config_xml_file().

• To change an option after an object is created, modify the current attributes for the object. (Note that many options cannot be changed after an object has been created.)

These methods can be used in combination. Figure 1-1 illustrates the relationships between attributes and the various UM API function calls that affect them.

1.1.5. Configuration Files

There are two types of UM Configuration files:

• Plain Text Configuration Files

• XML Configuration Files

You can read Configuration files either by function call, or automatically upon application launch by specifying a file name in an environment variable. See Figure 1-1 and Assignment Flow for details on how these options replace or override default values.