Solstice Enterprise Manager 4.1 Developing Java Applications

Chapter 4

Using the Java Topology API

The Java Topology API defines the classes and methods which allow you to create applications that perform topology management operations without learning the details of the MIT naming tree. This chapter covers the important aspects of using the API and provides detailed examples. For more information about the API, refer to Java API Reference and C++ API Reference.

The following topics are covered in this chapter:

• Section 4.1 Overview
• Section 4.2 Differences Between the C++ and Java Topology APIs
• Section 4.3 Performing Node Operations
• Section 4.4 Performing Type Operations
• Section 4.5 Performing Agent Operations

4.1 Overview

The Java Topology API allows you to create topology nodes to logically model managed objects in their management environments. Each topology node can correspond to one or more agents.

You can create applications using the Topology API. The following figure shows a GUI-based viewer which is an example of such an application. A GUI-based viewer, allows you to visualize interconnection among devices in a network.

FIGURE 4-1   Sample Viewer Application

4.1.1 Topology Management Tasks

The Java Topology API allows you to perform the following topology management tasks:

• Node operations
• Type operations
• Agent operations

These tasks could be performed using the following main classes of the Java Topology API:

• The EMTopoNode class allows you to perform the different operations on MOIs.
• The EMTopoType class allows you to define node types.
• The EMCmipAgent, EMRpcAgent, and EMSnmpAgent classes allow you to perform agent operations.

4.2 Differences Between the C++ and Java Topology APIs

The Java Topology API is very similar to the C++ Topology API. For example, the main classes are still EMTopoNode, EMTopoType, EMCmipAgent, EMSnmpAgent, and EMRpcAgent in the Java Topology API. The other classes are helper classes. The following differences exist:

• The Java Topology API contains more classes than the C++ Topology API since almost all the enum and struct types in the C++ Topology API have classes as their equivalent in Java Topology API. For example, the EMTopoNode class in the C++ Topology API has an enum called Attribute that is represented as a class (EMTopoNodeAttribute) in the Java Topology API.
• The following methods of the EMTopoPlatform class in the C++ Topology API are available in the EMTopoNode class of the Java Topology API (instead of EMTopoPlatform class).
  
  
  • find_nodes_by_name
    
  • find_nodes_by_type
    
  • find_nodes_by_managed_object
    
  • find_mos_by_nodes
    
  • load_nodes_in_view

  These equivalent methods in the Java Topology API have the following names:

  
  
  • findNodesByName
    
  • findNodesByType
    
  • findNodesByManagedObject
    
  • findMOsByNodes
    
  • loadNodesInView

    ---

    Note – These methods provide support for the actions topoNodeGetByName, topoNodeGetByType, topoNodeGetByMO, topoGetMODataByNodeList, and topoNodeChildAttrsByView that are supported by the topoNodeDB GDMO object class.

    ---

• In the C++ Topology API, the EMPpcAgent class has an attribute called schemas, but in the Java API, the same attribute is called INFOS.

For more detailed information about the C++ Topology API, especially on which attributes are mandatory and settable for each persistent object, refer to Chapter 8 in C++ API Reference. And for more detailed information about the Java Topology API, refer to Chapter 4 in Java API Reference.

4.3 Performing Node Operations

The EMTopoNode class represents a topology node, which is the unit of topology management in Solstice EM. It provides methods for creating, deleting, loading, changing, and comparing topology nodes.

Using the EMTopoNode class' access methods, you can get and set the name, topology type, parents, topology pathname, logical and geographical location, and associated managed objects and their corresponding CMIP, RPC, and SNMP agent objects among other attributes. The EMTopoNode class also provides an event listening mechanism to notify clients when a topology node has been created, deleted, or has had one or more attributes changed.

This section covers three types of node operations that you can perform using the methods of the EMTopoNode class:

• Creating nodes
• Destroying nodes
• Changing node attributes

For more information about the EMTopoNode class, refer to Chapter 4 in Java API Reference and Chapter 8 in C++ API Reference.

---

Note – Before performing node operations, you must instantiate the EMTopoPlatform class.

---

4.3.1 Creating Nodes

To Create a New Topology Node in the MIS

1. Set the mandatory attributes required for creating the node.

2. Use the createWithAllAttributes or createWithSomeAttributes method to create the object in the persistent store.

---

Note – The createWithAllAttributes method only uses attributes that have been given a value. If the create method succeeds, the DN attribute is set with the unique identifier of the new object.

---

The following code example shows how to create a topology node.

CODE EXAMPLE 4-1   Creating a Topology Node 

import com.sun.em.api.pmi.Platform; import com.sun.em.api.topology.*; public class CreateTopoNode { static void usage() { System.err.println("Usage:"); System.err.println("CreateTopoNode <jma-servername> <mis-name> <username> <password> <node-name> <typename> <parentname>"); System.exit(-1); } public static void main(String[] args) { if (args.length < 7) usage(); try { //Create a Platform and EMTopoPlatform: Platform platform = new Platform(args[0], args[1], args[2], args[3]); EMTopoPlatform topoPlatform = new EMTopoPlatform(platform); // Create an empty EMTopoNode in memory (not persistent yet) given //EMTopoPlatform instance EMTopoNode node = new EMTopoNode(topoPlatform); //Set attribute values (still in cache) node.setName(args[4]); node.setTypeName(args[5]); //To set mandatory attribute parents, find the parent's dn(s). // In this example, if there are more than one parent with the given name, choose the first one. EMTopoNodeDn parentDn = null; EMTopoNodeDn[] dns = EMTopoNode.findNodesByName(topoPlatform, args[6]); if (dns.length == 0) { System.err.println("No nodes found with name " + args[6]); System.exit(-1); } else { for (int i = 0; i < dns.length; i++) { // The node is qualified to be a parent only when it is a view. if (EMTopoNode.isView(topoPlatform,dns[i])) { parentDn = dns[0]; break; } } if (parentDn == null) { System.err.println("None of the nodes named \"" + args[6] + "\" are views!"); System.err.println("Aborting..."); System.exit(-1); } } EMTopoNodeDn parents[] = { parentDn }; node.setParents(parents); // Make the call to MIS to create a persistent node. node.createWithAllAttributes(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println("Created node \"" + args[4] + "\""); System.exit(-1); } }

4.3.2 Loading Node Attributes

To Get the Attribute Values of a Topology Node Object

1. Set the DN identifier.

2. Use the loadAllAttributes or loadSomeAttributes method.

Once the attribute values are loaded, they stay cached within the EMTopoNode in the API's user process memory space and remain constant even if the values change in the MIS. See the following code example.

CODE EXAMPLE 4-2   Loading Node Attributes 

import com.sun.em.api.pmi.Platform; import com.sun.em.api.topology.*; public class LoadTopoNode { static void usage() { System.err.println("Usage:"); System.err.println("ChangeTopoNode <jma-servername> <mis-name> <username> <password> <node-name>"); System.exit(-1); } public static void main(String[] args) { if (args.length < 5) usage(); try { //Create a Platform and EMTopoPlatform: Platform platform = new Platform(args[0], args[1], args[2], args[3]); EMTopoPlatform topoPlatform = new EMTopoPlatform(platform); //Find all the nodes with the name indicated by the 5th input argument, EMTopoNodeDn[] dns = EMTopoNode.findNodesByName(topoPlatform, args[4]); if (dns.length == 0) { System.err.println("No nodes found with name \"" + args[4] + "\""); System.exit(-1); } else { System.err.println("Found " + dns.length + " node(s) with name \"" + args[4] + "\""); } for (int i = 0; i < dns.length; i++) { EMTopoNode node = new EMTopoNode(topoPlatform, dns[i]); // Load the attributes from MIS node.loadAllAttributes(); System.err.println(node.toString()); } } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println("Done"); System.exit(-1); } }

There are several static methods of EMTopoNode that load multiple nodes instead of just one node:

• EMTopoNode.loadNodes
• EMTopoNode.loadNodesInBatches
• EMTopoNode.loadNodesInView

Refer to Chapter 4 in Java API Reference for more information.

4.3.3 Changing Node Attributes

To Set the Attribute Values Persistently in the MIS

1. Set the DN attribute to identify the topology node.

2. Use the setter methods to change attribute values of the node in the cache.

3. Call either storeAllAttributes or storeSomeAttributes to commit these changes persistently in the MIS.

---

Note – The storeAllAttributes method only stores attributes that have been given a value.

---

The following code example shows how to change the name of topology nodes.

CODE EXAMPLE 4-3   Changing Node Attributes 

import com.sun.em.api.pmi.Platform; import com.sun.em.api.topology.*; public class ChangeTopoNode { static void usage() { System.err.println("Usage:"); System.err.println("ChangeTopoNode <jma-servername> <mis-name> <username> <password> <old-name> <new-name>"); System.exit(-1); } public static void main(String[] args) { if (args.length < 6) usage(); try { //Create a Platform and EMTopoPlatform Platform platform = new Platform(args[0], args[1], args[2], args[3]); EMTopoPlatform topoPlatform = new EMTopoPlatform(platform); //Find all nodes with the name indicated by the 5th input argument EMTopoNodeDn[] dns = EMTopoNode.findNodesByName(topoPlatform, args[4]); if (dns.length == 0) { System.err.println("No nodes found with name \"" + args[4] + "\""); System.exit(-1); } else { System.err.println("Found " + dns.length + " node(s) with name \"" + args[4] + "\""); } for (int i = 0; i < dns.length; i++) { EMTopoNode node = new EMTopoNode(topoPlatform, dns[i]); //Set the node name to the new name, this setting is still in cache node.setName(args[5]); // we are ready to commit the change to MIS node.storeAllAttributes(); } } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println("Renamed node(s) of the name \"" + args[4] + "\" to the new name \"" + args[5] + "\""); System.exit(-1); } }

4.3.4 Destroying Nodes

To Destroy a Topology Node

1. Set the DN identifier.

2. Use the destroy method to delete the object from the MIS.

---

Caution – This is a permanent, non-reversible operation.

---

The following code example shows how to destroy a node.

CODE EXAMPLE 4-4   Destroying Nodes 

import com.sun.em.api.pmi.Platform; import com.sun.em.api.topology.*; public class DestroyTopoNode { static void usage() { System.err.println("Usage:"); System.err.println("DestroyTopoNode <jma-servername> <mis-name> <username> <password> <node-name>"); System.exit(-1); } public static void main(String[] args) { if (args.length < 5) usage(); try { //Create a Platform and EMTopoPlatform Platform platform = new Platform(args[0], args[1], args[2], args[3]); EMTopoPlatform topoPlatform = new EMTopoPlatform(platform); // Find all nodes with the name indicated by the 5th input argument EMTopoNodeDn[] dns = EMTopoNode.findNodesByName(topoPlatform, args[4]); if (dns.length == 0) { System.err.println("No nodes found with name \"" + args[4] + "\""); System.exit(-1); } else { System.err.println("Found " + dns.length + " node(s) with name \"" + args[4] + "\""); } //Create an empty EMTopoNode in cache EMTopoNode node = new EMTopoNode(topoPlatform); // delete found nodes one by one for (int i = 0; i < dns.length; i++) { node.setDn(dns[i]); // Make the call to MIS to really destory the object in persistent store node.destroy(); } } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println("Deleted node(s) of name \"" + args[4] + "\""); System.exit(-1); } }

4.3.5 Listening to Node Events

Node events include object creation, object deletion, and attribute value change events.

To Listen to Topology-Node-Related Events

1. Write a class that implements EMTopoNodeListener and define the body of its prototype methods according to your application needs.

2. Register the listener with the EMTopoPlatform object in a relevant place in your program.

The following code example shows how to listen to node events.

CODE EXAMPLE 4-5   Listening to Node Events 

import com.sun.em.api.pmi.Platform; import com.sun.em.api.topology.*; public class ListenToTopoNodeEvent implements EMTopoNodeListener { static void usage() { System.err.println("Usage:"); System.err.println("ListenToTopoNode <jma-servername> <mis-name> <username> <password>"); System.exit(-1); } // the following three method topotypes are in EMTopoNodeListener public void nodeCreated(EMTopoNodeEvent event) { // do something particular to your application System.err.println(event.toString()); } public void nodeChanged(EMTopoNodeEvent event) { // do something particular to your application System.err.println(event.toString()); } public void nodeDeleted(EMTopoNodeEvent event) { // do something particular to your application System.err.println(event.toString()); } public static void main(String[] args) { if (args.length < 4) usage(); try { // first create a Platform and EMTopoPlatform Platform platform = new Platform(args[0], args[1], args[2], args[3]); EMTopoPlatform topoPlatform = new EMTopoPlatform(platform); // create a topo node event listener ListenToTopoNodeEvent listener = new ListenToTopoNodeEvent(); // install/register the listener EMTopoNode.addEMTopoNodeListener(topoPlatform, listener); } catch (Exception e) { e.printStackTrace(); } } }

There is another type of listener (EMIndividualNodeListener) that only listens to object creation and attribute value change events of a single topology node. EMTopoNodeListener listens to events of any topology node. Refer to Chapter 4 in Java API Reference for more information.

4.4 Performing Type Operations

Type operations can be performed using the methods of the EMTopoType class. Each instance of this class represents a topology type that is used to classify topology nodes. The topology types form a hierarchy with the following base types (and their subtypes):

• Array
• Bus
• Container
• Device
• Link
• Monitor
• Sun

This section covers the following four topology type operations:

• Creating types
• Loading types
• Changing types
• Destroying types

For more information about the EMTopoType class, refer to Chapter 4 in Java API Reference.

4.4.1 Creating Topology Types

To Create a New Topology Type

1. Instantiate the EMTopoType class in the cache by providing the following two parameters:

• Platform: The object that gives your application access to a particular MIS.
• EMTopoTypeDn: The object that uniquely identifies a topology type out of the set of topology types.

2. Set at least the two mandatory attributes.

3. Use the createWithAllAttributes or createWithSomeAttributes method to create the object in the persistent store.

The following code example shows how to create a topology type.

CODE EXAMPLE 4-6   Creating Types 

public static void createType(EMTopoPlatform topoPlatform, String name, String baseTypeName) throws EMTopoException { if (topoPlatform == null) { System.err.println("topoPlatform is null"); } if (name == null) { System.err.println("name is null"); } if (baseTypeName == null) { System.err.println("baseTypeName is null"); } EMTopoTypeDn dn = new EMTopoTypeDn(topoPlatform.getLocalSystemName(),name); EMTopoType type = new EMTopoType(topoPlatform,dn); type.setBaseType(baseTypeName); type.setLayerName(baseTypeName); try { type.createWithAllAttributes(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println("Created type \""+name+"\""); }

4.4.2 Loading Topology Types

Use the loadAllAttributes or loadSomeAttributes method to load the attributes of an EMTopoType object as shown in the following code example.

CODE EXAMPLE 4-7   Loading Types 

public static void loadType(EMTopoPlatform topoPlatform,String name) throws EMTopoException { EMTopoTypeDn dn = (EMTopoTypeDn) new EMTopoTypeDn(topoPlatform.getLocalSystemName(),name); EMTopoType type = new EMTopoType(topoPlatform,dn); try { type.loadAllAttributes(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println(type.toString()); }

4.4.3 Changing Topology Types

Use the storeAllAttributes or storeSomeAttributes method to change the attribute values of a topology type persistent object as shown in the following code example.

CODE EXAMPLE 4-8   Changing Topology Types 

public static void changeType(EMTopoPlatform topoPlatform, String typeName, String layerName) { try { EMTopoTypeDn dn = (EMTopoTypeDn) new EMTopoTypeDn(topoPlatform.getLocalSystemName(), typeName); EMTopoType type = new EMTopoType(topoPlatform,dn); // set the layer name, this setting is still in cache type.setLayerName(layerName); // we are ready to commit the change to MIS type.storeAllAttributes(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } }

4.4.4 Destroying Topology Types

Use the EMTopoType destroy method to destroy topology types as shown in the following code example.

CODE EXAMPLE 4-9   Destroying Types 

public static void destroyType(EMTopoPlatform topoPlatform, String name) throws EMTopoException { EMTopoTypeDn dn = (EMTopoTypeDn) new EMTopoTypeDn(topoPlatform.getLocalSystemName(),name); EMTopoType type = new EMTopoType(topoPlatform,dn); try { type.destroy(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println("Deleted type \""+name+"\""); }

4.5 Performing Agent Operations

The Java Topology API allows you to perform operations on three types of agents as shown in the following table.

TABLE 4-1   Agent Operation Types 

Operation Type	Description
SNMP	The Java Topology API provides the EMSnmpAgent class that represents the MIS object containing configuration information for an SNMP agent. This information includes the read and write community strings, supported MIBs, and the transport address.
CMIP	The Java Topology API provides the EMCmipAgent class representing the MIS object containing configuration information for CMIP agent. This information includes the CMIP MPA hostname and port number, list of managed objects DN, network SAP, transport selector, presentation selector, session selector, and application entity title (AET).
RPC	The Java Topology API provides the EMRpcAgent class that represents the MIS object that contains configuration information for an RPC agent. This information includes the read and write community strings and supported schemas.

This section covers the following four types of agent operations:

• Creating agents
• Loading agents
• Changing agents
• Destroying agents

For more information on the classes EMSnmpAgent, EMCmipAgent, and EMRpcAgent, refer to Chapter 4 in Java API Reference.

---

Note – The following sections are based on RPC sample code. The same concepts can be applied to CMIP and SNMP agents.

---

4.5.1 Creating Agents

To Create a New RPC Agent

1. Instantiate the EMRpcAgent class in the cache by providing the following two parameters:

• Platform: The object that gives your application access to a particular MIS.
• RPCAgent: The object that uniquely identifies an RPC agent out of the set of RPC agent objects.

2. Set the agent's attributes, which are mandatory (and others if necessary).

3. Use the createWithAllAttributes or createWithSomeAttributes methods to create the object in the persistent store.

The following code example shows how to create an RPC agent.

CODE EXAMPLE 4-10   Creating Agents 

public static void createRpcAgent( EMTopoPlatform topoPlatform, String name, String getCommunityString, String setCommunityString, EMRpcAgentInfo[] infos) throws EMTopoException { EMRpcAgentDn dn = new EMRpcAgentDn(topoPlatform.getLocalSystemName(),name); EMRpcAgent rpcAgent = new EMRpcAgent(topoPlatform,dn); rpcAgent.setGetCommunityString(getCommunityString); rpcAgent.setSetCommunityString(setCommunityString); if (infos != null) { rpcAgent.setInfos(infos); } else { infos = new EMRpcAgentInfo[1]; infos[0] = new EMRpcAgentInfo("RPC Proxy - ping","granite"); rpcAgent.setInfos(infos); } rpcAgent.setAdministrativeState(EMAgentAdministrativeState.UNLOCKED); try { rpcAgent.createWithAllAttributes(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println("Created rpcAgent \""+name+"\""); }

4.5.2 Loading Agents

Use the loadAllAttributes or loadSomeAttributes method to load the attributes of an EMRpcAgent object as shown in the following code example.

CODE EXAMPLE 4-11   Loading Agents 

public static void loadRpcAgent(EMTopoPlatform topoPlatform,String name) throws EMTopoException { EMRpcAgentDn dn = (EMRpcAgentDn) new EMRpcAgentDn(topoPlatform.getLocalSystemName(),name); EMRpcAgent rpcAgent = new EMRpcAgent(topoPlatform,dn); try { rpcAgent.loadAllAttributes(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println(rpcAgent.toString()); } }

4.5.3 Changing Agents

Use the storeAllAttributes or storeSomeAttributes method to change the attribute values of an agent's persistent object as shown in the following code example.

CODE EXAMPLE 4-12   Changing Agents 

public static void changeAgent(EMTopoPlatform topoPlatform, String agentName, EMAgentAdministrativeState adminState) { try { EMRpcAgentDn dn = (EMRpcAgentDn) new EMRpcAgentDn(topoPlatform.getLocalSystemName(), agentName); EMRpcAgent rpcAgent = new EMRpcAgent(topoPlatform,dn); // Set the administrative state, this setting is still in cache rpcAgent.setAdministrativeState(adminState); // You are ready to commit the change to MIS rpcAgent.storeAllAttributes(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } }

4.5.4 Destroying Agents

Use the destroy method to destroy RPC agents as shown in the following code example.

CODE EXAMPLE 4-13   Destroying Agents 

public static void destroyRpcAgent(EMTopoPlatform topoPlatform, String name) throws EMTopoException { EMRpcAgentDn dn = (EMRpcAgentDn) new EMRpcAgentDn(topoPlatform.getLocalSystemName(),name); EMRpcAgent rpcAgent = new EMRpcAgent(topoPlatform,dn); try { rpcAgent.destroy(); } catch (Exception e) { e.printStackTrace(); System.exit(-1); } System.err.println("Deleted rpcAgent \""+name+"\""); }