Introduction To Universal Messaging Administration API (nAdminAPI)
Getting Started
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);
Universal Messaging namespace
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, queues and P2P services.
For example, to obtain an enumeration of all child nodes within a realm node, simply call the following:
Java:
Enumeration children = realm.getNodes();
C#:
System.Collections.IEnumerator children = realm.getNodes();
C++:
fSortedList nodes = pNode->getNodes();
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
Java:
while (children.hasMoreElements()) {
nNode child = (nNode)children.nextElement();
if (child instanceof nLeafNode) {
nLeafNode leaf = (nLeafNode)child;
System.out.println("Leaf node contains "+leaf.getCurrentNumberOfEvents());
}
}
C#:
while (children.MoveNext()){
nNode child = (nNode)children.Current;
if (child is nLeafNode) {
nLeafNode leaf = (nLeafNode)child;
Console.WriteLine("Leaf node contains "+leaf.getCurrentNumberOfEvents());
}
}
C++:
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.
Management / Configuration / Security
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
nInterfaceManager - The realm interface manager, allows me to add, remove, stop, start
interfaces on a realm nSchedulerManager - the scheduler manager allows me to control
scheduled tasks on the realm
nConfigGroup - an enumeration of these corresponds to
all configuration 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 for resources
nJoinInfo - All join information associated with a channel or queue
Monitoring
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 :
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.
