AdventNet Web NMS 4 API Specification: Interface TopoAPI

Overview

Package

Class

Tree

Deprecated

Index

Help

AdventNet Web NMS 4 API Specification

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

com.adventnet.nms.topodb
Interface TopoAPI

All Superinterfaces:: CommonAPI, CommonModuleAPI, java.rmi.Remote

public interface TopoAPI
extends CommonAPI

The TopoAPI defines the methods that allows for accessing and managing ManagedObjects in the Topology database. The Topology module provides a base class, the ManagedObject (or MO), to model the Networks, Network Elements (NEs) and other entities that are to be managed. All the MOs are stored in a RDBMS and this API provides database neutral access for other modules and applications to manage those MOs.

The following are the important functionalities provided by this API,

Database operations (add, delete, update, retrieve and search MOs)
Concurrency for MOs
Controlling the Notification Engine
Configuring the Discovery Engine at run time

Database Operations

The TopoAPI provides methods for adding, deleting, updating and retrieving MOs to/from the Topology database. Each type of MO is stored in a different table, and each MO instance is stored in one row of a table. These methods operate over a database interface layer, which translates java objects to fit into RDBMS tables. The database layer can work with any JDBC compliant RDBMS.

Apart from the basic database operations, this API also provides methods which discover the devices themselves and add corresponding MOs to the database. The methods of this API supplement the add/delete/update operations to also suitably take care of the effect of those operations. For example, when a Network object is deleted, the corresponding Node and the IpAddress objects also are deleted. Importantly, the API also gives the ability to the users to control such behaviour, to specify whether or not the supplementary actions should take effect. Methods have also been provided to operate on multiple MOs, that significantly improve the efficiency of the operations. These database access methods are defined as transactions which ensure atomicity of the operations that affect more than one database table. That is, if the operation fails at any step, the changes made to the database tables from the start of the transaction are undone and the operation is abandoned.

The table below lists few important methods of this API for doing database operations,

Operations	Methods
Adding MO	`addObject(ManagedObject, boolean, boolean)` `addObjects(String, Vector)` `addNode(ManagedObject, boolean, boolean, boolean)` `addNodeToTopoDB(String, String)`
Deleting MO	`deleteObject(ManagedObject, boolean, boolean)` `deleteObjects(String,Properties)` `deleteObjectAndSubElements(String)` `deleteObjects(String,Properties,int)` `deleteObjectAndSubElements(String,int)` `removeNodeFromTopoDB(String)`
Updating MO	`updateObject(ManagedObject, boolean, boolean)` `refreshObject(ManagedObject)`
Retrieve MO	`getByName(String)` `getNet(String)` `getNode(String)` `getInterface(String)`
Search MO	`getObjectNamesWithProps(Properties)` `getObjectNamesWithProps(Properties,boolean)` `isManagedObjectPresent(String)`

Concurrency of MOs

A very important ability provided by this API is to control the concurrency of the MOs in the database. Whenever an application or a module wants to update a MO, it can lock the MO and prevent it from being updated by ohter applications or modules, until it unlocks the MO. The Web NMS, internally, locks the corresponding MO, till the time it does any update operation over it.

The table below lists the important methods for controlling the concurrency of MOs,

Methods

checkOut(String, int)

lock(ManagedObject, int, int)

unlock(ManagedObject)

Notification Engine

The Topology module has a notification engine, which is responsible for notifying the other Web NMS modules and applications about changes made to the MO database. The notification engine provides various mechanisms, and the applications can choose any of them based on the operating needs. This API provides methods through which the applications can access the notification engine.

The table below lists the various notification mechanisms and the TopoAPI methods for controlling the notification engine,

Notification Mechanism	Methods
`TopoActionListener`	`register(TopoActionListener)` `unregister(TopoActionListener)`
`TopoListener`	`addTopoListener(TopoListener)` `removeTopoListener(TopoListener)`
`TopoSubscriber`	`registerTopoSubscriber(TopoSubscriber, String)` `deregisterTopoSubscriber(TopoSubscriber)`
`TopoNotificationFilter`	`registerNotificationFilter(TopoNotificationFilter)` `unregisterNotificationFilter(TopoNotificationFilter)`

Discovery Engine Configuration

This API provides a set of methods using which the discovery engine parameters can be configured to control the behaviour of the discovery engine at run time. The configuration changes made are updated in the discovery engine configuration file (seed.file), and will be avaialable on the subsequent runs of the Web NMS server.

The following table lists the important methods that can be used for runtime configuration of the discovery engine,

Methods

setDiscoveryParameters(Properties)

getDiscoveryParameters()

setAddressRangeToDiscover(String, String, String, String)

removeAddressRangeToDiscover(String, String, String, String)

addNetwork(String, String)

dontDiscoverNetwork(String, String)

dontDiscoverNode(String, String)

getSeedFileParameters()

Accessing TopoAPI

This API extends the CommonAPI, which allows it to be accesible even from remote hosts through RMI. It also inherits various database search functionalities from the CommonAPI.

This API can be accessed either through RMI or directly from the same JVM. It is published with the RMI handle TopoAPI on the NMS server. Code within the same JVM as the NMS server can use the NmsUtil.getAPI(String) method to get the TopoAPI handle.

For secure and authentic acquisition of the TopoAPI handle, the remote applications can use the RMIAccessAPI provided by the AdventNet Web NMS Security module. With this, the applications have to first get the handle of the RMIAccessAPI (which is published with the handle RMIAccessAPI on the NMS Server) and then use the getAPI method to get the handle of TopoAPI by specifying valid username and password.

The examples below show how the TopoAPI can be accessed from the same JVM or through RMI,

// Accessing TopoAPI from the same JVM
TopoAPI topoApi = (TopoAPI) NmsUtil.getAPI ("TopoAPI");
Vector objectList = topoApi.getCompleteList ();

// Accessing TopoAPI via RMI
try
{
TopoAPI topoApi = (TopoAPI) Naming.lookup ("//[NMSServer]/TopoAPI");
System.out.println ( "Successfully got the handle for TopoAPI");
}
catch (Exception remoteException)
{
System.out.println ( "Error in getting the handle for TopoAPI");
}

Vector objectList = topoApi.getCompleteList ();

// Accessing TopoAPI via RMIAccessAPI in the NMS RMI secure mode
try
{
RMIAccessAPI rmiApi = (RMIAccessAPI) Naming.lookup ("//[NMSServer]/RMIAccessAPI");
TopoAPI topoApi = (TopoAPI) rmiApi.getAPI ("username", "password", "TopoAPI");
Vector objectList = topoApi.getCompleteList ();
}
catch (Exception remoteException)
{
System.out.println ( "Error in getting the handle for TopoAPI");
}

Field Summary

static int CLEAR
          Deprecated. As of Web NMS 2.1. This variable had been deprecated to support configurable number of severities.

static int CRITICAL
          Deprecated. As of Web NMS 2.1. This variable had been deprecated to support configurable number of severities.

static int MAJOR
          Deprecated. As of Web NMS 2.1. This variable had been deprecated to support configurable number of severities.

static int MINOR
          Deprecated. As of Web NMS 2.1. This variable had been deprecated to support configurable number of severities.

static int UNKNOWN
          Deprecated. As of Web NMS 2.1. This variable had been deprecated to support configurable number of severities.

static int WARNING
          Deprecated. As of Web NMS 2.1. This variable had been deprecated to support configurable number of severities.

Method Summary

boolean addNetwork(java.lang.String network, java.lang.String netmask)
          Adds a network object of given IP address and netmask to the topology database and starts off its discovery.

boolean addNode(ManagedObject obj)
          Adds a Node object to the database.

java.lang.String addNode(ManagedObject obj, boolean overRideSeed, boolean reachFlag)
          Adds a Node object to the database.

java.lang.String addNode(ManagedObject obj, boolean overRideSeed, boolean reachFlag, boolean discoverParentNet)
          Adds a Node object to the database.

boolean addNodesToTopoDB(java.lang.String[] ipAddrs, java.lang.String netmask)
          Discovers and adds nodes of the given list of IP addresses to the database.

boolean addNodesToTopoDB(java.lang.String startIpAddr, java.lang.String endIpAddr, java.lang.String netmask)
          Discovers and adds nodes of the given IP address range to the database.

boolean addNodeToTopoDB(java.lang.String ipaddr, java.lang.String netmask)
          Discovers and adds a node of the given ip address and netmask to the database.

boolean addNodeToTopoDB(java.lang.String ipaddr, java.lang.String netmask, java.lang.String community, int snmpPort)
          Discovers and adds a node of the given IP address, netmask, SNMP community and SNMP port to the database.

boolean addObject(ManagedObject obj)
          Adds a ManagedObject to the database.

java.lang.String addObject(ManagedObject obj, boolean overRideSeed)
          Adds a ManagedObject to the database.

java.lang.String addObject(ManagedObject obj, boolean overRideSeed, boolean discoveryflag)
          Adds a ManagedObject to the database.

void addObjects(java.lang.String classname, java.util.Vector managedObjects)
          Adds a Vector of ManagedObjects to the database.

void addTopoListener(TopoListener listener)
          To register as a listener to receive notifications from TopoAPI when the bulk-delete operation is carried out.

boolean changeDiscInterval(java.lang.String net, int seconds)
          To change the Discovery interval.

boolean changePingRetries(java.lang.String net, int retries)
          To change the Ping retries.

boolean changePollInterval(java.lang.String net, int seconds)
          Deprecated. as of WebNMS 2.2.

boolean changeSnmpRetries(java.lang.String net, int retries)
          To change the SNMP ping retries.

ManagedObject checkOut(java.lang.String name)
          This method checks out the ManagedObject with the given name from the database for writing, with a write lock.

ManagedObject checkOut(java.lang.String name, int timeOut)
          This method checks out the ManagedObject with the given name from the database for writing, with a write lock.

ManagedObject checkOutIfAvailable(java.lang.String name)
          This method checks out the ManagedObject with the given name from the database for writing, with a write lock.

boolean checkWritePermission(ManagedObject obj)
          Check whether this instance of the ManagedObject can be written to the database.

void clearLockForObject(java.lang.String name, int lockType)
          Release the specified lock type unconditionally for the ManagedObject with the given name.

void clearRouterBusyFlag()
          Method to be used only by the HTML client for debugging purpose.

boolean deleteObject(ManagedObject obj)
          Deprecated. As of Web NMS 2.3. The Web NMS internally locks the MOs before updating them in the database, and since this method does not check for locks before deleting the object, using this method might result in inconsistency in the database. Always use the deleteObject(ManagedObject, boolean, boolean) method with the third argument set to true, to avoid any database inconsistency.

boolean deleteObject(ManagedObject obj, boolean deleteSubElements)
          Deprecated. As of Web NMS 2.3. The Web NMS internally locks the MOs before updating them in the database, and since this method does not check for locks before deleting the object, using this method might result in inconsistency in the database. Always use the deleteObject(ManagedObject, boolean, boolean) method with the third argument set to true, to avoid any database inconsistency.

boolean deleteObject(ManagedObject obj, boolean deleteSubElements, boolean dealWithLocks)
          Deletes the given ManagedObject from the topology database.

boolean deleteObjectAndSubElements(java.lang.String objKey)
          Deletes the ManagedObject with the given key, and all its sub-elements from the data-base.

void deleteObjectAndSubElements(java.lang.String objKey, int level)
          This method can be used to delete a container object and its children objects with multiple levels recursively.

void deleteObjects(java.lang.String classname, java.util.Properties criteria)
          The deleteObjects method is used to delete a selected group of objects based on a criteria.

void deleteObjects(java.lang.String classname, java.util.Properties criteria, int level)
          This method is used to delete objects based on some specific criteria including the deletion of the traces if any.

boolean deregisterTopoSubscriber(TopoSubscriber toposbs)
          To deregister from receiving notifications from TopoAPI, about changes in a particular container object and it's children.

boolean dontDiscoverNetwork(java.lang.String network, java.lang.String netmask)
          Mark the network as not to be discovered in the seed file.

boolean dontDiscoverNode(java.lang.String ip, java.lang.String mask)
          Mark the node as not to be discovered in the seed file.

void doStatusPoll(java.lang.String name)
          Deprecated. As of WebNMS2.0 Beta, the pollStatus method of the ManagedObject is used for status polling of the objects

ManagedObject getByName(java.lang.String name)
          Fetches the ManagedObject from the database, by its unique key.

int getCurrentLockType(ManagedObject obj)
          Get the lock type currently held by the specified instance of the ManagedObject.

DBVector getDbObjects()
          Deprecated. As of Web NMS 2.3, since the DBVector object can not be serialized this method can't be used by remote applications.

java.util.Properties getDiscoveryParameters()
          Gets the current value of the various discovery parameters.

java.util.Vector getGroupNames()
          Gets the names of all the Group MOs in the database.

java.lang.String[] getGroupNamesOfMO(java.lang.String name)
          Deprecated. As of Web NMS 2.3. Methods have been added in the ManagedObject class itself that handle all the Group relation related operations. Retrieve the MO from the database and call the ManagedObject.getGroupNames() method, instead of using this method.

IpAddress getInterface(java.lang.String ipAddr)
          Fetches the IpAddress Object from the database, given the IP address.

java.lang.String getInterfaceObjectKey(java.lang.String ipAddr)
          Gets the key of the IpAddress object, given it's IP address.

java.util.Vector getInterfaces()
          This method returns the IP addresses of all the IpAddress objects in the database, as a vector of Strings.

java.util.Vector getInterfacesOfNetwork(java.lang.String netName)
          Gets the keys of all IpAddress objects belonging to the given Network.

java.util.Vector getInterfacesOfNode(java.lang.String nodeName)
          Gets the keys of all IpAddress objects belonging to the given Node.

java.util.Vector getList()
          Deprecated. As of WebNMS2.0Beta, replaced by getCompleteList() from CommonAPI.

java.lang.String getLocalNetworkAddrs()
          Gets the local network address.

java.lang.String[] getLockedObjectKeys()
          To get the keys of all the Managed objects which are locked at that instance of time.

java.util.Vector getMembersOfGroup(java.lang.String groupName)
          Deprecated. As of Web NMS 2.3. Methods have been added in the ManagedObject class itself that handle all the Group relation related operations. Retrieve the MO from the database and call the ManagedObject.getGroupMembers() method, instead of using this method.

java.lang.String[] getMOClassHierarchy(java.lang.String objKey)
          Get the class hierarchy for the ManagedObject with the given key.

java.lang.String[] getMOHierarchyForClass(java.lang.String classname)
          This method is used to get the classnames in the Hierarchy for the given classname of Managed Object.

Network getNet(java.lang.String ipAddr)
          Fetches the Network Object from the database, by it's unique key.

java.util.Vector getNetworks()
          Returns the keys of all the Network objects in the database, as a Vector of Strings.

Node getNode(java.lang.String name)
          Fetches the Node Object from the database, by it's unique key.

java.lang.String getNodeNameByIP(java.lang.String ipAddress)
          Gets the name of the Node object, given its IP-Address.

java.util.Properties getNodeProperties(java.lang.String nodeName)
          Gets the properties of the Node object with the given key.

java.util.Vector getNodes()
          Returns the keys of all the Node objects in the database, as a Vector of Strings.

java.util.Vector getNodesOfNetwork(java.lang.String net)
          Gets the keys of all the Node objects belonging to the given network.

int getNumInterfaces()
          Returns the current total number of Interface objects in Topology Database.

int getNumNetworks()
          Returns the current total number of Network Objects in Topology Database.

int getNumNodes()
          Returns the current total number of Node objects in Topology Database.

int getNumObjects()
          Returns the current total number of ManagedObjects in Topology Database.

java.util.Vector getObjectNamesWithProps(java.util.Properties p)
          This method can be used to fetch the keys of managed objects which are matching the given criteria.

java.util.Vector getObjectNamesWithProps(java.util.Properties p, boolean performOR)
          Returns a Vector containing the keys of all the MOs, whose properties match the one given in the argument.

java.util.Vector getObjects(java.lang.String classname, java.util.Properties match)
          Gets a Vector of objects matching the given criteria.

java.util.Hashtable getSeedFileParameters()
          Get the values of various seed file discovery parameters.

java.util.Properties getTopoModuleParams()
          returns the Topo Module parameters and their values in java.util.Properties object.

boolean isInitialized()
          Returns whether the TopoAPI has been initialized or not.

boolean isManagedObjectPresent(java.lang.String objKey)
          To check if an object with the given key exists in the database.

ManagedObject lock(ManagedObject obj, int lock_type, int timeout)
          Apply the specified lock to the ManagedObject.

void pollStatus(java.util.Properties prop)
          Deprecated. As of WebNMS2.2, the pollStatus method of the ManagedObject is used for status polling of the objects.

boolean refreshObject(ManagedObject obj)
          Refresh the ManagedObject that is already in the database.

boolean register(TopoActionListener listener)
          To register for notifications from TopoAPI, about topology database changes.

boolean register(TopoObserver obs)
          Deprecated. This method is deprecated as of Web NMS 2.3. Use register(TopoActionListener)

boolean registerNotificationFilter(TopoNotificationFilter notfilter)
          To register for notifications from TopoNotificationRegistry, about changes in the topology database.

boolean registerTopoSubscriber(TopoSubscriber toposbs, java.lang.String containerObjectName)
          To register for notifications from TopoAPI, about changes in a particular container object and it's children.

boolean removeAddressRangeToDiscover(java.lang.String startIP, java.lang.String endIP, java.lang.String network, java.lang.String netmask)
          This method could be used to prevent discovery of a range of IpAddresses in a network.

boolean removeMOFromGroup(java.lang.String[] names, java.lang.String groupName)
          Deprecated. As of Web NMS 2.3. Methods have been added in the ManagedObject class itself, that handle all the Group relation related operations. Retrieve the MO from the database and call the ManagedObject.removeGroupMembers(String[]) method followed by a call to the updateObject(ManagedObject, boolean, boolean) method for that MO, instead of using this method.

boolean removeNodeFromTopoDB(java.lang.String ipaddr)
          Removes the node of the given IP address from the topology database.

boolean removeNodesFromTopoDB(java.lang.String[] ipaddrs)
          Removes the nodes of the given list of IP address from the database.

void removeTopoListener(TopoListener listener)
          To unregister the previously registered TopoListener from TopoAPI.

void saveTopoDBState()
          Deprecated. As of Web NMS 2.3, since serialized mode is no longer supported in Web NMS.

boolean setAddressRangeToDiscover(java.lang.String startIP, java.lang.String endIP, java.lang.String network, java.lang.String netmask)
          Use this method to set the discovery range of a network of given netmask.

boolean setAutoCommit(boolean b)
          Deprecated. As of Web NMS 2.3, modules don't have separate database connections and all database operations in NMS go through a central database connection pool. Please refer ConnectionPool for more details.

boolean setDiscover(java.lang.String netwname, boolean discover)
          This method sets/unsets the discover property of the given Network object,if it is present in the database, and accordingly starts or stops discovery for the Network.

boolean setDiscoveryParameters(java.util.Properties prop)
          Set values for various discovery parameters.

void setDisTopoLoggingMode(boolean mode)
          Enable or Disable logging messages in the discoveryLogs.txt file.

boolean setGroupForMembers(java.lang.String[] memberNames, java.lang.String groupName)
          Deprecated. As of Web NMS 2.3. Methods have been added in the ManagedObject class itself, that handle all the Group relation related operations. Retrieve the MO from the database and call the ManagedObject.setGroupNames(String[]) or ManagedObject.addGroupNames(String[]) method, followed by a call to the updateObject(ManagedObject, boolean, boolean) method for that MO, instead of using this method.

boolean setGroupsForMO(java.lang.String name, java.lang.String[] groupNames, boolean append)
          Deprecated. As of Web NMS 2.3. Methods have been added in the ManagedObject class itself, that handle all the Group relation related operations. Retrieve the MO from the database and call the ManagedObject.setGroupMembers(String[]) or ManagedObject.addGroupMembers(String[]) method, followed by a call to the updateObject(ManagedObject, boolean, boolean) method for that MO, instead of using this method.

void setManaged(java.lang.String name, boolean manage)
          This method sets whether a ManagedObject is to be managed or unmanaged.

void setManagedAll(Network obj, boolean isManaged)
          This method sets whether a Network Object is to be managed or unmanaged.

void setManagedAll(Node obj, boolean isManaged)
          This method sets whether a Node Object is to be managed or unmanaged.

void suppressInfoEvents(boolean suppress)
          To enable/disable Info events getting generated from the Topology module.

void unlock(ManagedObject obj)
          Unlock the specified ManagedObject.

boolean unregister(TopoActionListener listener)
          To unregister from getting notifications, about topology database changes , from the TopoAPI.

boolean unregister(TopoObserver obs)
          Deprecated. This method is deprecated as of Web NMS 2.3. Use unregister(TopoActionListener)

boolean unregisterNotificationFilter(TopoNotificationFilter notfilter)
          To unregister the previously registered TopoNotificationFilter from the TopoNotificationRegistry.

boolean updateObject(ManagedObject obj)
          Deprecated. As of Web NMS 2.3. The Web NMS internally locks the MOs before updating them in the database, and since this method does not check for locks before updating the object, using this method might result in inconsistency in the database. Always use the updateObject(ManagedObject, boolean, boolean) method with the third argument set to true, to avoid any database inconsistency.

boolean updateObject(ManagedObject obj, boolean retainUserProperties)
          Deprecated. As of Web NMS 2.3. The Web NMS internally locks the MOs before updating them in the database, and since this method does not check for locks before updating the object, using this method might result in inconsistency in the database. Always use the updateObject(ManagedObject, boolean, boolean) method with the third argument set to true, to avoid any database inconsistency.

boolean updateObject(ManagedObject obj, boolean retainUserProperties, boolean dealWithLocks)
          Updates the ManagedObject in the database.

boolean updateStatus(java.lang.String name, int status)
          Updates the status of the specified ManagedObject, to the given status value.

Methods inherited from interface com.adventnet.nms.util.CommonAPI

getCompleteList, getPropertiesOfObject

Field Detail