![]() |
![]() |
|
|
Using Naming
Naming is a powerful feature that enables BEA MessageQ applications to identify message queues by name whether they reside on the local system or on another system on the BEA MessageQ message queuing bus. Naming also allows applications to bind permanent and temporary queues to names at runtime.
Application developers use the BEA MessageQ naming feature to separate their applications from the underlying BEA MessageQ environment configuration. By referring to message queues by name in their applications, developers do not have to modify their applications when the BEA MessageQ environment configuration changes. A name can also be associated with a Multipoint Outbound Target (MOT) address when broadcasting messages.
The following sections describe:
Before you can use naming, you need to understand the following key concepts in using BEA MessageQ naming:
The BEA MessageQ naming feature enables applications to refer to message queues by name. These names are also called queue references. The queue reference and its associated queue address must be defined to BEA MessageQ, either statically in the group configuration file, or dynamically using the pams_bind_q function. The pams_locate_q function performs the name-to-queue address translation at runtime.
When a name or queue reference is defined it is assigned a scope. Names can be assigned a "group-wide" scope to enable the name to be used by any application running in that message queuing group (local queue reference). Names can be assigned "bus-wide" scope to enable any application on the message queuing bus to refer to the queue by name (global queue reference).
What is a Name Space?
A name space is the repository where names and their associated queue addresses are stored. When an application refers to a queue by name, BEA MessageQ must look up the name in the name space to find its associated queue address in order to send a message to the named queue.
BEA MessageQ uses three levels of name spaces: process, group, and bus. Names are stored in the group- or bus-wide name space whether their configuration scope defines a local or global queue reference. The process name space is an application cache used to improve performance. Names can exist in one or all three of the name spaces. However, they are defined only in one of these spaces and can be cached at different levels. Users can bypass caching when they use pams_locate_q if they favor accuracy over performance.
When a group starts up, it creates the group-wide name space and populates it with entries defined in the %QCT and %GNT sections of the group initialization file. In addition, entries configured in the %QCT and %GNT sections with a global scope are updated in the bus-wide name space. In order to use bus-wide naming, you must configure your environment to use this BEA MessageQ feature.
BEA MessageQ offers two types of name spaces:
The Naming Agent is the BEA MessageQ process that accesses and manages the BEA MessageQ bus-wide name space. Users configure groups to decide whether a group hosts or remotely accesses a Naming Agent. When a group starts, it launches the Naming Agent, if it is hosted by this group.
When a group starts up, the BEA MessageQ startup procedure requests the Naming Agent to update all entries in the initialization file that have a global scope.
Applications do not access the bus-wide name space directly; when an application uses a global queue reference, it is the Naming Agent that looks up the name in the bus-wide name space and returns the queue address to the application.
Configuring Bus-Wide Naming
The use of group-wide naming requires no special configuration steps because the process-level name space is created by attaching to the BEA MessageQ message queuing bus and the group-wide name space is created by the group control process. To use local (group-wide) naming, configure queue names in the Queue Configuration Table (%QCT) or the Group Name Table (%GNT) section of the group initialization file. When the group starts up, BEA MessageQ automatically creates the group name space. It creates the process name space when an application attaches to the message queuing bus.
To enable your applications to use global (bus-wide) naming, you must perform additional configuration steps. First, you must decide the group or groups in which the naming agent will run. BEA MessageQ allows you to specify a main group and an alternate group to run the Naming Agent. The BEA MessageQ Naming Agent is the BEA MessageQ Server that maintains the namespace for name-to-queue address translations and performs the runtime queue lookup when an application refers to a queue by name.
The %NAM section of the group initialization file enables you define the group or groups in which the Naming Agent process will run. BEA MessageQ allows the definition of two naming agents for each message queuing bus. When BEA MessageQ starts each group, it looks in this section of the initialization file to decide whether to start a naming agent for the group. For groups that do not run a Naming Agent, BEA MessageQ uses the information in the %NAM section to direct requests to the Naming Agent. Groups must have a cross-group connection to the groups in which the Naming Agent runs.
To use global naming, you must create a namespace on the nodes on which the Naming Agents will run. BEA MessageQ enables users to configure two Naming Agents to support global messaging for the environment. In order to allow the second Naming Agent to form a backup for the first, both Naming Agents must be configured to use the same name space. Therefore, when you configure your name space for use by two Naming Agents that run on different systems, it must use a shared file system that is accessible to both Naming Agents.
To use a global name, at least some portion of the path name must be specified. Path information can be supplied by the application, or you can use the DEFAULT_NAMESPACE_PATH parameter in the %PROFILE section of the group initialization file in order to create and maintain path information for global names. For global naming to function properly, this parameter must be set to the same value for all groups in which applications are designed to access the same name space. When the naming agent is enabled in the group initialization file, a file uid.dnf is created in the DEFAULT_NAMESPACE_PATH directory which contains the global names. The following syntax shows how to set the default namespace to be created and maintained in the name space.
Use the Queue Configuration Table (%QCT) or the Group Name Table (%GNT) of the group initialization file to create static or dynamic definitions for global names as follows:
For a detailed description of how to configure your environment and develop applications to use global naming, refer to the installation and configuration guide for your platform.
How Applications Use Naming
Queues and local queue references exist in groups, which exist in buses. Global queue references can exist anywhere in the bus-wide name space. Applications in all groups can bind and look up global queue references.
The set of directory names from the root of the hierarchy to where the queue is defined is called its path. The path plus the queue's name is called its pathname. A name must be unique within its directory. Thus, any queue can be uniquely identified by its pathname.
Queues and local queue references are always identified by their names. A global queue reference must be identified by its pathname. However, it can be identified by its name only if its path is the group's DEFAULT_NAMESPACE_PATH. (The DEFAULT_NAMESPACE_PATH is set in the %PROFILE section of the group initialization file.)
The following sections describe:
Specifying Names and Pathnames
BEA MessageQ applications can be developed to be independent of the bus-wide name space implementation for a particular environment. This means that no coding changes are required if the application environment initially uses the BEA MessageQ lightweight name space and migrates to a heavy weight name space at a later time.
Names are specified in BEA MessageQ applications in one of three ways:
For detailed information on how to specify path names and file names, refer to the installation and configuration guide for the platform that you are using.
Attaching and Locating Queues
An application may only read messages from queues in its own group. To read from a queue, an application must attach to the queue using the pams_attach_q function. For a permanent queue, it must identify the queue by its name, its address, or a queue reference. For a temporary queue, the attach operation creates the queue and assigns it an address.
An application can send messages to a queue in its own group and to queues in other groups. When sending a message, the target queue is always identified by its address. An application can directly code in the address, or it can use the pams_locate_q function to derive the queue's address from its name or queue alias. When pams_locate_q is used with pams_put_msg, applications can remain separate from the details of system configuration because they are able to obtain the physical address of the target queue at runtime.
Static and Dynamic Binding of Queue Addresses
BEA MessageQ offers two approaches to associating a queue reference (also called a queue name) with a queue address: static and dynamic. Static binding refers to associating a queue name with a queue reference using the queue configuration table (%QCT section) and the group name table (%GNT section) in the group initialization file. Static binding creates the association when the group starts up.
Dynamic binding refers to the use of the pams_bind_q to associate a queue name with a queue address after the application starts up. With dynamic binding, you can write applications that dynamically "sign up" to service a queue at runtime. This means that your application can access a service without having to be aware that its normal host computer is down and that the service is being provided from another host computer. An application does this by dynamically associating a queue address to a queue reference at run-time.
The following sections describe:
How Dynamic Binding of Queue Addresses Works
Dynamic binding of queue addresses allows you to share queue names with any application attached to the message queuing bus. An application can attach to a queue in a group and bind this queue to a name into the bus-wide name space so that an application in another group can locate this queue in the bus-wide name space and send messages to it.
BEA MessageQ provides the pams_bind_q function, which associates a queue address to a queue name at runtime. The name_space_list argument in the pams_attach_q and pams_bind_q functions identify the scope of the queue name and controls cache access.
How Caching and Binding Work
When an application process locates a name for the first time, it is cached in the process name space. If the name is for a global queue reference, it is also cached in the group name space. Conversely, later lookups can fetch the name from the "nearest" location that holds the name. For example, suppose APP1 in a group locates gqref1. This causes gqref1 to be cached in APP1's process name space and in the group. Also, suppose APP2 in this group locates gqref1. Since APP1's process cache is invisible to APP2, APP2 will fetch gqref1 from the group.
When an application process deletes a queue that is bound to a reference or when it binds a reference to a new address, BEA MessageQ automatically updates the applications process cache, the name's entry in the group, and (if this is a global queue reference), the global name space also. However, other places where this queue is cached are not updated.
When your application detaches or exits from a queue that was bound to a name, BEA MessageQ unbinds the queue before exiting or detaching.
Examples of Static and Dynamic Binding
You can code your application to use either static or dynamic binding of queue addresses. Use static binding if the queue that your application attaches to is not going to change its address (for example, a permanent queue). Otherwise, if the queue that your application needs may change (for example, if the queue is temporary, or if the application runs in different groups), code your application to use dynamic binding of the queue address.
When coding, keep in mind that there are two name-based queue identification styles that you can use. They are as follows:
Client for Style 1 (Static Binding)
Listing 4-1 is a pseudocode fragment showing static binding of a queue address for a client.
Listing 4-1 Client Style Static Binding
pams_locate_q("gqref1", q_address,
[PSEL_TBL_PROC, PSEL_TBL_GRP, PSEL_TBL_BUS] )
loop:
build request message
putloop:
status = pams_put_msg(q_address)
if status is error,
print descriptive error
pause and goto putloop,
or exit program as desired
goto loop
Client for Style 2 (Dynamic Binding)
Listing 4-2 is a pseudocode fragment showing dynamic binding of a queue address for a client. In this example, when an error occurs, the client attempts to see if a new server has signed up to provide this service. Note that it does not use the cache when it refinds gqref1 because it wants to see the binding established by the new server, not the out-of-date cached binding.
Listing 4-2 Client Style Dynamic Binding
pams_locate_q("gqref1", q_address,
[PSEL_TBL_PROC, PSEL_TBL_GRP, PSEL_TBL_BUS]
)
loop:
build request message
putloop:
status = pams_put_msg(q_address)
if status is error then
pams_locate_q("gqref1", q_address1, [PSEL_TBL_BUS])
if q_address not q_address1 then
q_address = q_address1
goto putloop
else pause and goto putloop, or exit program as desired
Server for Style 1 (Static Binding)
Listing 4-3 is a pseudocode fragment showing static binding of a queue address for a server.
Listing 4-3 Server Style Static Binding
pams_attach_q("gqref1", q_address, PSYM_ATTACH_BY_NAME,
[PSEL_TBL_PROC, PSEL_TBL_GRP, PSEL_TBL_BUS])
loop:
pams_get_msg(q_address)
process request and reply
goto loop
Server for Style 2 (Dynamic Binding)
Listing 4-4 is a pseudocode fragment showing dynamic binding of a queue address for a server. In this example, the server attaches to a queue and then tries to make this queue the provider of the gqref1 service. However, if another server is already providing the service, the program exits.
Listing 4-4 Server Style Dynamic Binding
pams_attach_q(any attach options, q_address)
status = pams_bind_q("gqref1", q_address, [PSEL_TBL_BUS])
if status = "queue reference already bound to a queue"
then exit program
loop:
pams_get_msg(q_address)
process request and reply
goto loop
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|