Introduction

The Universal Messaging Admin API (see the Package Documentation) allows management, configuration, audit and monitoring of all aspects of a Universal Messaging realm server.

The starting point for the Admin API is connecting to a realm. In order to connect to a realm using the Admin API, you need to ensure you are familiar with the concept of an RNAME. Once you have the RNAME that corresponds to your realm, you can then connect to the realm.

The way you connect to a realm is by constructing an nRealmNode object. The nRealmNode object is the main object you need to access all of the objects you wish to configure, monitor and manage:

String[] RNAME={"nsp://127.0.0.1:9000"};

nSessionAttributes nsa=new nSessionAttributes(RNAME);

nRealmNode realm = new nRealmNode(nsa);

Access to resources on a Universal Messaging realms, or indeed objects in a multi Universal Messaging realm server namespace, is based on a simple tree structure, where the nRealmNode is the root of the tree. All nodes within the tree are subclasses of a base class nNode. From the root, it is possible to obtain references to all child nodes. Child nodes may be other realm nodes, containers (folders containing other realms, channels etc), channels and queues.

For example, to obtain an enumeration of all child nodes within a realm node, simply call the following:

From this enumeration you can then perform operations on the child nodes. For example, if you have a realm with 1 channel and 1 queue, and wanted to find the number of events currently on each, the following code would do that:

Example: Finding out how many events are on a channel / queue

while (children.hasMoreElements()) {
nNode child = (nNode)children.nextElement();
if (child instanceof nLeafNode) {
nLeafNode leaf = (nLeafNode)child;
System.out.println("Leaf node contains "+leaf.getCurrentNumberOfEvents());
}
}

while (children.MoveNext()){
nNode child = (nNode)children.Current;
if (child is nLeafNode) {
nLeafNode leaf = (nLeafNode)child;
Console.WriteLine("Leaf node contains "+leaf.getCurrentNumberOfEvents());
}
}

void searchNodes(fSortedList nodes)
for (fSortedList::iterator iterator = nodes.begin(); iterator != nodes.end(); iterator++)
{
nNode *pNode = iterator->second;
int type = pNode->getType ();

if (type == fBase::LEAFNODE)
{
printf("Leaf node contains %ll events",pNode->getCurrentNumberOfEvents());
}
}
}

The namespace structure is dynamic and is managed asynchronously for you, so as and when objects are created, deleted modified, stopped or started, the namespace will manage those state changes and keep the structure up to date automatically.

As well as the namespace nodes, there are also other objects that can be obtained from the nodes but which are not part of the namespace tree structure.

For example, from an nRealmNode it is possible to obtain the following objects:

nClusterNode - The cluster node that this realm may be part of, allowing the administration of Universal Messaging realm clusters

nACL - The realm acl object (see About Realm ACL Permissions), allowing control of the ACL permissions (see Access Control Lists)

nInterfaceManager - The realm interface manager, allows me to add, remove, stop, start interfaces on a realm (see Interfaces)

nConfigGroup - an enumeration of these corresponds to all configuration (see Config) and tuning parameters for a given realm.

From an nLeafNode which could be a channel or a queue, the following objects are available:

nACL - The leaf node acl object, allows me to control acl permissions (see About Channel ACL Permissions) for resources

As well access to the channel resources as described above, there are also many monitoring tools available to developers that provide information asynchronously as and when events occur on a realm. This can be extremely useful in ongoing real time management of one or more Universal Messaging Realm servers.

For example, for a realm node you can provide listeners for the following :

Connections - get notified as new connections (see Connection Information) to the realm occur, showing connection information

Creation / Deletions / Stop / Start - get notified when new objects are created, deleted, modified, stopped or started (see nRealmNode) (for example new channels being created, acls being changed etc)

State Changes - get notified when changes occur to any of the objects in the namespace (see nLeafNode), such as events being published / consumed. All updates are asynchronously received from the realm server and the API manages those changes for you.

Audit / Logging - when security or state changes occur, get notified of audit events, as well as remotely receiving log file information from the server.

The following sections in this guide will work through in more detail, each of what has been discussed above.