"WEBNMS_5 API Docs"

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

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)
  • TopoBulkListener
  • addTopoBulkListener(TopoBulkListener)
  • removeTopoBulkListener(TopoBulkListener)
  • 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");
    }
     
     


    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.
     int addNetwork(java.lang.String network, java.lang.String netmask, boolean overRideSeed)
              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 addTopoBulkListener(TopoBulkListener 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 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 checkOut(java.lang.String name, int timeOut, boolean dealWithLocks, boolean lazyFetch)
              This method is to fetch the object with or without associated Collections.
     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, 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 recursively, till the last level of containment hierarchy.
     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)
              Deprecated. Deprecated as of WebNMS 5. Use deleteObjects(String, Properties).
     boolean deregisterTopoSubscriber(TopoSubscriber toposbs)
              To deregister from receiving notifications from TopoAPI, about changes in a particular container object and it's children.
     int discoverNetwork(java.lang.String network, java.lang.String netmask, boolean overRideUnmanaged, boolean overRideDiscoveryDisabled)
              Triggers discovery for a network which is already present in the database.Inorder to manage and trigger discovery for a unmanaged network, the argument "overRideUnmanaged" should be set to true.This parameter also sets the "discover" property for the network to true.Inorder to trigger discovery for a network which is managed but discover-disabled, the parameter "overRideDiscoveryDisabled" should be set to true.
     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.
     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.
     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 getIpAddressesOfNetwork(java.lang.String netName)
              Gets the ipAddresses belonging to the given Network.
     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.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 getObjectPropsWithProps(java.lang.String classname, java.lang.String[] fetchProperties, java.util.Properties criteria, boolean returnAsProps, boolean performOr)
              Gets a Vector containing selective properties of objects matching the given criteria.
     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.
     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 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 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 removeTopoBulkListener(TopoBulkListener listener)
              To unregister the previously registered TopoBulkListener from TopoAPI.
     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 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 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(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 unregisterNotificationFilter(TopoNotificationFilter notfilter)
              To unregister the previously registered TopoNotificationFilter from the TopoNotificationRegistry.
     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
     

    Method Detail

    checkOut

    ManagedObject checkOut(java.lang.String name)
                           throws java.rmi.RemoteException,
                                  TimeoutException,
                                  NmsStorageException,
                                  UserTransactionException
    This method checks out the ManagedObject with the given name from the database for writing, with a write lock. This method blocks for a very long time until the ManagedObject is ready for writing, if the object is locked by another thread. Returns null if the ManagedObject is not present in the database.

    Note: Use the checkOut(String, int) method to check out objects from the database with locks, as it might result in the method call getting blocked unacceptably.

    Parameters:
    name - The unique name of the ManagedObject to be checked out
    Returns:
    ManagedObject, if it is present in the database

    null, if the object is not present in the database

    Throws:
    TimeoutException - if the object is not available for writing even after a very long time (LOCK_TIMEOUT configured in DBServer process).
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    checkOut

    ManagedObject checkOut(java.lang.String name,
                           int timeOut)
                           throws java.rmi.RemoteException,
                                  TimeoutException,
                                  NmsStorageException,
                                  UserTransactionException
    This method checks out the ManagedObject with the given name from the database for writing, with a write lock. If the ManagedObject to be checked out is currently locked by some other thread, this method keeps trying to check out the object for the specified time. If the ManagedObject becomes available for writing before the specified time, the object is fetched from the database, locked and returned back. Returns null if the ManagedObject is not present in the database.

    Parameters:
    name - The unique name of the ManagedObject to be checked out
    timeOut - Time in seconds to wait, if the object is locked by some other thread.
    Returns:
    ManagedObject, if it is present in the database

    null, if the object is not present in the database

    Throws:
    TimeoutException - if the object is not available for writing for the specified amount of time.
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    checkOut

    ManagedObject checkOut(java.lang.String name,
                           int timeOut,
                           boolean dealWithLocks,
                           boolean lazyFetch)
                           throws java.rmi.RemoteException,
                                  TimeoutException,
                                  NmsStorageException,
                                  UserTransactionException
    This method is to fetch the object with or without associated Collections. The argument (lazyFetch) will decide whether object will be loaded with collections associated with this object. Based on the value of dealWithLocks,the object is fetched from the database using checkOut() or getByName() APIs. If dealWithLocks is set to true ,then this method will call checkOut method ,else it will call getByname() If lazyFetch is set to false,this method will load the object with collections associated with this Object,else it will fetch the object alone. For example, The ManagedObject may have the possible collections such as childrenKeys - if the object is a container object groupNames,groupMembers- if the object is a group object If the object is container or group object,then the argument (lazyFetch) will decide whether object will be loaded initially with collections (childrenkeys or groupMembers and groupNames). if lazyFetch is false ,the Object will be loaded with childrenkeys ,groupMembers and groupNames.

    Note: Use the checkOut(String, int) method to check out objects from the database with locks. Use the getByName(String) method to fetches the ManagedObject from the database

    Parameters:
    name - The unique name of the ManagedObject to be checked out
    timeOut - Time in seconds to wait, if the object is locked by some other thread.
    dealWithLocks - if dealWithLocks is true,it will call checkOut(String,int) method,Otherwise it will call getByname method
    lazyFetch - if lazyFetch is false,this method will load the object with collections associated with this Object.If it is true,It will fetch the object alone.
    Returns:
    ManagedObject, if it is present in the database

    null, if the object is not present in the database

    Throws:
    TimeoutException - if the object is not available for writing for the specified amount of time.
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    checkOutIfAvailable

    ManagedObject checkOutIfAvailable(java.lang.String name)
                                      throws java.rmi.RemoteException,
                                             TimeoutException,
                                             NmsStorageException,
                                             UserTransactionException
    This method checks out the ManagedObject with the given name from the database for writing, with a write lock. This method throws an Exception if the managed object is locked by another thread and doesn't wait.

    Parameters:
    name - The unique name of the ManagedObject to be checked out
    Returns:
    ManagedObject, if it is present in the database

    null, if the object is not present in the database

    Throws:
    TimeoutException - if the object is locked by some other thread
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    addObject

    boolean addObject(ManagedObject obj)
                      throws java.rmi.RemoteException,
                             NmsStorageException,
                             UserTransactionException
    Adds a ManagedObject to the database. The ManagedObject, identified uniquely by it's key, will be added to the database only if it is not previously present in the database.

    The addition of a ManagedObject to the database might involve inserts into multiple tables. If the underlying database supports transaction and if the transaction support is enabled, then this method would ensure atomicity in the add operation, across all the database tables and the cache.

    If the given ManagedObject is an instance of Network object, then this method would start the discovery process for the corresponding network, if the managed and the discover properties are set to true. This method doesn't add Network objects to the database, which are specified in the NOT_TO_DISCOVER net seed file statement. To override this behaviour, use the addObject(ManagedObject, boolean) method. If the Network object being added happens to be a subnet of some other Network, which is already present in the database, then this method updates the parentNetwork and the parentNetMask properties of the passed Network object and the subNets and the subNetMasks properties of the other corresponding Network object, respectively. Similarly, it also takes care of the condition where an alerady existing Network object is a subnet of the passed Network object.

    If the given ManagedObject is an instance of Node object, then this method would also automatically add a Network object corresponding to the parent network of the Node, if one such is not already present in the database. This method, by default, would also start the discovery process for the added Network object. To override this behaviour, use the addObject(ManagedObject, boolean, boolean) method.

    This method is not to be used if the properties are not fully filled, in case of Node and IpAddress objects. To discover and add the Node and IpAddress objects use the addNode(ManagedObject) method.

    This method notifies all the TopoObservers, if the object is successfully added to the database. This method also generates an Event when a ManagedObject gets successfully added to the database.

    Parameters:
    obj - The ManagedObject to be added to the database.
    Returns:
    true, if the object was successsfully added to the database, false otherwise
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    com.adventnet.nms.topodb.TopoObserver, addNode(ManagedObject), updateObject(ManagedObject, boolean, boolean), deleteObject(ManagedObject, boolean, boolean), getByName(String)

    addObject

    java.lang.String addObject(ManagedObject obj,
                               boolean overRideSeed)
                               throws java.rmi.RemoteException,
                                      NmsStorageException,
                                      UserTransactionException
    Adds a ManagedObject to the database. The ManagedObject, identified uniquely by it's key, will be added to the database only if it is not previously present in the database.

    The addition of a ManagedObject to the database might involve inserts into multiple tables. If the underlying database supports transaction and if the transaction support is enabled, then this method would ensure atomicity in the add operation, across all the database tables and the cache.

    If the given ManagedObject is an instance of Network object, then this method would start the discovery process for the corresponding network, if the managed and the discover properties are set to true. If the second argument to this method (overRideSeed) is set to true, then the Network objects are added to the database, even if they are specified in the NOT_TO_DISCOVER net seed file statement. If the Network object being added happens to be a subnet of some other Network, which is already present in the database, then this method updates the parentNetwork and the parentNetMask properties of the passed Network object and the subNets and the subNetMasks properties of the other corresponding Network object, respectively. Similarly, it also takes care of the condition where an alerady existing Network object is a subnet of the passed Network object.

    If the given ManagedObject is an instance of Node object, then this method would also automatically add a Network object corresponding to the parent network of the Node, if one such is not already present in the database. This method, by default, would also start the discovery process for the added Network object. To override this behaviour, use the addObject(ManagedObject, boolean, boolean) method.

    This method is not to be used if the properties are not fully filled, in case of Node and IpAddress objects. To discover and add the Node and IpAddress objects use the addNode(ManagedObject) method.

    This method notifies all the TopoObservers, if the object is successfully added to the database. This method also generates an Event when a ManagedObject gets successfully added to the database.

    Parameters:
    obj - The ManagedObject to be added to the database.
    overRideSeed - Whether the seed file configuration is to be overridden or not, while adding the Network objects.
    Returns:
    String specifying the result of the operation, with the reason

    Object Successfully Added to Database

    Object Already Exists in the database

    Object Not Added: Invalid Address

    Discovery disabled for the object in seed file, hence Network not added

    Database Exception occured while adding object

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    com.adventnet.nms.topodb.TopoObserver, addNode(ManagedObject), updateObject(ManagedObject, boolean, boolean), deleteObject(ManagedObject, boolean, boolean), getByName(String)

    addObject

    java.lang.String addObject(ManagedObject obj,
                               boolean overRideSeed,
                               boolean discoveryflag)
                               throws java.rmi.RemoteException,
                                      NmsStorageException,
                                      UserTransactionException
    Adds a ManagedObject to the database. The ManagedObject, identified uniquely by it's key, will be added to the database only if it is not previously present in the database.

    The addition of a ManagedObject to the database might involve inserts into multiple tables. If the underlying database supports transaction and if the transaction support is enabled, then this method would ensure atomicity in the add operation, across all the database tables and the cache.

    If the given ManagedObject is an instance of Network object, then this method would start the discovery process for the corresponding network, if the managed and the discover properties are set to true. If the second argument to this method (overRideSeed) is set to true, then the Network objects are added to the database, even if they are specified in the NOT_TO_DISCOVER net seed file statement. If the Network object being added happens to be a subnet of some other Network, which is already present in the database, then this method updates the parentNetwork and the parentNetMask properties of the passed Network object and the subNets and the subNetMasks properties of the other corresponding Network object, respectively. Similarly, it also takes care of the condition where an alerady existing Network object is a subnet of the passed Network object.

    If the given ManagedObject is an instance of Node object, then this method would also automatically add a Network object corresponding to the parent network of the Node, if one such is not already present in the database. If the third argument (discoveryFlag) is set to true, then this method would also start the discovery process for the added Network object.

    This method is not to be used if the properties are not fully filled, in case of Node and IpAddress objects. To discover and add the Node and IpAddress objects use the addNode(ManagedObject) method.

    This method notifies all the TopoObservers, if the object is successfully added to the database. This method also generates an Event when a ManagedObject gets successfully added to the database.

    Parameters:
    obj - The ManagedObject to be added to the database.
    overRideSeed - Whether the seed file configuration is to be overridden or not, while adding the Network objects.
    discoveryflag - Whether the discovery process for the parent Network Object of the Node is to be started or not.
    Returns:
    String specifying the result of the operation, with the reason

    Object Successfully Added to Database

    Object Already Exists in the database

    Object Not Added: Invalid Address

    Discovery disabled for the object in seed file, hence Network not added

    Database Exception occured while adding object

    Licensed Limit Exceeded: Could not Add the Object

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    com.adventnet.nms.topodb.TopoObserver, addNode(ManagedObject), updateObject(ManagedObject, boolean, boolean), deleteObject(ManagedObject, boolean, boolean), getByName(String)

    addNode

    boolean addNode(ManagedObject obj)
                    throws java.rmi.RemoteException,
                           NmsStorageException,
                           UserTransactionException
    Adds a Node object to the database. This method can be used if a node has to be discovered and added to the database. The Node object will be added to the database only if there is no IpAddress object already existing in the database, with the ipAddress property the same as the one of the Node object passed in the argument of this method. This is done to avoid the same node (identified uniquely by it's IP address on an IP network) getting added to the database with different keys.

    The ManagedObject passed through the first argument of this method must be an instance of Node or it's sub-classes, otherwise this method does not proceed discovering the node.

    This method uses the ipAddress and the netmask properties of the given Node object (which are inherited from TopoObject) to discover the node, and hence it is mandatory that these two properties be set with proper values. The netmask property is used to identify the network to which the Node should belong. Also, if the node to be discovered has SNMP support, then the snmpport, userName, contextName and community properties of the given Node object will be used during discovery. Any other property or user properties from the passed Node object will be ignored.

    This method follows the same path as the discovery module would, to discover the specified Node. Thus, the object is passed through all the discovery filters and seed file constraints that are specified, which might cause change in values of the various properties of the object and even prevent the object from being added to the database. This method will add the Node's interfaces (as IpAddress objects) to the database, and may also result in the addition of other Network objects if the specified node happens to be a router. Thus, it is recommended that this method not be invoked from the discovery filters, as it might result in recursive invokation of this method.

    The addition of a Node object to the database might involve inserts into multiple tables. If the underlying database supports transaction and if the transaction support is enabled, then this method would ensure atomicity in the add operation, across all the database tables and the cache.

    This method by default checks for all the constraints specified in the seed file, which might prevent the addition of the Node object to the database. To override this behaviour, use the addNode(ManagedObject ,boolean, boolean) method.

    This method does not add the Node and it's interface objects, if it is not reachable from the Web NMS server. To override this behaviour, use the addNode(ManagedObject, boolean, boolean) method.

    If the parent Network object does not exist for the Node to be added, then this method would add the corresponding parent Network object to the database, if one such does not already exist in the database. This method, by default would also start the discovery process for the added Network object. To override this behaviour, use the addNode(ManagedObject, boolean, boolean, boolean) method.

    This method notifies all the TopoObservers, if the Node and the IpAddress objects are successfully added to the database. This method also generates corresponding Events when the Node and IpAddress objects get successfully added to the database.

    Parameters:
    obj - The ManagedObject (which must be an instance of Node) to be discovered and added.
    Returns:
    true if the operation was successful, false otherwise
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    com.adventnet.nms.topodb.TopoObserver, addNodesToTopoDB(String, String, String)

    addNode

    java.lang.String addNode(ManagedObject obj,
                             boolean overRideSeed,
                             boolean reachFlag)
                             throws java.rmi.RemoteException,
                                    NmsStorageException,
                                    UserTransactionException
    Adds a Node object to the database. This method can be used if a node has to be discovered and added to the database. The Node object will be added to the database only if there is no IpAddress object already existing in the database, with the ipAddress property the same as the one of the Node object passed in the argument of this method. This is done to avoid the same node (identified uniquely by it's IP address on an IP network) getting added to the database with different keys.

    The ManagedObject passed through the first argument of this method must be an instance of Node or it's sub-classes, otherwise this method does not proceed discovering the node.

    This method uses the ipAddress and the netmask properties of the given Node object (which are inherited from TopoObject) to discover the node, and hence it is mandatory that these two properties be set with proper values. Also, if the node to be discovered has SNMP support, then the snmpport, userName, contextName and community properties of the given Node object will be used during discovery. Any other property or user properties from the passed Node object will be ignored.

    This method follows the same path as the discovery module would, to discover the specified Node. Thus, the object is passed through all the discovery filters and seed file constraints that are specified, which might cause change in values of the various properties of the object and even prevent the object from being added to the database. This method will add the Node's interfaces (as IpAddress objects) to the database, and may also result in the addition of other Network objects if the specified node happens to be a router. Thus, it is recommended that this method not be invoked from the discovery filters, as it might result in recursive invokation of this method.

    The addition of a Node object to the database might involve inserts into multiple tables. If the underlying database supports transaction and if the transaction support is enabled, then this method would ensure atomicity in the add operation, across all the database tables and the cache.

    If the second argument of this method (overRideSeed) is set to true, then the constraints specified in the seed file will all be ignored while the Node object is added to the database.

    If the third argument of this method (reachFlag) is set to true , then the Node and the corresponding IpAddress objects will be added to the database even if the node (identified by it's IP address) is not reachable from the Web NMS server.

    If the parent Network object does not exist for the Node to be added, then this method would add the corresponding parent Network object to the database, if one such does not already exist in the database. This method, by default would also start the discovery process for the added Network object. To override this behaviour, use the addNode(ManagedObject, boolean, boolean, boolean) method.

    This method notifies all the TopoObservers, if the Node and the IpAddress objects are successfully added to the database. This method also generates corresponding Events when the Node and IpAddress objects get successfully added to the database.

    Parameters:
    obj - The ManagedObject (which must be an instance of Node) to be discovered and added.
    overRideSeed - Whether the seed file configuraton has to be overridden or not.
    reachFlag - Whether the node is to be added, even if it is not reachable from the NMS server.
    Returns:
    String specifying the result of the operation, with the reason.

    Successfully Added to Database

    object Not An Instance Of Node

    Cannot Add This Node object Check Seed File Configuration

    Cannot Add This Node object Node not reachable

    Cannot Add This Node object Check Applied Filters

    Database Exception occured while adding Node object

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    com.adventnet.nms.topodb.TopoObserver, addNodesToTopoDB(String, String, String)

    addNode

    java.lang.String addNode(ManagedObject obj,
                             boolean overRideSeed,
                             boolean reachFlag,
                             boolean discoverParentNet)
                             throws java.rmi.RemoteException,
                                    NmsStorageException,
                                    UserTransactionException
    Adds a Node object to the database. This method can be used if a node has to be discovered and added to the database. The Node object will be added to the database only if there is no IpAddress object already existing in the database, with the ipAddress property the same as the one of the Node object passed in the argument of this method. This is done to avoid the same node (identified uniquely by it's IP address on an IP network) getting added to the database with different keys.

    The ManagedObject passed through the first argument of this method must be an instance of Node or it's sub-classes, otherwise this method does not proceed discovering the node.

    This method uses the ipAddress and the netmask properties of the given Node object (which are inherited from TopoObject) to discover the node, and hence it is mandatory that these two properties be set with proper values. Also, if the node to be discovered has SNMP support, then the snmpport, userName, contextName and community properties of the given Node object will be used during discovery. Any other property or user properties from the passed Node object will be ignored.

    This method follows the same path as the discovery module would, to discover the specified Node. Thus, the object is passed through all the discovery filters and seed file constraints that are specified, which might cause change in values of the various properties of the object and even prevent the object from being added to the database. This method will add the Node's interfaces (as IpAddress objects) to the database, and may also result in the addition of other Network objects if the specified node happens to be a router. Thus, it is recommended that this method not be invoked from the discovery filters, as it might result in recursive invokation of this method.

    The addition of a Node object to the database might involve inserts into multiple tables. If the underlying database supports transaction and if the transaction support is enabled, then this method would ensure atomicity in the add operation, across all the database tables and the cache.

    If the second argument of this method (overRideSeed) is set to true, then the constraints specified in the seed file will all be ignored while the Node object is added to the database.

    If the third argument of this method (reachFlag) is set to true , then the Node and the corresponding IpAddress objects will be added to the database even if the node (identified by it's IP address) is not reachable from the Web NMS server.

    If the parent Network object does not exist for the Node to be added, then this method would add the corresponding parent Network object to the database, if one such does not already exist in the database. If the fourth argument of this method (discoverParentNet) is set to true, then it would also start the discovery process for the added Network object.

    This method notifies all the TopoObservers, if the Node and the IpAddress objects are successfully added to the database. This method also generates corresponding Events when the Node and IpAddress objects get successfully added to the database.

    Parameters:
    obj - The ManagedObject (which must be an instance of Node) to be discovered and added.
    overRideSeed - Whether the seed file configuraton has to be overridden or not.
    reachFlag - Whether the node is to be added, even if it is not reachable from the NMS server.
    discoverParentNet - Whether the discovery process for the parent network is to be started or not.
    Returns:
    String specifying the result of the operation, with the reason.

    Successfully Added to Database

    object Not An Instance Of Node

    Cannot Add This Node object Check Seed File Configuration

    Cannot Add This Node object Node not reachable

    Cannot Add This Node object Check Applied Filters

    Database Exception occured while adding Node object

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    com.adventnet.nms.topodb.TopoObserver, addNodesToTopoDB(String, String, String)

    refreshObject

    boolean refreshObject(ManagedObject obj)
                          throws java.rmi.RemoteException,
                                 NmsStorageException,
                                 UserTransactionException
    Refresh the ManagedObject that is already in the database. Currently this method can be used only for Node Objects, whose managed property is set to true. This method will again discover the node and all its interfaces and update their properties and also their current status.

    Parameters:
    obj - - The ManagedObject to be rediscovered and refreshed in the database.
    Returns:
    true, if refreshing was successful

    false, if the object is not present in the database or if the node is currently set to unmanaged or the parent network is not in database or if the given object is not an instance of Node.

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.

    deleteObject

    boolean deleteObject(ManagedObject obj,
                         boolean deleteSubElements,
                         boolean dealWithLocks)
                         throws java.rmi.RemoteException,
                                NmsStorageException,
                                UserTransactionException,
                                AccessDeniedException
    Deletes the given ManagedObject from the topology database.

    If dealWithLocks is true, then this method first checks whether the object instance being passed holds a valid write lock and only then procedes with the delete operation. If dealWithLocks is false, then this method would ignore any lock held by other instnaces of the same object and will carry on deleting the object. Since the Web NMS internally locks the MOs before doing any update/delete operations over them, it is strongly recommended that this method be always used with the dealWithLocks argument set to true, to avoid causing inconsistency to the database.

    For Network object instances, this method also takes care of updating or deleting the corresponding Node and IpAddress objects. If deleteSubElements is false, then the name of the Network object will be removed from the parentNets property of the Node object, and the parentNet property of the IpAddress object will be set to an empty string (""), and the changes will be updated to the database. If deleteSubElements is true, then the corresponding Node and IpAddress objects will also be deleted from the database. If a Node object belongs to more than one Network object, then that Node object will not be deleted.

    Please note that deleting a Network object and all it's associated Node and IpAddress objects using this method might take a long time, as the objects are individually deleted. Please use the deleteObjectAndSubElements(String) method to delete the Network and it's associated objects, which does the operation efficiently, greatly minimizing the number of database queries to be executed.

    For Node object instances, this method would remove the name of the Node object from the nodeList property of the corresponding Network object and updates the changes to the database. If deleteSubElements is false, then this method sets the parentNode property of the corresponding IpAddress object to an empty string ("") and updates the changes to the database. If deleteSubElements is true, then this method would also delete the corresponding IpAddress object from the database.

    For IpAddress object instances, this method would remove the IP address of the given IpAddress object from the ipaddrs property of the corresponding Network and Node objects, and updates the changes to the database.

    For any other type of MO, this method only deletes the given object. For deleting MOs implementing ContainerInterface or GroupInterface and all their associated objects, please use the deleteObjectAndSubElements(String) method.

    If the underlying RDBMS supports transactions and if the transaction support is enabled in the Web NMS server, then this method ensures atomicity of the delete operation, which might involve multiple MOs. That is, if the delete operation fails at any point, all the previous changes made to the database will be undone.

    If the delete operation is successful, then this method notifies all the registered TopoObservers for each MO separately. If a GroupObject is deleted using this method, the Group members belonging that group will not be deleted. For deleting Group objects along with the Group members, use deleteObjectAndSubElements() method instead.

    Please note Containers cannot be deleted using this method. For deleting containers use deleteObjectAndSubElements() method instead.

    Parameters:
    obj - The ManagedObject to be deleted.
    deleteSubElements - Whether related objects are to be deleted or not.
    dealWithLocks - Whether the given object should be checked for holding a valid lock, before deleting
    Returns:
    true if deletion is successful, false otherwise.
    Throws:
    AccessDeniedException - if the object is locked by some other thread and is not available for writing.
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    checkOut(String,int), deleteObjectAndSubElements(String)

    isInitialized

    boolean isInitialized()
                          throws java.rmi.RemoteException
    Returns whether the TopoAPI has been initialized or not. The TopAPI can be used only after it has been initialized.

    Returns:
    true if TopoAPI is initialized and can be used, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    getByName

    ManagedObject getByName(java.lang.String name)
                            throws java.rmi.RemoteException,
                                   NmsStorageException,
                                   UserTransactionException
    Fetches the ManagedObject from the database, by its unique key. This method returns null, if the Object is not in the database.

    Parameters:
    name - Key of the ManagedObject to be fetched from the database. The name property of the ManagedObject is it's key, if it's ownerName property is null. Otherwise the key will be name + \t +ownerName
    Returns:
    Corresponding ManagedObject instance if present in the database, null otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getNode

    Node getNode(java.lang.String name)
                 throws java.rmi.RemoteException,
                        NmsStorageException,
                        UserTransactionException
    Fetches the Node Object from the database, by it's unique key. This method returns null, if the Object is not in the database or the object in the database with the given key is not an instance of Node.

    Parameters:
    name - key of the Node Object to be fetched from the database.
    Returns:
    Corresponding Node instance if present in the database, null otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getInterface

    IpAddress getInterface(java.lang.String ipAddr)
                           throws java.rmi.RemoteException,
                                  NmsStorageException,
                                  UserTransactionException
    Fetches the IpAddress Object from the database, given the IP address. This method can be used to retrieve IpAddress objects from the database by specifying the ipAddress property. For example, an IpAddress object with the name property as IF-adventnet and ipAddress property as 192.168.4.7 can be retrieved from the database by specifying it's ipAddress property (i.e. 192.168.4.7) in the argument of this method.

    This method returns null, if the Object is not in the database or the object in the database with the given IP address is not an instance of IpAddress object.

    Parameters:
    ipAddr - IP address of the IpAddress object which is to be retrieved.
    Returns:
    Corresponding IpAddress instance if present in the database, null otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getInterfaceObjectKey

    java.lang.String getInterfaceObjectKey(java.lang.String ipAddr)
                                           throws java.rmi.RemoteException,
                                                  NmsStorageException,
                                                  UserTransactionException
    Gets the key of the IpAddress object, given it's IP address. If the name is the key of the IpAddress object, then this method returns the name of the IpAddress object, whose ipAddress property matches the given argument.

    Parameters:
    ipAddr - IP Address of the IpAddress object whose name is to be got.
    Returns:
    Key of the IpAddress object matching the given IP address if the object exists in database, null otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getNodeNameByIP

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

    Parameters:
    ipAddress - IP-Address of the Node object whose name is required.
    Returns:
    Name of the Node object matching the given IP-Address if the object exists in the database, null otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getNet

    Network getNet(java.lang.String ipAddr)
                   throws java.rmi.RemoteException,
                          NmsStorageException,
                          UserTransactionException
    Fetches the Network Object from the database, by it's unique key. This method returns null, if the Object is not in the database or the object in the database with the given name is not an instance of Network.

    Parameters:
    ipAddr - key of the Network Object to be fetched from the database.
    Returns:
    Corresponding Network instance if present in the database, null otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    updateObject

    boolean updateObject(ManagedObject obj,
                         boolean retainUserProperties,
                         boolean dealWithLocks)
                         throws java.rmi.RemoteException,
                                AccessDeniedException,
                                NmsStorageException,
                                UserTransactionException
    Updates the ManagedObject in the database.

    This method can be used when one or more properties of a ManagedObject is to be updated in the database. This method replaces the ManagedObject in the database with the one (with modified properties) given in the first argument of this method. The update operation will be successful only if the object, identified by it's key, is already present in the database.

    If the second argument (retainUserProperties) of this method is set to true, then already existing user properties of the object are retained with their old values, otherwise they will be overwritten with the new values, if specified. However, in both the cases, the newly added user properties will be updated in the database.

    If the third argument (dealWithLocks) of this method is set to true, then this method proceeds to update the object in the database only if it holds a valid write lock. Otherwise, it updates the changes to the database, irrespective of the object holding a valid write lock or not. Hence the ManagedObject that is passed to this method for update should be locked before if this boolean is set to true. As the Web NMS internally locks the objects before updating them to the database for any of its internal operations, it is highly recommended that applications developed over Web NMS use this method (with the third argument set to true) to update the object in the database. Also, this method automatically unlocks the object upon completion, irrespective of the result of the update operation (if the third argument is true). Please refer checkOut(String, int) to get more details on how to lock the objects.

    If the underlying database supports transaction, and if the transaction support is enabled, then this method ensures atmocity of the update operation. That is, if the update operation affects multiple database tables, and if the operation fails at any point, the changes made to the database tables from the start of the operation are all undone and the operation is abandoned.

    If any of the relation (Container or Group) capturing property of the ManagedObject is changed, then this method takes care of automatically updating the corresponding properties of the related objects also. For ex., if the childrenKeys property of a ManagedObject is changed, then the parentKey property of the related ManagedObjects are also updated.

    If the ManagedObject provided as an argument to this method (identified uniquely by it's key) is an instance of a different class from that of the object already present, then it would boil down to a deletion of the old object and addition of provided object.

    If the managed or the discover property of the Network object is changed to true or false, then this method takes care of starting or stopping the network discovery, respectively.

    Note :The property 'classname' should not be changed,since it is internally used in NMS and altering the classname would lead to undesired result in object fetching,updating and deleting the object .So this method will not update the classname if it is changed .

    If the update operation is successful, then this method also notifies all the TopoObservers (viz. MapManager, PollMgr etc.) about the change in the database object. Please refer com.adventnet.nms.topodb.TopoObserver for more details about the notifications.

    If the 'ipAddress' property of a Node object is updated using this method, and if the new 'ipAddress' is not previously set to any other object ,then this method take care of updating the Node's 'ipAddress' property in all the related tables .But if the new 'ipAddress' set to the Node is previously set to any other object , then the 'ipAddress' property is not updated. Also this method takes care of updating the Node's corresponding Interface object's 'ipAddress' property .If the new ipAddress belongs to a different network and if the network does not exist in database, then this method takes care of adding the network without triggering the network discovery . If the 'ipAddress' property of an Interface object is updated using this method, then this method take care of updating the Interface object's ipAddress property in all the related tables .But does not take care of updating its corresponding parent node's ipAddress property .

    Note Whenever 'ipAddress' property is updated , then this method sends notification to all TopoObservers with notification type as 'IpAddress Update'

    Parameters:
    obj - The ManagedObject which is to be updated in the database
    retainUserProperties - Specifies whether the values of the already existing user properties are to be retained or overwritten with this update operation
    dealWithLocks - Specifies whether the object passed in the argument should be checked for a valid write lock before it is updated in the database
    Returns:
    true if update was sucessful, false otherwise.
    Throws:
    AccessDeniedException - if the method is invoked with the third argument(dealWithLocks) set to true but the the object that is passed for update does not hold a valid write lock.
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    com.adventnet.nms.topodb.TopoObserver, checkOut(String, int)

    updateStatus

    boolean updateStatus(java.lang.String name,
                         int status)
                         throws java.rmi.RemoteException,
                                NmsStorageException,
                                UserTransactionException
    Updates the status of the specified ManagedObject, to the given status value. The first argument is the name of the ManagedObject whose status is to be updated and the second argument is the value of the status. This method notifies all the TopoObservers about the status change of the ManagedObject. This method will also trigger an immediate status polling for the object's parent objects, which might result in a status change for those objects too. All the changes are immediately updated in the database.

    Parameters:
    name - The name of the ManagedObject whose status is to be updated.
    status - The new status value of the ManagedObject.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    setDiscover

    boolean setDiscover(java.lang.String netwname,
                        boolean discover)
                        throws java.rmi.RemoteException,
                               NmsStorageException,
                               UserTransactionException
    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. This method can take effect only if the Network Object is being currently managed (i.e. it's managed property is set to true). The method will not do anything, if the Network Object is unmanaged. This method notifies all TopoObservers of the change in the discover property of the Network.

    Parameters:
    netwname - The name of the Network Object.
    discover - true - to start discovery, false - to stop discovery.
    Returns:
    true, if the operation is successful false, if the object is not present or if the network is not managed or if tried to set discover attribute to it's old value.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.

    setManaged

    void setManaged(java.lang.String name,
                    boolean manage)
                    throws java.rmi.RemoteException,
                           NmsStorageException,
                           UserTransactionException
    This method sets whether a ManagedObject is to be managed or unmanaged. The sub-elements of this ManagedObject will not be affected by this method. For example, if a Node object is set to unmanaged by this method, then the corresponding interface objects will not be affected at all. For Network objects, this method will also update their discover property depending on whether they are set to managed or unmanaged. This method notifies all TopoObservers of the change in the managed property of the ManagedObject.

    Parameters:
    name - The name of the ManagedObject.
    manage - true - to make the object managed, false - to make the object unmanaged.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.

    setManagedAll

    void setManagedAll(Node obj,
                       boolean isManaged)
                       throws java.rmi.RemoteException,
                              NmsStorageException,
                              UserTransactionException
    This method sets whether a Node Object is to be managed or unmanaged. The sub-elements of this Node Object will also be affected by this method. This method by default doesn't provide concurrency control for the object passed as argument. To ensure that the Node object is not modified simultaneously by any other user ( thread ) and to get exclusive access to the object, it has to be locked before invoking the method. Also the user must take care of unlocking the object. The method can also be invoked without the object being locked. For example, if a Node object is set to unmanaged by this method, then the corresponding children interface objects will also be made unmanaged by this method. Note that this method can be used to manage or unmanage only a Node Object and its corresponding interface objects.

    Parameters:
    obj - The Node object to be managed or unmanaged.
    isManaged - true - if node is to be managed and false - if node is to be unmanaged
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.

    getNetworks

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

    Returns:
    Vector of Strings, containing the keys of all the Network objects in the database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getNodes

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

    Returns:
    Vector of Strings, containing the keys of all the Node objects in the database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getInterfaces

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

    Returns:
    Vector of Strings, containing the ipAddress property of all the IpAddress objects in the database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getLocalNetworkAddrs

    java.lang.String getLocalNetworkAddrs()
                                          throws java.rmi.RemoteException
    Gets the local network address. This method is used to get the parent network address of the host running the Web NMS server.

    Returns:
    The parent network address of the host running the Web NMS server, as a string.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    register

    boolean register(TopoActionListener listener)
                     throws java.rmi.RemoteException
    To register for notifications from TopoAPI, about topology database changes. The Observers who want to get notified of any changes in the topology database with data of both the ManagedObject that was before the update and after update should implement the interface com.adventnet.nms.topodb.TopoActionListener. The registered TopoObserver will be notified about the changes in database like new additions of ManagedObjects, Property Update of Managed Objects, Status Update of ManagedObjects, Manage Update of ManagedObjects , Discover Update of Network Objects etc.

    Parameters:
    listener - The TopoActionListener interface implementor object to which notifications have to be sent.
    Returns:
    true if the registration is sucessful, false otherwise
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    TopoActionListener, unregister(TopoActionListener)

    unregister

    boolean unregister(TopoActionListener listener)
                       throws java.rmi.RemoteException
    To unregister from getting notifications, about topology database changes , from the TopoAPI. This method can be used when the applications no longer want to get notified by the TopoAPI, about the topology database changes.

    The argument passed to this method should be the same TopoActionListener instance that was passed with the previous call to the #register(TopoObserver) method.

    Parameters:
    listener - The TopoActionListener interface implementor object which was previously registered with the TopoAPI.
    Returns:
    true if unregister operation is successful, false otherwise
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    TopoActionListener, register(TopoActionListener)

    lock

    ManagedObject lock(ManagedObject obj,
                       int lock_type,
                       int timeout)
                       throws java.rmi.RemoteException,
                              TimeoutException
    Apply the specified lock to the ManagedObject. This method will lock the specified ManagedObject, by applying the given type of lock, which will actually define access levels for the object. The TopoAPI doesn't provide any locking mechanism for the ManagedObjects itself, but makes use of the com.adventnet.nms.util.LockableObject interface implementation. That interface defines the lock types and various other methods to implement the locking mechanism as required by the user. The third argument specifies the time in seconds as to how long to wait to obtain the lock for the ManagedObject.

    Parameters:
    obj - The ManagedObject that is to be locked.
    lock_type - The type of lock to be applied.
    timeout - Time, in seconds, to wait to acquire the lock.
    Returns:
    The ManagedObject with the lock set in it's lockId property.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    TimeoutException - if the thread is not able to acquire a lock of specified type on the specified object for the specified period of time.
    See Also:
    LockableObject

    unlock

    void unlock(ManagedObject obj)
                throws java.rmi.RemoteException
    Unlock the specified ManagedObject. This method will unlock the given ManagedObject, releiving it of all the previously applied locks.

    Parameters:
    obj - The ManagedObject that is to be unlocked.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    LockableObject

    checkWritePermission

    boolean checkWritePermission(ManagedObject obj)
                                 throws java.rmi.RemoteException
    Check whether this instance of the ManagedObject can be written to the database. This method checks whether the specified instance of the ManagedObject currently holds a valid write lock, so that it can be written to the database.

    Parameters:
    obj - The ManagedObject instance that is to be checked whether it has a write lock.
    Returns:
    true if the object holds a write lock, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    LockableObject

    getCurrentLockType

    int getCurrentLockType(ManagedObject obj)
                           throws java.rmi.RemoteException
    Get the lock type currently held by the specified instance of the ManagedObject. This method is useful in finding out what type of lock this instance of the ManagedObject holds, when multiple instances hold different types of locks.

    Parameters:
    obj - ManagedObject instance for which the lock type is to be obtained.
    Returns:
    The lock type value, as defined in the LockableObject interfae, currently held by the specified instance of the ManagedObject. If the object instance is not locked previously, this method returns UNKNOWN_LOCK.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    clearLockForObject

    void clearLockForObject(java.lang.String name,
                            int lockType)
                            throws java.rmi.RemoteException
    Release the specified lock type unconditionally for the ManagedObject with the given name. If under some exceptional condition, a ManagedObject instance that was holding a lock, is lost before it has unlocked, then it will result in all subsequent requests for locks over that ManagedObject to fail. In such a case, this method can be used to unconditionally release the specified lock type by giving just the name of the ManagedObject. But the effect of this method depends entirely on the implementation of the LockableObject interface.

    Parameters:
    name - Name of the ManagedObject to be unlocked.
    lockType - Type of the lock to be unlocked.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    getObjectNamesWithProps

    java.util.Vector getObjectNamesWithProps(java.util.Properties p)
                                             throws java.rmi.RemoteException,
                                                    NmsStorageException,
                                                    UserTransactionException
    This method can be used to fetch the keys of managed objects which are matching the given criteria. The criteria can be passed in the form of Properties object containing the selection criteria to fetch the objects from the database.

    Specified by:
    getObjectNamesWithProps in interface CommonAPI
    Parameters:
    p - matching criteria.
    Returns:
    Vector of keys matching the criteria specified. The objects for which the search is made are listed below:
    • ManagedObject
    • Node
    • SnmpNode
    • Network
    • Other MO extensions

    The search can be done by either giving the exact values of the object to be searched or by using some wild card character in the search. Some of the wild card characters, that can be used are listed below with their explanations.
     

    Wild Card Character Description
    * (Asterisk) This is used to search for objects that begin with a particular value.
    Example: If the names of all the objects starting with the name "test" is needed, then the property key - name and the value test* is given.
    ! (Exclamation Mark) This is used for filtering the search using NOT operator. 
    Example: If all the objects whose name does not start with "test" is required, then property key - name and value - !test is given.
    , (Comma) This is used for searching objects where a single property key has different values. 
    Example: If all the objects with names starting with "abc" or "xyz" is required, then property key -name and value "abc*,xyz*"is given
    \ (Back Slash) This is used when the name of the object itself contains a comma. This character is called an escape sequence, since it avoids searching of the objects, as if it were two different names. 
    Example: If an object with name "a,b" has to be searched, then the property key - name and the value - "a\,b " is given.
    <between> value1 and value2 This is used to get objects with some numeric values within a specific range. 
    Example: If object names with poll interval  value ranging from 300 to 305 is required, then the property key should be pollinterval and the value has to be <between> 300 and 305 .
    It must be noted that the first number is smaller than the second number. Only the values in between the given values will be matched.
    <> This is used for matching exact type of string or integer value. 
    Example: The value <ab> fetches the object whose name is ab.

    Here any number of properties can be passed as a matching criteria. The names of the objects matching all the properties is returned. If the matching of object names to be performed with OR, the method TopoAPI.getObjectNamesWithProps(Properties prop, boolean performOR) can be used. The properties passed can be any MO Properties or User defined Properties.

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getObjects

    java.util.Vector getObjects(java.lang.String classname,
                                java.util.Properties match)
                                throws java.rmi.RemoteException,
                                       NmsStorageException,
                                       UserTransactionException
    Gets a Vector of objects matching the given criteria. The criteria can be a list of properties taken from properties of ManagedObject or its derived objects. The objects will be selected only if they match with all the properties given in the match criteria, ie., it uses the AND operator while querying the tables with the match criteria to obtain the required result. The user properties being stored for objects also can be used in the match criteria. The classname signifies, the tables that must be considered for the selection of objects.

    For example, to fetch all the SNMP Nodes from the Topology Database, the following code snippet can be used.

     Properties criteria = new Properties();
     criteria.put("isSNMP","true");
     Vector MOVector  =  topoAPI.getObjects("SnmpNode",criteria);
     
    Now the MOVector will contain all the snmp nodes filled with all properties from the tables which are associated with the MO hierarchy of SnmpNode. ie., it will fetch data from the tables ManagedObject, TopoObject, Node, and SnmpNode.

    This method returns only those objects whose classname property is the one passed to this method. If the given classname is incorrect, i.e., any of the property name given in the match criteria is not found in the properties of MO associated with the given classname or in the user properties table, then this method will return null. For example, in the above example, if the classname passed as "ManagedObject" instead of "SnmpNode", then this method would return null. Because the match criteria "isSNMP" is not found in the properties of "ManagedObject".

    Note: As of Web NMS 2.3 release, this method was deprecated as it had its own limitations like it would fetch data only from the particular table which is associated for the given classname which is passed as argument for this method. It won't consider the other tables which are fall in the class hierarchy for the given classname. This has been fixed in SP2 over WebNMS 2.3 so that the deprecated tag also been removed.

    Note : Only the properties stored in database will be filled into the Objects returned from getObjects() method . The other properties like 'childrenKeys','NodeList','InterfaceList','groupNames','groupMembers' etc will not be filled in the objects .

    Parameters:
    classname - the classname for the objects that are selected.
    match - the criteria based on which the objects to be selected from the database.
    Returns:
    a Vector of managed objects matching the given criteria. Returns 'null' when the classname is null or no matching objects found in the database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getDbObjects

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

    Get the list of names of all the objects in the Topology database. This method will return a list containing the keys (names) of all the ManagedObjects in the database, as a DBVector object.

    Note : As DBVector is not a serializable object, this method cannot be used over RMI.

    Returns:
    List of names of all the ManagedObjects in the topology database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    getNumObjects

    int getNumObjects()
                      throws java.rmi.RemoteException,
                             NmsStorageException,
                             UserTransactionException
    Returns the current total number of ManagedObjects in Topology Database.

    Returns:
    The total number of ManagedObjects in the topology database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getNumNetworks

    int getNumNetworks()
                       throws java.rmi.RemoteException,
                              NmsStorageException,
                              UserTransactionException
    Returns the current total number of Network Objects in Topology Database.

    Returns:
    The total number of Network Objects in the topology database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getNumNodes

    int getNumNodes()
                    throws java.rmi.RemoteException,
                           NmsStorageException,
                           UserTransactionException
    Returns the current total number of Node objects in Topology Database.

    Returns:
    The total number of Node Objects in the topology database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getNumInterfaces

    int getNumInterfaces()
                         throws java.rmi.RemoteException,
                                NmsStorageException,
                                UserTransactionException
    Returns the current total number of Interface objects in Topology Database.

    Returns:
    The total number of IpAddress Objects in the topology database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getNodeProperties

    java.util.Properties getNodeProperties(java.lang.String nodeName)
                                           throws java.rmi.RemoteException,
                                                  NmsStorageException,
                                                  UserTransactionException
    Gets the properties of the Node object with the given key. This method is equivalent to doing a Node.getProperties() call over the corresponding Node object.

    Parameters:
    nodeName - key of the Node object whose properties are to be obtained.
    Returns:
    The properties of the specified Node as a Properties object.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getNodesOfNetwork

    java.util.Vector getNodesOfNetwork(java.lang.String net)
                                       throws java.rmi.RemoteException,
                                              NmsStorageException,
                                              UserTransactionException
    Gets the keys of all the Node objects belonging to the given network.

    Parameters:
    net - key of the Network object for which the list of Node object keys is to be obtained.
    Returns:
    A Vector of Strings containing the keys of all the node objects belonging to the given network.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getInterfacesOfNode

    java.util.Vector getInterfacesOfNode(java.lang.String nodeName)
                                         throws java.rmi.RemoteException,
                                                NmsStorageException,
                                                UserTransactionException
    Gets the keys of all IpAddress objects belonging to the given Node.

    Parameters:
    nodeName - Key of the Node object for which the list of IpAddress object keys is to be obtained.
    Returns:
    A vector of Strings containing the keys of all the IpAddress objects belonging to the given node.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getInterfacesOfNetwork

    java.util.Vector getInterfacesOfNetwork(java.lang.String netName)
                                            throws java.rmi.RemoteException,
                                                   NmsStorageException,
                                                   UserTransactionException
    Gets the keys of all IpAddress objects belonging to the given Network.

    Parameters:
    netName - Key of the Network object for which the list of IpAddress object keys is to be obtained.
    Returns:
    A vector of Strings containing the keys of all the IpAddress objects belonging to the given network.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    ManagedObject.getKey()

    getIpAddressesOfNetwork

    java.util.Vector getIpAddressesOfNetwork(java.lang.String netName)
                                             throws java.rmi.RemoteException,
                                                    NmsStorageException,
                                                    UserTransactionException
    Gets the ipAddresses belonging to the given Network.

    Parameters:
    netName - Key of the Network object for which the list of IpAddresses is to be obtained.
    Returns:
    A vector of Strings containing all the IpAddresses belonging to the given network.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    addNodeToTopoDB

    boolean addNodeToTopoDB(java.lang.String ipaddr,
                            java.lang.String netmask)
                            throws java.rmi.RemoteException,
                                   NmsStorageException,
                                   UserTransactionException
    Discovers and adds a node of the given ip address and netmask to the database. This method internally makes use of the TopoAPI method addNode(ManagedObject obj) to discover and add the node to the database.

    Parameters:
    ipaddr - IpAddress of the node to be added.
    netmask - Netmask of the network to which this node belongs.
    Returns:
    true on successfully adding the node, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    addNode(ManagedObject)

    addNodeToTopoDB

    boolean addNodeToTopoDB(java.lang.String ipaddr,
                            java.lang.String netmask,
                            java.lang.String community,
                            int snmpPort)
                            throws java.rmi.RemoteException,
                                   NmsStorageException,
                                   UserTransactionException
    Discovers and adds a node of the given IP address, netmask, SNMP community and SNMP port to the database. This method internally makes use of the TopoAPI method addNode(ManagedObject, boolean, boolean) to discover and add the node to the database. This method does not override the seed file constraints, if any, specified for the node but adds the node to the database even if it is not reachable from the NMS server. This method is particularly useful in adding nodes that have SNMP agents with different community or communicate on a different port, than the others.

    Parameters:
    ipaddr - IP Address of the node to be added.
    netmask - Netmask of the network to which this node belongs.
    community - Snmp Community for the node.
    snmpPort - Port number on which to communicate to the SNMP agent of the node.
    Returns:
    true on successfully adding the node, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    addNode(ManagedObject, boolean, boolean)

    addNodesToTopoDB

    boolean addNodesToTopoDB(java.lang.String startIpAddr,
                             java.lang.String endIpAddr,
                             java.lang.String netmask)
                             throws java.rmi.RemoteException,
                                    NmsStorageException,
                                    UserTransactionException
    Discovers and adds nodes of the given IP address range to the database. Note that the range of IP addresses specified must all belong to the same network, with the specified netmask. This method internally makes use of the TopoAPI method addNodeToTopoDB(String, String) to add the nodes to the database.

    Nodes added through this method all go through all the filters and seed file constraints, and hence some of them may not be added to the database. Note that this method tries to add all the nodes specified in the range, and does not return when it encounters any error while adding any of the nodes. This method does not add any node to the database if the specified range is illegal (i.e. end IP address is lower in the specified range than the start IP address).

    Also note that this method will return true regardless of nodes getting added to the database. It will only check whether the specified address range belongs to the same network.

    Parameters:
    startIpAddr - Starting IP address of the range of IP addresses to be added to the database.
    endIpAddr - End IP address of the range of IP address to be added to the database.
    netmask - Netmask of the network to which the IP addresses of the given range all belong.
    Returns:
    false if the start IP address and the end IP address does not belong to the same network or if the given IP address or the netmask is of invalid format or if the range is illegal, true otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    addNodeToTopoDB(String, String), setAddressRangeToDiscover(String, String, String, String), removeAddressRangeToDiscover(String, String, String, String)

    addNodesToTopoDB

    boolean addNodesToTopoDB(java.lang.String[] ipAddrs,
                             java.lang.String netmask)
                             throws java.rmi.RemoteException,
                                    NmsStorageException,
                                    UserTransactionException
    Discovers and adds nodes of the given list of IP addresses to the database. Note that the list of IP addresses specified must all belong to the same class of network, with the specified netmask. This method internally makes use of the TopoAPI method addNodeToTopoDB(String, String) to add the nodes to the database.

    Nodes added through this method all go through all the filters and seed file constraints, and hence some of them may not be added to the database. Note that this method tries to add all the nodes specified in the list, and does not return when it encounters any error while adding any of the nodes.

    Also note that this method will return true regardless of nodes getting added to the database. This method actually does not check whether all the addresses specified in the list belong to the same class of Network (in other words, all the IP addresses specified in the list should have the same netmask), and hence users should take care of this situation themselves.

    Parameters:
    ipAddrs - List of IP addresses of nodes to be added to the database.
    netmask - Netmask of the network to which the IP addresses of the given list all belong.
    Returns:
    true always.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    addNodeToTopoDB(String, String), setAddressRangeToDiscover(String, String, String, String), removeAddressRangeToDiscover(String, String, String, String)

    removeNodeFromTopoDB

    boolean removeNodeFromTopoDB(java.lang.String ipaddr)
                                 throws java.rmi.RemoteException,
                                        NmsStorageException,
                                        UserTransactionException
    Removes the node of the given IP address from the topology database. This method would delete the interface object corresponding to the given IP address and would delete the parentNode object only if no other interface exists for that parentNode.

    Parameters:
    ipaddr - IP address of the Node object to be deleted.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    removeNodesFromTopoDB

    boolean removeNodesFromTopoDB(java.lang.String[] ipaddrs)
                                  throws java.rmi.RemoteException,
                                         NmsStorageException,
                                         UserTransactionException
    Removes the nodes of the given list of IP address from the database. This method internally makes use of removeNodeFromTopoDB(String) TopoAPI method to delete the nodes and it's corresponding interface objects.

    Parameters:
    ipaddrs - List of IP address of the Node objects to be deleted.
    Returns:
    true if the operation was successful, false if the input is null or empty.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getGroupNames

    java.util.Vector getGroupNames()
                                   throws java.rmi.RemoteException,
                                          NmsStorageException,
                                          UserTransactionException
    Gets the names of all the Group MOs in the database. A Group MO is one which implements the GroupInterface interface or for which the isGroup property of the MO is set to true.

    Returns:
    A vector of Strings containing the keys (names) of all the Group MOs.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    setGroupsForMO

    boolean setGroupsForMO(java.lang.String name,
                           java.lang.String[] groupNames,
                           boolean append)
                           throws java.rmi.RemoteException,
                                  NmsStorageException,
                                  UserTransactionException
    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.

    Sets the groups to which a ManagedObject should belong to. Setting the groupNames of the ManagedObject using the setGroupNames method of ManagedObject class and a subsequent call of TopoAPI updateObject over the ManagedObject instance will not bear fruit. Groups of ManagedObjects can be set only using this API.

    Parameters:
    name - Name of the ManagedObject to which the groups have to be assigned.
    groupNames - Names (one or more) of the ManagedGroupObjects to which this node should be a child.
    append - boolean to say whether the given groupNames should override the existing ones or be appended to them.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    setAddressRangeToDiscover

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

    Please note that the network is added to the topology database if no such network already exists in the database. After adding the network, discovery of the network starts off in a seperate thread with the restricted given range of ipaddresses. Unlike the addNodesToTopoDB method, this method returns immediately after starting off a discovery thread for the network.

    And also note that this method wouldn't affect already discovered nodes. But it can prevent discovery of the nodes which were about to be discovered.

    Important Note

    The discovery range for the network is written into the seed file for persistence so that the seed file could be edited by the user before restarting the server.

    Parameters:
    startIP - The IP Address from which discovery should start.
    endIP - The IP Address from which discovery should end.
    network - The IP Address of the network.
    netmask - The netmask of the network.
    Returns:
    true on successfully setting the range of discovery.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    removeAddressRangeToDiscover(String, String, String, String), addNodesToTopoDB(String, String, String), addNodesToTopoDB(String[], String)

    removeAddressRangeToDiscover

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

    Important Note : The discovery range for the network is written into the seed file for persistence so that the seed file could be edited by the user before restarting the server.

    Parameters:
    startIP - The IP Address from which discovery should discard.
    endIP - The IP Address upto which discovery should discard.
    network - The IP Address of the network.
    netmask - The netmask address of the network.
    Returns:
    true on successfully preventing discovery of the given range of IPs and returns false when no such network exists in the database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    setAddressRangeToDiscover(String, String, String, String), addNodesToTopoDB(String, String, String), addNodesToTopoDB(String[], String)

    addNetwork

    boolean addNetwork(java.lang.String network,
                       java.lang.String netmask)
                       throws java.rmi.RemoteException,
                              NmsStorageException,
                              UserTransactionException
    Adds a network object of given IP address and netmask to the topology database and starts off its discovery. The network object is first passed through all the discovery filters, which might prevent it from getting added to the database. This method internally makes use of the addObject(ManagedObject) method to add the network object to the database.

    If the network object is successfully added to the database, then this method also adds a TO_DISCOVER net entry for the network in the discovery engine configuration file (seed.file).

    Parameters:
    network - The IPAddress of the network to be added.
    netmask - The netmask for the network.
    Returns:
    true if the operation was successful. false if the arguments are of invalid format or if the object was not added to the database or if the network object with the given IP address already exists in the database.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    addObject(ManagedObject)

    changeDiscInterval

    boolean changeDiscInterval(java.lang.String net,
                               int seconds)
                               throws java.rmi.RemoteException
    To change the Discovery interval. This will modify the discovery interval, which is the time in seconds to wait between discovery of two nodes, for the given network. Currently, discovery for all networks will use the seed file value for discovery interval. This method can be used to specify different discovery interval values for different networks at run time. Note that this method does not update the seed file, and hence the change in discovery interval value will not be available across restarts of NMS server.

    Parameters:
    net - Network (address) for which the discovery interval is to be changed.
    seconds - The value of discovery interval in seconds.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    setDiscoveryParameters(Properties)

    changePingRetries

    boolean changePingRetries(java.lang.String net,
                              int retries)
                              throws java.rmi.RemoteException
    To change the Ping retries. This will modify the ping retries, which is the number of consecutive failed ICMP ping attempts to declare that a node is not alive, for the given network. ICMP ping is used both during discovery as well as status polling. Currently, all networks will use the seed file value for ping retries. This method can be used to specify different ping retries values for different networks at run time. Note that this method does not update the seed file, and hence the change in ping retries value will not be available across restarts of NMS server.

    Parameters:
    net - Network (address) for which the ping retries is to be changed.
    retries - The value of ping retries.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    setDiscoveryParameters(Properties)

    changeSnmpRetries

    boolean changeSnmpRetries(java.lang.String net,
                              int retries)
                              throws java.rmi.RemoteException
    To change the SNMP ping retries. This will modify the SNMP ping retries, which is the number of consecutive failed SNMP ping attempts to declare that a SNMP enabled node is not alive, for the given network. SNMP ping is used both during discovery as well as status polling. Currently, all networks will use the seed file value for SNMP ping retries. This method can be used to specify different SNMP ping retries values for different networks at run time. Note that this method does not update the seed file, and hence the change in SNMP ping retries value will not be available across restarts of NMS server.

    Parameters:
    net - Network (address) for which the SNMP ping retries is to be changed.
    retries - The value of SNMP ping retries.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    setDiscoveryParameters(Properties)

    setDiscoveryParameters

    boolean setDiscoveryParameters(java.util.Properties prop)
                                   throws java.rmi.RemoteException,
                                          NmsStorageException,
                                          UserTransactionException
    Set values for various discovery parameters. This method can set values for the various discovery engine configuration parameters at run time. These are actually the parameters that are configurable through the seed file. This method updates the seed file also with the given values. The following is the list of discovery parameters that can be set using this method.
     DISCOVERY_INTERVAL      Time to wait between discovering nodes, in
                            seconds.
     PING_RETRIES    Number of ping retries to be used during discovery.
    
     SNMP_RETRIES    Number of snmp query retries to be used during
                    discovery.
    
     SNMP_TIMEOUT    Snmp timeout value in seconds for all snmp queries.
    
     DISCOVER        Whether automatic discovery is to be done or not.
    
     REDISCOVER_INTERVAL     Time between two discoveries for a network,
                            in hours.
    
     HOUR    The hour(s) of the day in which discovery for networks is
            scheduled.
    
     DAY_OF_THE_MONTH        The day(s) of the months on which discovery fori
                            networks is scheduled.
    
     DAY_OF_THE_WEEK The day(s) of the week on which discovery for i
                            network is scheduled.
    
     REDISCOVER_ALREADY_DISCOVERED   Whether the nodes discovered in the
                                    previous disocvery have to discovered in the current
                                    discovery or not.
    
     READ_COMMUNITY  The SNMP read communities to be used.
    
     WRITE_COMMUNITY The SNMP write communities to be used.
    
     ENABLE_SNMP_DISCOVERY  Whether to enable SNMP discovery or not.
    
     ENABLE_ICMP_DISCOVERY   Whether to enable ICMP discovery or not.
    
     ENABLE_SNMPV3_DISCOVERY Whether to enable SNMPV3 discovery or not.
    
     SNMP_PORTS      Ports in which SNMP Agent is running in the devices
    
     SNMPV3_USERNAMES        The SNMPv3 user who is authorized perform v3 SNMP transactions
    
     SNMPV3_CONTEXTNAME The context name, where context is a collection of management information (range of OIDS) that are accessible by an SNMP entity.
    
     ENABLE_LOG      Whether to log debug messages related to discovery.
    
     DISCOVER_LOCALNET               Whether to discover the localnet or not.
    
     NATIVE_PING (consists of parameters ICMP_TIMEOUT,ICMP_RETRIES,ICMP_SWEEP_PACKETS,ICMP_SWEEP_SLEEP_INTERVAL,ICMP_DEBUG_LEVEL,PING_SWEEP)
    
     INITIAL_PARAMETERS (consists of parameters DISCOVERY_INTERVAL,REDISCOVER_INTERVAL,PING_RETRIES,SNMP_RETRIES,SNMP_TIMEOUT,ICMP_RETRIES,ICMP_TIMEOUT)
    
     TO_DISCOVER (consists of parameters NETWORK_ID,NETMASK,DHCP,START_IP,END_IP,SNMP_VERSION,SNMPV3_USERNAMES,SNMPV3_CONTEXTNAME,SNMPAGENTPORTS,READ_COMMUNITY)
    
     NOT_TO_DISCOVER (consists of parameters NETWORK_ID,NETMASK)
    
     TO_DISCOVERIP (consists of parameters NODE_ID,NETMASK,COMMUNITY,SNMPAGENTPORT,USERNAME,CONTEXT_NAME,SNMP_VERSION,DISCOVER_PARENTNET)
    
     NOT_TO_DISCOVERIP (consists of parameters NODE_ID,NETMASK)
    
     ALLOW_CRITERIA  To discover only those objects matching the criteria.
    
     DISALLOW_CRITERIA       To prevent the discovery of objects matching the criteria.
     

    Refer to the seed file for the description of the above tags

    An example code snippet on how to set the above properties using this method is given below. Properties p = new Properties(); //Properties object for INITIAL_PARAMETERS and NATIVE_PING tags p.put("REDISCOVER_INTERVAL",String.valueOf(12)); p.put("ICMP_TIMEOUT",String.valueOf(1)); Properties p1 = new Properties(); //Properties object for TO_DISCOVER, NOT_TO_DISCOVER, TO_DISCOVERIP and NOT_TO_DISCOVERIP tags. p1.put("NETWORK_ID","192.168.4.0"); p1.put("NETMASK","255.255.255.0"); p1.put("START_IP","192.168.4.1"); p1.put("END_IP","192.168.4.254"); p1.put("DHCP",String.valueOf(true)); Vector v= new Vector(); v.addElement(p1); Properties p2 = new Properties(); p2.put("net",v); Properties discParams = new Properties(); discParams.put("TO_DISCOVER",p2); discParams.put("INITIAL_PARAMETERS",p); discParams.put("DISCOVERY_INTERVAL", String.valueOf(5)); // For parameters under DISCOVERY tag discParams.put("SNMP_RETRIES", String.valueOf(2)); // For parameters under DISCOVERY tag topoapi.setDiscoveryParameters(discParams);

    The table below shows the procedure for setting the parameters under various tags.

    Main Tags Procedure
    <DISCOVER> Construct a Properties object with (parameter, parameter value) as the (key, value) pair where,
    parameter - fields under DISCOVER tag
    paramater value - corresponding values for the above keys
    and pass it to the setDiscoveryParameters() method
    <INITIAL_PARAMETERS>, <NATIVE_PING>,
    <ALLOW_CRITERIA> and <DISALLOW_CRITERIA>
    Construct a Properties Object with (parameter, parameter value) as the (key,value) pair.
    Pass the above Properties Object as the value to another <Properties object> with the main tag as the key.

    This should be passed to the setDiscoveryParamaters() method.
    <TO_DISCOVER, <NOT_TO_DISCOVER>, <TO_DISCOVERIP> and <NOT_TO_DISCOVERIP> Construct a Properties Object with (parameter, parameter value) as the (key,value) pair. Add this Properties Object to a Vector. Pass the above Vector as the value to <Properties Object1> with net / ip as the key

    (key = net for TO_DISCOVER and NOT_TO_DISCOVER tags)
    and key = ip (for TO_DISCOVERIP and NOT_TO_DISCOVERIP tags)

    Pass the above <Properties Object1> as the value to <Properties Object2> with main tag as the value.

    which in turn needs to be passed to the setDiscoveryParamaters() method.

    Note that any change in the parameters will have immediate effect if discovery is currently happening. Otherwise, the changes will be used during next discovery. Any change in value of these parameters will have effect over the discovery process of all the networks. If any one of REDISCOVER_INTERVAL, DAY_OF_THE_WEEK, DAY_OF_THE_MONTH or HOUR parameter is changed, discovery for all networks will be stopped and restarted, after the changes are applied.

    Parameters:
    prop - The Properties object containing the discovery parameters and their corresponding values.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    getDiscoveryParameters(), getSeedFileParameters(), getDiscoveryParameters()

    getDiscoveryParameters

    java.util.Properties getDiscoveryParameters()
                                                throws java.rmi.RemoteException
    Gets the current value of the various discovery parameters. This method gets those values as a Properties object. The keys and their values in the Properties object returned would be the following. The values of the properties will be all Strings and users have to type cast the values as specified alongside each property.
     DISCOVERY_INTERVAL      Time to wait between discovering nodes, in
                            seconds (Integer). 

    PING_RETRIES Number of ping retries to be used during discovery (Integer).

    SNMP_RETRIES Number of snmp query retries to be used during discovery (Integer).

    SNMP_TIMEOUT Snmp timeout value in seconds for all snmp queries (Integer).

    DISCOVER Whether automatic discovery is to be done or not (Boolean).

    REDISCOVER_INTERVAL Time between two discoveries for a network, in hours (Integer).

    HOUR The hour(s) of the day in which discovery for networks is scheduled (String).

    DAY_OF_THE_MONTH The day(s) of the months on which discovery fori networks is scheduled (String).

    DAY_OF_THE_WEEK The day(s) of the week on which discovery for i network is scheduled (String).

    REDISCOVER_ALREADY_DISCOVERED Whether the nodes discovered in the previous disocvery have to discovered in the current discovery or not (Boolean).

    READ_COMMUNITY The SNMP read communities to be used (String).

    WRITE_COMMUNITY The SNMP write communities to be used (String).

    For example, the following code snippet demonstrates how this method can be used for getting the discovery parameters.

     
            Properties prop = topoapi.getDiscoveryParameters ();
            String str = (String) prop.remove ("DISCOVERY_INTERVAL");
            int discInt = (Integer.valueOf (str)).intValue ();
     
     

    Returns:
    A Properties object with the current values of the various discovery parameters.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    setDiscoveryParameters(Properties), getSeedFileParameters(), setDiscoveryParameters(java.util.Properties)

    dontDiscoverNetwork

    boolean dontDiscoverNetwork(java.lang.String network,
                                java.lang.String netmask)
                                throws java.rmi.RemoteException
    Mark the network as not to be discovered in the seed file. This method causes a NOT_TO_DISCOVER net statement to be included in the seed file for the given network, at run time. Note that there would be no effect of this method call in the current run of the NMS server, including rediscovery, and the network will not be discovered only on a subsequent restart of the NMS server.

    Parameters:
    network - The IPAddress of the network not to be discovered.
    netmask - The Netmask of the network not to be discovered.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    dontDiscoverNode

    boolean dontDiscoverNode(java.lang.String ip,
                             java.lang.String mask)
                             throws java.rmi.RemoteException
    Mark the node as not to be discovered in the seed file. This method causes a NOT_TO_DISCOVER ip statement to be included in the seed file for the given node, at run time. Note that if the node was already discovered, then the object will continue to remain in the database. But the node will not be discovered during the rediscovery of the network.

    Parameters:
    ip - The IPAddress of the node not to be discovered.
    mask - The Netmask of the node not to be discovered.
    Returns:
    true if the operation was successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    getSeedFileParameters

    java.util.Hashtable getSeedFileParameters()
                                              throws java.rmi.RemoteException
    Get the values of various seed file discovery parameters. This method is useful to get discovery parameters from seed file, that are of complex data types (unlike the getDiscoveryParameters() method which is useful for getting values of primitive data types). The following parameters from the seed file are returned in the form of a hashtable. The key to get the property from the hashtable and it's corresponding data type are given below.
     Key                     Data Type 

    InNets Vector of Strings OutNets Vector of Strings OutNetMasks Vector of Strings InNodes Vector of Strings OutNodes Vector of Strings OutNodeMasks Vector of Strings NodeMasks Vector of Strings Netmasks Vector of Strings Communities Hashtable (key : network address)of Hashtables (key : node IP address) LowVal Hashtable of Vectors of Strings (key : network address) HighVal Hashtable of Vectors of Strings (key : network address) SNMPPort Hashtable (key : network address)of Hashtables (key : node IP address)

    Returns:
    Hashtable containing the values of various seed file discovery parameters.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    setDiscoveryParameters(Properties), getDiscoveryParameters()

    setDisTopoLoggingMode

    void setDisTopoLoggingMode(boolean mode)
                               throws java.rmi.RemoteException
    Enable or Disable logging messages in the discoveryLogs.txt file. This method is useful to stop or start logging messages in the discovery log file, at run time.

    Parameters:
    mode - true to enable logging, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    clearRouterBusyFlag

    void clearRouterBusyFlag()
                             throws java.rmi.RemoteException
    Method to be used only by the HTML client for debugging purpose. Users should not use this method.

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    registerTopoSubscriber

    boolean registerTopoSubscriber(TopoSubscriber toposbs,
                                   java.lang.String containerObjectName)
                                   throws java.rmi.RemoteException
    To register for notifications from TopoAPI, about changes in a particular container object and it's children. The container object is one that implements the ContainerInterface. Applications, that want to receive notification about a container object change, must implement the TopoSubscriber interface, and register with the TopoAPI using this method.

    Once registered, the update method of the application implementing the TopoSubscriber interface will be called, for any change in the corresponding container object.

    Parameters:
    toposbs - The TopoSubscriber interface implementor object to which notifications have to be sent.
    containerObjectName - The name of the container object in the topology database, whose changes is to be notified.

    Returns:
    true if registration is sucessfull, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    TopoSubscriber, deregisterTopoSubscriber(TopoSubscriber)

    deregisterTopoSubscriber

    boolean deregisterTopoSubscriber(TopoSubscriber toposbs)
                                     throws java.rmi.RemoteException
    To deregister from receiving notifications from TopoAPI, about changes in a particular container object and it's children. Applications, that have already registered for notifications, using the registerTopoSubscriber method, can use this method to stop reveiving the notifications.

    Parameters:
    toposbs - The TopoSubscriber interface implementor object for which notifications are not to be sent anymore.

    Returns:
    true if deregistration is sucessfull, false otherwise.

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    TopoSubscriber, registerTopoSubscriber(TopoSubscriber, String)

    addTopoBulkListener

    void addTopoBulkListener(TopoBulkListener listener)
                             throws java.rmi.RemoteException
    To register as a listener to receive notifications from TopoAPI when the bulk-delete operation is carried out. Bulk-delete can be performed using the deleteObjectAndSubElements(String) method or using the deleteObjects(String,Properties). Listeners that need to get this notification about bulkdelete/addObjects have to implement the TopoBulkListener interface Once registered as a listener, the TopoBulkListener.deleteObject(XMLNode) will be called, when the deleteObjectAndSubElements() method is invoked and the method TopoBulkListener.addObjects(Vector) will be called, when the addObjects(String,Vector) method is invoked

    Parameters:
    listener - The object that implements com.adventnet.nms.topodb.TopoBulkListener interface, to which notifications have to be sent.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    TopoBulkListener, deleteObjectAndSubElements(String), removeTopoBulkListener(com.adventnet.nms.topodb.TopoBulkListener)

    removeTopoBulkListener

    void removeTopoBulkListener(TopoBulkListener listener)
                                throws java.rmi.RemoteException
    To unregister the previously registered TopoBulkListener from TopoAPI. Applications that have already registered as TopoBulkListener using addTopoBulkListener(TopoBulkListener) method, can use this method to stop receiving notifications.

    Parameters:
    listener - The TopoBulkListener instance which was previously registered with the TopoAPI
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    TopoBulkListener, deleteObjectAndSubElements(String), deleteObjects(String,Properties), addObjects(String,Vector), addTopoBulkListener(com.adventnet.nms.topodb.TopoBulkListener)

    deleteObjectAndSubElements

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

    This method can be used for deleting an object that is either a Container parent, Network, or a Group object that have other objects as its sub-elements, under which case, all their sub-elements would also be deleted. When this method is used for deleting objects that are other than the above mentioned three cases, (for. eg. a Node or an Interface object that is neither a Container parent nor a Group object) it would only result in a call to #deleteObject(ManagedObject,boolean) with a true for the second parameter.

    Deleting a Network object using this method will also delete all the Node and IpAddress objects belonging to that network. Also if any of the Node or IpAddress is a container, the children of the same will also be deleted till the last level.

    Deleting a Container object (Object implementing ContainerInterface) using this method will also delete all its children till the last level of objects, from the database.

    Deleting a Group object (Object implementing GroupInterface) using this method will also delete all it's first level member objects, irrespective of whether they belong to other groups or not. If any of the member object to be deleted is a container, the children of the same will be deleted till the last level.

    The applications that have registered themselves as TopoBulkListeners using addTopoBulkListener(TopoBulkListener) , would be notified about this delete operation by a call to their TopoBulkListener.deleteObject(XMLNode) method.

    Please note that deletion of objects using this method would not be intimated to the TopoObservers.

    Parameters:
    objKey - The key (name) of the Object to be deleted.
    Returns:
    true if the deletion of the object and all its sub-elements is successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.
    See Also:
    TopoBulkListener, addTopoBulkListener(TopoBulkListener)

    getObjectNamesWithProps

    java.util.Vector getObjectNamesWithProps(java.util.Properties p,
                                             boolean performOR)
                                             throws java.rmi.RemoteException,
                                                    NmsStorageException,
                                                    UserTransactionException
    Returns a Vector containing the keys of all the MOs, whose properties match the one given in the argument. The keys of the Properties object passed in the argument must be the same as the property names of the MOs. Also, this method will succeed only for the MO properties that are stored in the database table columns.

    This method compares the (key, value) pairs of the Properties argument with the (property, value) pairs of the MOs, and returns the keys of the objects where there is a match.

    If performOr is false, then keys are returned only for objects which match all the (key, values) pairs specified in the argument. If performOr is true, then keys are returned for objects that match any of the given (key, value) pairs.

    Note that wild card patterns can be specified in the search criteria in the argument.

     
     The following code snippets explain the usage of this method, 

    Properties p = new Properties (); p.put ("type", "Windows"); p.put ("ipAddress", "192.168.4.*"); Vector v = topoApi.getObjectNamesWithProps (p, false);

    The above code snippet will return the keys of all MOs whose type property is "Windows" and the ipAddress property starts with "192.168.4.".

    Properties p = new Properties (); p.put ("userName", "adventnet"); p.put ("community", "public"); Vector v = topoApi.getObjectNamesWithProps (p, true);

    The above code snippet will return the keys of all MOs whose userName property is "adventnet" or the community property "public".

    Parameters:
    p - (key, value) pairs to match, in a Properties object
    performOR - specify whether to match all the specified criteria or any one of them
    Returns:
    Vector of names matching the Properties specified.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    suppressInfoEvents

    void suppressInfoEvents(boolean suppress)
                            throws java.rmi.RemoteException
    To enable/disable Info events getting generated from the Topology module. Currently, Info Events will be generated from the Topology module whenever a ManagedObject gets added to the database. For large number of MOs, this will result in as many number of additional events in the Event database plus the processing time for each event. If the generation of these Info events are not needed, it can be disabled at runtime using this method.

    By default, the generation of the Info events will be controlled by the SUPPRESS_INFO_EVENTS parameter of the DBServer process in the NMSProcessesBE.conf file.

    If suppress is true, then the generation of the Info events will be suppressed thereafter and vice versa.

    Parameters:
    suppress - Whether the generation of Info events is to be suppressed or not (true to suppress Info events, false to generate).
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.

    registerNotificationFilter

    boolean registerNotificationFilter(TopoNotificationFilter notfilter)
                                       throws java.rmi.RemoteException
    To register for notifications from TopoNotificationRegistry, about changes in the topology database. The TopoNotificationRegsitry can be used to filter the com.adventnet.nms.topodb.TopoObserver notifications, by specifying various criteria.

    Parameters:
    notfilter - Instnace of TopoNotificationFilter which specifies the criteria to filter the TopoObserver notifications, and invokes the the corresponding implementation of TopoNotificationHandler to handle the notifications.
    Returns:
    true if registration is successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    TopoNotificationFilter, TopoNotificationHandler, TopoNotificationRegistryIfc, unregisterNotificationFilter(TopoNotificationFilter)

    unregisterNotificationFilter

    boolean unregisterNotificationFilter(TopoNotificationFilter notfilter)
                                         throws java.rmi.RemoteException
    To unregister the previously registered TopoNotificationFilter from the TopoNotificationRegistry.

    Parameters:
    notfilter - The instnace of TopoNotificationFilter which was previously registered.
    Returns:
    true if unregistration is successful, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    See Also:
    TopoNotificationFilter, TopoNotificationHandler, TopoNotificationRegistryIfc, registerNotificationFilter(TopoNotificationFilter)

    isManagedObjectPresent

    boolean isManagedObjectPresent(java.lang.String objKey)
                                   throws java.rmi.RemoteException,
                                          NmsStorageException,
                                          UserTransactionException
    To check if an object with the given key exists in the database.

    Parameters:
    objKey - key of the ManagedObject whose existence in the database needs to be checked.
    Returns:
    true if the object with the given key exists in the database, false otherwise.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getMOClassHierarchy

    java.lang.String[] getMOClassHierarchy(java.lang.String objKey)
                                           throws java.rmi.RemoteException,
                                                  NmsStorageException,
                                                  UserTransactionException
    Get the class hierarchy for the ManagedObject with the given key. This method would return the fully qualified class names of the ManagedObject with the given key and all it's super classes.

    The class names will be returned in a String array in the reverse hierarchical order (i.e.) the class name of the ManagedObject with the given key will be at the first position and the base class will be at the last position in the array.

    For example, for a ManagedObject which is an instance of SnmpNode the following will be returned :

     
     com.adventnet.nms.topodb.SnmpNode;
     com.adventnet.nms.topodb.Node;
     com.adventnet.nms.topodb.TopoObject;
     com.adventnet.nms.topodb.ManagedObject;
      

    Parameters:
    objKey - The key of the ManagedObject for which the class hierarchy is to be returned.
    Returns:
    A String array containing the fully qualified class names of the ManagedObject with the given key and all it's super classes, in the reverse hierarchical order. If the object with the given name does not exist in the database a 'null' will be returned.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    getMOHierarchyForClass

    java.lang.String[] getMOHierarchyForClass(java.lang.String classname)
                                              throws java.rmi.RemoteException,
                                                     java.lang.ClassNotFoundException
    This method is used to get the classnames in the Hierarchy for the given classname of Managed Object. It returns the fully qualified classnames of the super classes. The class names will be returned in a String array in the reverse hierarchical order (i.e.) the given class name will be at the first position and the base class will be at the last position in the array.

    For example, for a ManagedObject which is an instance of SnmpNode the following will be returned :

     
     com.adventnet.nms.topodb.SnmpNode;
     com.adventnet.nms.topodb.Node;
     com.adventnet.nms.topodb.TopoObject;
     com.adventnet.nms.topodb.ManagedObject;
      

    Parameters:
    classname - The fully qualified classname or the short name of a Managed Object's classname.
    Returns:
    A String array containing the fully qualified class names of the ManagedObject with the className and all it's super classes, in the reverse hierarchical order. If there are no classes with the given classname, a 'null' will be returned.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    java.lang.ClassNotFoundException - if the classname passed in the argument is not a valid one.
    Since:
    WebNMS2.3 Service-Pack1 to get the classnames in the hierarchy for the given className of Managed Object.
    See Also:
    getMOClassHierarchy(String)

    getLockedObjectKeys

    java.lang.String[] getLockedObjectKeys()
                                           throws java.rmi.RemoteException
    To get the keys of all the Managed objects which are locked at that instance of time. When the ownername is 'null', it returns the names of the Managed Objects. It returns all the locked objects, irrespective of whether they are locked internally in NMS or in any user application.

    Returns:
    a String array of keys of the Managed Objects which are locked.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    Since:
    WebNMS2.3 Service-Pack1 to get the list of locked objects.
    See Also:
    checkOut(String,int)

    deleteObjects

    void deleteObjects(java.lang.String classname,
                       java.util.Properties criteria)
                       throws java.rmi.RemoteException,
                              NmsStorageException,
                              UserTransactionException
    The deleteObjects method is used to delete a selected group of objects based on a criteria. The objects matching the properties given in the argument of the method will be deleted along with their traces as cascade deletion. This method takes care of deleting all the children recursively till the last level of contaiment relationship, if any of the object to be deleted is a container. The objects will be selected for deletion only if it matches all the properties given in the argument.

    Please note that this API supports cascade deletion (deleting all children recursively) only for container objects and this does not handle the objects which are not following the parent/child relationship. Note that this does not delete the members of a group if a group object happen to be deleted by this method. However if any member object is a container, all its children will be deleted till the last level of containment hierarchy.

    The first argument classname can be make use for better performance. This means, if all the matching objects belong to a same class, the classname can be passed to this method which will improve the performance a bit as this need not search the tables to perform the delete operation. From the classname itself this method will get the related table names and proceed with deletion. For example, if all the objects which are deleted are belong to same class say test.Port which extends ManagedObject, the classname can be passed as test.Port which perform the deletion only Port and ManagedObject tables and other relevant tables. This will avoid searching the related tables by its own.

    The classname argument cannot be used if the matching objects are belong to different classes. In this case, the classname should be passed as null.

    The applications which are registered as TopoBulkListener with the topology module, would be notified about this delete operation by invoking TopoBulkListener.deleteObject(XMLNode) method .On successful return from all the listeners, this method will delete all the selected objects and their traces if any, from the database as well as from memory cache. Note that this method does not check for locks made over the objects which are happen to be deleted by this method. If any of the object which is already locked and happen to be deleted by this method, the lock made for the object will be cleared.

    For example, for deleting all group objects belonging to a network, the following code snippet can be used:

    
     Properties prop = new Properties();
     prop.put("isGroup","true");
     prop.put("parentNet","192.168.1.0");
     String className = "com.adventnet.nms.topodb.Node";
     api.deleteObjects(className, prop);  // api is the TopoAPI handle.
     
    The above code deletes all group objects of the network "192.168.1.0".

    If the underlying database supports transaction, and if the transaction support is enabled, then this method ensures atomicity of the delete operation. If the deletion operation fails at any point, the changes made to the database tables from the start of the operation are all undone and the operation is abandoned i.e if 10 objects are selected for deletion from the given criteria, 5 objects are deleted and the deletion of the 6th object fails, then the operation is rolled back for the 5 deleted objects.

    Please note that the deletion of objects performed by this method would not be intimated to the TopoObservers.

    Parameters

    Parameters:
    classname - Either fully qualified classname or the short name of the Managed Object's classname.
    criteria - The properties based on which the objects will be deleted.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    deleteObject(ManagedObject,boolean,boolean), deleteObjectAndSubElements(String)

    addObjects

    void addObjects(java.lang.String classname,
                    java.util.Vector managedObjects)
                    throws java.rmi.RemoteException,
                           NmsStorageException,
                           UserTransactionException
    Adds a Vector of ManagedObjects to the database. The ManagedObjects, identified uniquely by it's key, will be added to the database only if it is not previously present in the database.

    The classname (either fully qualified or the short name) can be given if all the objects to be added belongs to the same class. If the classname is null, it is assumed that the Managed Objects to be added to the DataBase belongs to different classes.

    If the underlying database supports transaction, and if the transaction support is enabled, then this method ensures atomicity of the add operation across all the tables. If the insertion of the object, fails at any point, the changes made to the database tables from the start of the operation are all undone and the operation is abandoned i.e if 10 objects are given to be added to the DataBase, 5 objects are added and the insertion of the 6th object fails, then the operation is rolled back for the 5 inserted objects.

    The applications that have registered themselves as TopoBulkListeners using addTopoBulkListener(TopoBulkListener) would be notified about this bulk add operation by a call to their TopoBulkListener.addObjects(Vector) method. This method notifies the TopoBulkListeners only after the insertion is comitted to the DataBase.

    If the Objects to be added implements ContainerInterface then this API would set the isContainer value to true before the objects gets added to the database.

    If the given ManagedObject is an instance of Network object, then this method would not start the discovery process for the corresponding network.If the Network object being added happens to be a subnet of some other Network, which is already present in the database, then this method doesnot updates the parentNetwork and the parentNetMask properties of the passed Network object and the subNets and the subNetMasks properties of the other corresponding Network object, respectively.

    If the given ManagedObject is an instance of Node object, then this method would not add a Network object corresponding to the parent network of the Node, if one such is not already present in the database.

    Note that the Vector of ManagedObjects are not passed through all the discovery filters and seed file constraints that are specified.It has no option considering the seed.file entries for the Network or Node insertion into the Database.

    Please Note that addition of ManagedObjects will not be notified to the TopoObservers Also this method does not generate Events for the ManagedObjects added to the database and also it does not create MapSymbols for the objects added.

    Parameters:
    classname - Either fully qualified classname or the short name of the Managed Object's classname.
    managedObjects - The vector of Managed Objects to be added to the DataBase.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    addObject(ManagedObject)

    deleteObjectAndSubElements

    void deleteObjectAndSubElements(java.lang.String objKey,
                                    int level)
                                    throws java.rmi.RemoteException,
                                           NmsStorageException,
                                           UserTransactionException
    This method can be used to delete a container object and its children objects recursively, till the last level of containment hierarchy. The level passed as argument will take no effect.

    In topology, the parent/child relationship can be formed as a hierarchy of objects which can spread in number of levels to represent the network elements. This method is designed to handle the deletion of a parent object to take care of deleting all its child objects by traversing into as many levels as the parent object has the child objects.

    This deletion is performed with efficient sql statements with the necessary notifications to the listeners.

    Note : As of WebNMS 5, The argument, level is dummy. Whatever is passed as level, this method will delete the object for given key, its level 1 children, children of objects in level 1, its children,... till the last level objects will be deleted. This works similar to passing -1 in implementation prior to WebNMS 5.

    To receive notifications of delete operation performed by this method, applications should be registered as TopoBulkListener with the topology module. Please refer addTopoBulkListener(TopoBulkListener) for more details.

    On successful return from all the listeners, this method will delete the container object and its children from the database and also from the memory cache. Note that this method does not check for locks made over the objects which are happen to be deleted. If the objects which are locked and happen to be deleted by this method, the lock made over the objects will be cleared.

    If the underlying database supports transaction, and if the transaction support is enabled, then this method ensures proper rollback. That is, if the delete operation fails at any point, all the previous changes made to the database will be undone.

    Please note that deletion of objects using this method would not be intimated to the TopoObservers. Also note that this API works only if the underlying database supports subquery. NOTE: This API doesn't handle the objects which are not following the parent/child relationship. Please note that the deletion of a group object will not delete its members.

    Parameters:
    objKey - The key of the Object to be deleted.
    level - The number of levels passed here take no effect.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out. deleted is not a container object
    See Also:
    deleteObjects(String classname,Properties criteria,int level)

    deleteObjects

    void deleteObjects(java.lang.String classname,
                       java.util.Properties criteria,
                       int level)
                       throws java.rmi.RemoteException,
                              NmsStorageException,
                              UserTransactionException
    Deprecated. Deprecated as of WebNMS 5. Use deleteObjects(String, Properties).

    This method is used to delete objects based on some specific criteria including the deletion of the traces if any. ie., This method takes care of deleting all the children recursively if some/all of the matching objects are container objects. The level passed will take no effect and children till the last level of containment relationship will be deleted.

    Please note that this API supports cascade deletion (deleting all children recursively) only for container objects and this does not handle the objects which are not following the parent/child relationship. Note that this does not delete the members of a group if a group object happen to be deleted by this method. However if any member object is a container, all its children will be deleted till the last level.

    The first argument classname can be make use for better performance. This means, if all the matching objects are belong to a same class, the classname can be passed to this method which will improve the performance a bit as this need not search the tables to perform the delete operation. From ths classname itself this method will get the related table names and proceed with deletion. For example, if all the objects which are deleted are belong to same class say test.Port which extends ManagedObject, the classname can be passed as test.Port which perform the deletion only Port and ManagedObject tables and other relevant tables. This will avoid searching the related tables by its own.

    The classname argument cannot be used if the matching objects are belong to different classes. In this case, the classname should be passed as null. While perform cascade deletion, the classes of the objects may differ in different levels. If this is the case, the classname field should be passed as null. As of WebNMS 5, the level passed as argument to this method does not take any effect.

    For example, to delete all the container objects with cascade delete (deleting all the children recursively), the following code snippet can be used:

    
       Properties prop = new Properties();
       prop.put("isContainer","true");
       TopoAPI.deleteObjects(className, prop,-1);
     
    

    The applications which are registered as TopoBulkListener with the topology module, would be notified about this delete operation by invoking TopoBulkListener.deleteObject(XMLNode) method. On successful return from all the listeners, this method will delete all the selected objects and their traces if any, from the database as well as from memory cache. Note that this method does not check for locks made over the objects which are happen to be deleted by this method. If any of the object which is already locked and happen to be deleted by this method, the lock made for the object will be cleared.

    If the underlying database supports transaction, and if the transaction support is enabled, then this method ensures proper rollback. That is, if the delete operation fails at any point, all the previous changes made to the database will be undone.

    Please note that the deletion of objects performed by this method would not be intimated to the TopoObservers. Also note that this API works only if the underlying database supports subquery.

    Parameters:
    classname - Either fully qualified classname or the short name of the Managed Object's classname .
    criteria - The criteria properties for the objects to be deleted
    level - The level does not take any effect and children till the last level are deleted.
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    deleteObjectAndSubElements(String objKey,int level), deleteObjects(String classname, Properties criteria)

    getTopoModuleParams

    java.util.Properties getTopoModuleParams()
                                             throws java.rmi.RemoteException
    returns the Topo Module parameters and their values in java.util.Properties object. int, boolean values are also converted as String objects and stored in java.util.Properties object.

    The below tabular column lists the possible keys and their respective values in the returned Properties object

    Topo Module Parameters Possible Values
    TOPO_OBJECTS_IN_MEMORY int >= 0
    LOCK_CLASS Lock Class name
    LOCK_TIMEOUT int >= -1
    MANAGE_OTHER_NETWORKS true,false
    SUPPRESS_INFO_EVENTS true,false
    ENABLE_SP_FOR_IFC_PARENTS true,false
    DISCOVER_OTHER_NETWORKS true,false
    DISCOVER_BC_RESP_IPS true,false
    STOP_BC_FOR_NETWORKS true,false
    STATUS_PROPAGATION true,false
    STATUS_POLL_DHCP_CHECK true,false
    USER_DISCOVERY_ONLY true,false
    DISCOVERY_REQUESTS_PER_INTERVAL int > 0

    Returns:
    java.util.Properties object containing Topo Module Parameters and values.
    Throws:
    java.rmi.RemoteException - if request fails in remote machine

    addNetwork

    int addNetwork(java.lang.String network,
                   java.lang.String netmask,
                   boolean overRideSeed)
                   throws java.rmi.RemoteException,
                          NmsStorageException,
                          UserTransactionException
    Adds a network object of given IP address and netmask to the topology database and starts off its discovery. The network object is first passed through all the discovery filters, which might prevent it from getting added to the database. This method internally makes use of the addObject(ManagedObject) method to add the network object to the database.

    If the network object is successfully added to the database, then this method also adds a TO_DISCOVER net entry for the network in the discovery engine configuration file (seed.file).

    Parameters:
    network - The IPAddress of the network to be added.
    netmask - The netmask for the network.
    overRideSeed - Whether the seed file configuration is to be overridden or not, while adding the Network object.
    Returns:
    Integer specifying the result of the operation:

    1 Operation successful.

    2 Network already available.

    3 Invalid NetworkID or Netmask.

    4 Rejected by seed.file configuration.

    5 Network Unmanged.

    6 Network Discovery Disabled.

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    addObject(ManagedObject)

    discoverNetwork

    int discoverNetwork(java.lang.String network,
                        java.lang.String netmask,
                        boolean overRideUnmanaged,
                        boolean overRideDiscoveryDisabled)
                        throws java.rmi.RemoteException,
                               NmsStorageException,
                               UserTransactionException
    Triggers discovery for a network which is already present in the database.Inorder to manage and trigger discovery for a unmanaged network, the argument "overRideUnmanaged" should be set to true.This parameter also sets the "discover" property for the network to true.Inorder to trigger discovery for a network which is managed but discover-disabled, the parameter "overRideDiscoveryDisabled" should be set to true.

    Parameters:
    network - The IPAddress of the network to be added.
    netmask - The netmask for the network
    overRideUnmanaged - Whether the network object is to be discovered even if it is unmanaged.If set to true,the network will be managed and discovery will be triggered, even if its previously unmanaged.If set to false,the "managed" property of the corresponding network object in the database will be checked and if set to true, discovery for the network will be triggered.
    overRideDiscoveryDisabled - Whether the network object is to be discovered even if it is discovery disabled.If set to true,the network's discovery will be triggered.If set to false,the "discover" property of the corresponding network object in the database will be checked and if set to true, discovery for the network will be triggered.
    Returns:
    1 if the operation was successful.

    2Network not available in the database.

    3 Invalid NetworkID or Netmask.

    4 Network discovery is in progress.

    Network Unmanged.

    6 Network Discovery Disabled.

    7 Error while checkout

    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back by the method or because of time out.
    See Also:
    addObject(ManagedObject)

    getObjectPropsWithProps

    java.util.Vector getObjectPropsWithProps(java.lang.String classname,
                                             java.lang.String[] fetchProperties,
                                             java.util.Properties criteria,
                                             boolean returnAsProps,
                                             boolean performOr)
                                             throws java.rmi.RemoteException,
                                                    NmsStorageException,
                                                    UserTransactionException
    Gets a Vector containing selective properties of objects matching the given criteria. The criteria can be a list of properties taken from properties of ManagedObject or its derived objects. The objects will be selected if they match with any or all the properties given in the match criteria, ie., it uses the both AND or OR operator while querying the tables with the match criteria to obtain the required result. The user properties cannot be used in the match criteria or in the required properties. The classname signifies, the tables that must be considered for the selection of objects. Not all the properties of the match objects are returned. The required properties passed in the fetchProperties array will be retured as Properties object of key and value. The vector will have Properties for every match object of requested Properties alone. This will be enable shallow fetch of objects properties based on criteria.

    For example, to fetch few properties say name,status and sysDescr of all the SNMP Nodes from the Topology Database, the following code snippet can be used.

     Properties criteria = new Properties();
     criteria.put("isSNMP","true");
     String fetchProperties = {"name","status","sysDescr"};
     Vector MOVector  =  topoAPI.getObjectPropsWithProps("SnmpNode",fetchProperties,criteria,true,false);
     
    Now the MOVector will Properties object for all objects match the criteria. The Properties will have 3 elements for status, name and sysDescr for all the snmp nodes. This will be fetched from the tables which are associated with the MO hierarchy of SnmpNode. ie., it will fetch data from the tables ManagedObject, TopoObject, Node, and SnmpNode.

    This method returns only those objects whose classname property is the one passed to this method. If the given classname is incorrect, i.e., any of the property name given in the match criteria is not found in the properties of MO associated with the given classname, then this method will return null. For example, in the above example, if the classname passed as "ManagedObject" instead of "SnmpNode", then this method would return null. Because the match criteria "isSNMP" is not found in the properties of "ManagedObject". Similar to criteria, if the fetchProperties is not found in the properties of given class, then null value will be returned. Note : The fetchProperties will return properties stored in database. The other properties like 'childrenKeys','NodeList','InterfaceList','groupNames','groupMembers' etc cannot be obtained using this method.

    Parameters:
    classname - the classname for the objects that are selected.
    fetchProperties - the properties that needs to be fetched.
    match - the criteria based on which the objects to be selected from the database.
    returnAsProps - if true, returns a Vector of Properties objects else List of properties in order specified in fetchProperties
    performOr - if true, does a OR operation on the properties in criteria Properties else AND of the criteria.
    Returns:
    a Vector of Properties object with selected properties of objects matching the given criteria. Returns 'null' when the classname is null or no matching objects found in the database
    Throws:
    java.rmi.RemoteException - if a problem occurs when accessing through RMI.
    NmsStorageException - that may occur if any SQL error occurs while performing database operations.
    UserTransactionException - that may occur if the current transaction is rolled back because of time out.

    "WEBNMS_5 API Docs"

    Copyright © 2013 ZOHO Corp., All Rights Reserved.