com.adventnet.management.policydb
Interface NmsPolicyAPI

All Superinterfaces:

CommonAPI, CommonModuleAPI, java.rmi.Remote

public interface NmsPolicyAPI
extends CommonAPI

The AdventNet Web NMS Policy Module provides support for network based management with an extensible framework for scalable administration of the Web NMS server and the network elements managed by Web NMS. The primary goal of the engine is to enable administration of complex functions easily. In the context of network management, policies are specifications for network management systems or network elements directly, which can be used by administrators to control a range of network activities. In the context of Web NMS, policies are used to customize the behaviour of the NMS and to provide a framework for adding policies for different network elements.

For example, Web NMS provides the following policies. 

      1.  Deleting all failed nodes from the management system, if down for more than a specified time. 
      2.  Escalating alarms of a specific severity, if in the same state for more than a specified time. 
      3.  Changing the tester class at runtime to get more details about the object, apart from status. 

NmsPolicyAPI defines the methods for accessing PolicyObject in PolicyModule.

        Some of the important methods available  are :
   addPolicy(PolicyObject po) - For adding a new PolicyObject
   updatePolicy(String policyname,Properties prop) - For updating existing PolicyObject
   executePolicy(PolicyEvent policyEvt) - For executing PolicyObjects
   stopPolicy(String policyname) - For stopping the execution of a PolicyObject
   deletePolicy(String name) - For deleting a PolicyObject
   register(PolicyObserver observer) - For registering as a PolicyObserver thereby getting notification
   
   NmsPolicyAPI handle can be obtained from one of the following ways. 
   

   On the same JVM with Web NMS it can be obtained using,
   
   NmsPolicyAPI api = (NmsPolicyAPI)NmsUtil.getAPI("NmsPolicyAPI");
   
   This API is also available as a Remote Object. Use the following statement for getting a remote handle 
   (assuming rmihost as localhost and port as 1099) to NmsPolicyAPI
   
   NmsPolicyAPI api = (NmsPolicyAPI)Naming.lookup("rmi://localhost:1099/NmsPolicyAPI");
   
   In case of RMI secure mode handle can be obtained using
   
   RMIAccessAPI rmiApi = (RMIAccessAPI) Naming.lookup ("rmi://localhost:1099/RMIAccessAPI");
   NmsPolicyAPI api = (NmsPolicyAPI)rmiApi.getAPI ("username", "password","NmsPolicyAPI");
    

Field Summary

static int	AND_CONDITION Deprecated.
static int	DEFAULT_PERIOD variable to represent periodicity for PeriodicPolicyObject.
static int	OR_CONDITION Deprecated.
static int	POLICY_ADDED Variable to represent Policy addition
static int	POLICY_DELETED Variable for PolicyObject Deletion
static int	POLICY_DISABLED variable to represent the status of the PolicyObject as disabled.
static int	POLICY_ENABLED variable to represent the status of the PolicyObject as enabled.
static int	POLICY_EXECUTED Variable to represent PolicyObject execution
static int	POLICY_SCHEDULED Variable to represent scheduling of PolicyObject
static int	POLICY_STOPPED Variable to represent stopping of a PolicyObject
static int	POLICY_UPDATED Variable to represent PolicyObject modification

Method Summary

boolean	addAction(java.lang.String policyname, PolicyAction pa) Deprecated. We strongly recommend you to use addPolicyActionAndCondition(String policyname , PolicyAction pa , PolicyCondition pc)
boolean	addCondition(java.lang.String policyname, PolicyCondition pc) Deprecated. We strongly recommend you to use addPolicyActionAndCondition(String policyname , PolicyAction pa , PolicyCondition pc)
boolean	addPolicy(PolicyObject po) Adds the policy represented by the PolicyObject to the Policy Module.
boolean	addPolicyActionAndCondition(java.lang.String policyname, PolicyAction pa, PolicyCondition pc) Adds the PolicyAction and PolicyCondition to the PolicyObject whose name corresponds to policyname.
boolean	deletePolicy(java.lang.String name) Deletes the policy represented by name from the system and returns true on successful deletion.
void	executePolicy(PolicyEvent policyEvt) Executes the policy which are all listed in PolicyEvent.
PolicyObject	getPolicy(java.lang.String name) Returns the PolicyObject whose name correspondsc to name.
PolicyObject	getPolicy(java.lang.String name, boolean newInstance) Deprecated. as of WebNMS2.2
java.util.Hashtable	getPolicyConfParameters() Method to get all parameters available in conf/policy.conf
java.util.Vector	getPolicyNames() Returns the name of all the PolicyObjects that exist in PolicyModule.
boolean	isInitialized() Returns status of the policy module.
boolean	register(PolicyObserver observer) Registers the PolicyObserver to the Policy module returns true if successful.
void	removeAllObservers() Remove all PolicyObservers registered to the Policy module
boolean	removeObserver(PolicyObserver observer) Removes the PolicyObserver registered to the Policy module.
void	setPolicyStatus(java.lang.String policyname, int status) Sets the status of the PolicyObject whose name corresponds to policyname to status.
boolean	stopPolicy(java.lang.String policyname) Stops the execution of PolicyObject for the given policyname.
boolean	updatePolicy(java.lang.String policyname, java.util.Properties prop) updates the PolicyObject whose name corresponds to policyname with the Properties prop.

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

getCompleteList, getObjectNamesWithProps, getPropertiesOfObject

Field Detail

POLICY_ENABLED

static final int POLICY_ENABLED

variable to represent the status of the PolicyObject as enabled.

NOTE

Only Enabled PolicyObjects can be executed.

See Also:

Constant Field Values

POLICY_DISABLED

static final int POLICY_DISABLED

variable to represent the status of the PolicyObject as disabled.

NOTE

Disabled PolicyObjects cannot be executed.

See Also:

Constant Field Values

AND_CONDITION

static final int AND_CONDITION

Deprecated.

variable to represent conditionType (i.e all the conditions must be satisfied) of the PolicyObject. To specify in case of multiple conditions how their cumulative should be evaluated.

NOTE

This is the default value of the conditionType of the PolicyObject

See Also:

Constant Field Values

DEFAULT_PERIOD

static final int DEFAULT_PERIOD

variable to represent periodicity for PeriodicPolicyObject. specifies the time interval ( in seconds ) between the 2 schedules of the PolicyObject.

NOTE

The default value is 10 seconds.

See Also:

Constant Field Values

OR_CONDITION

static final int OR_CONDITION

Deprecated.

variable to represent the conditionType (i.e any one of the conditions must be satisfied) of the PolicyObject. To specify in case of multiple conditions how their cumulative should be evaluated.

NOTE

This is not the default value for the conditionType of the PolicyObject.

See Also:

Constant Field Values

POLICY_ADDED

static final int POLICY_ADDED

Variable to represent Policy addition

See Also:

Constant Field Values

POLICY_UPDATED

static final int POLICY_UPDATED

Variable to represent PolicyObject modification

See Also:

Constant Field Values

POLICY_DELETED

static final int POLICY_DELETED

Variable for PolicyObject Deletion

See Also:

Constant Field Values

POLICY_EXECUTED

static final int POLICY_EXECUTED

Variable to represent PolicyObject execution

See Also:

Constant Field Values

POLICY_STOPPED

static final int POLICY_STOPPED

Variable to represent stopping of a PolicyObject

See Also:

Constant Field Values

POLICY_SCHEDULED

static final int POLICY_SCHEDULED

Variable to represent scheduling of PolicyObject

See Also:

Constant Field Values

Method Detail

addPolicy

boolean addPolicy(PolicyObject po)
                  throws java.rmi.RemoteException,
                         NmsStorageException,
                         UserTransactionException

Adds the policy represented by the PolicyObject to the Policy Module. Returns true on successful addition Otherwise, return false. Name is the unique identifier for PolicyObject

Parameters:

po - the PolicyObject to be added

Returns:

boolean to represent success or failure

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

deletePolicy

boolean deletePolicy(java.lang.String name)
                     throws java.rmi.RemoteException,
                            NmsStorageException,
                            UserTransactionException

Deletes the policy represented by name from the system and returns true on successful deletion. Otherwise, returns false.

Parameters:

name - Name of the PolicyObject to be deleted

Returns:

boolean to represent result of delete operation

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

getPolicy

PolicyObject getPolicy(java.lang.String name,
                       boolean newInstance)
                       throws java.rmi.RemoteException,
                              NmsStorageException,
                              UserTransactionException

Deprecated. as of WebNMS2.2

Returns the PolicyObject whose name corresponds to name. A new instance will be returned if the boolean createNewInstance is true.

NOTE

Creating new instance of policy depending on boolean passed is no longer exists. Functionality of this method is same as the method getPolicy(String policyName)

Parameters:

name - name of the PolicyObject to be retrieved

createNewInstance - boolean to determine whether to create new instance or not

Returns:

PolicyObject

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

getPolicy

PolicyObject getPolicy(java.lang.String name)
                       throws java.rmi.RemoteException,
                              NmsStorageException,
                              UserTransactionException

Returns the PolicyObject whose name correspondsc to name. Returns null if no policy exist with the specified name.

Parameters:

name - name of the PolicyObject to be retrieved

Returns:

PolicyObject corresponding to the given name

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

getPolicyNames

java.util.Vector getPolicyNames()
                                throws java.rmi.RemoteException,
                                       NmsStorageException,
                                       UserTransactionException

Returns the name of all the PolicyObjects that exist in PolicyModule.

Returns:

Vector containing the names of all the PolicyObjects

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

addAction

boolean addAction(java.lang.String policyname,
                  PolicyAction pa)
                  throws java.rmi.RemoteException

Deprecated. We strongly recommend you to use addPolicyActionAndCondition(String policyname , PolicyAction pa , PolicyCondition pc)

Adds the PolicyAction pa to the PolicyObject whose name corresponds to policyname.

Parameters:

policyname - name of the PolicyObject

pa - the PolicyAction to be added

Returns:

ture on success. Otherwise, false

Throws:

java.rmi.RemoteException - if export fails

addCondition

boolean addCondition(java.lang.String policyname,
                     PolicyCondition pc)
                     throws java.rmi.RemoteException

Deprecated. We strongly recommend you to use addPolicyActionAndCondition(String policyname , PolicyAction pa , PolicyCondition pc)

Adds the PolicyCondition pc to the PolicyObject whose name corresponds to policyname.

Parameters:

policyname - name of the PolicyObject

pc - the PolicyCondition to be added

Returns:

true on success. Otherwise, false

Throws:

java.rmi.RemoteException - if export fails

addPolicyActionAndCondition

boolean addPolicyActionAndCondition(java.lang.String policyname,
                                    PolicyAction pa,
                                    PolicyCondition pc)
                                    throws java.rmi.RemoteException

Adds the PolicyAction and PolicyCondition to the PolicyObject whose name corresponds to policyname. While adding PolicyAction and Conditon through this method key for PolicyAction and PolicyCondition should match each other. Otherwise PolicyAction and PolicyCondition won't get added and false will be returned

Parameters:

policyname - name of the PolicyObject to which Action and Condition are to be added

pa - PolicyAction to be added

pc - the PolicyCondition to be added

Returns:

true on success. false Otherwise

Throws:

java.rmi.RemoteException - if export fails

Since:

WebNMS 2.3

executePolicy

void executePolicy(PolicyEvent policyEvt)
                   throws java.rmi.RemoteException,
                          NmsStorageException,
                          UserTransactionException

Executes the policy which are all listed in PolicyEvent. For the specified policy if no PolicyAction/PolicyCondition is configured then executeAction method of PolicyObject will be called. If one or more PolicyAction/PolicyCondition are specified for the particular PolicyObject then the following approach will be considered. First list of PolicyConditions will be taken, then condition will be checked. Only if isConditionSatified method returns true, corresponding executeAction method of PolicyAction will be called.

     Code snippet for executing a PolicyObject
     First PolicyEvent has to be constructed as 
     PolicyEvent pe = new PolicyEvent(java.lang.Object source);
     where, source specifies the object from which the event is fired.

     Then policies which has to executed are added as 
     pe.addPolicyNamesToTrigger("testpolicy1");
     then added PolicyObject with the name "testpolicy1" can be executed as
     api.executePolicy(pe);

     Even all policies belonging to a group group  can be executed as 

     PolicyEvent pe = new PolicyEvent(this); 
     pe.addPolicyNamesToTrigger("testpolicy1");
     pe.addPolicyGroupsToTrigger("backuppolicygroup") 
     then all PolicyObjects with the groupName "backuppolicygroup" can be executed as
     api.executePolicy(pe);
     

Parameters:

policyEvt - PolicyEvent with list of policies to be executed

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

See Also:

PolicyEvent

setPolicyStatus

void setPolicyStatus(java.lang.String policyname,
                     int status)
                     throws java.rmi.RemoteException,
                            NmsStorageException,
                            UserTransactionException

Sets the status of the PolicyObject whose name corresponds to policyname to status. Status can be any one of NmsPolicyAPI.POLICY_ENABLED or NmsPolicyAPI.POLICY_DISABLED

Parameters:

policyname - name of the PolicyObject

status - the status to be set for the PolicyObject

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

See Also:

POLICY_ENABLED, POLICY_DISABLED

updatePolicy

boolean updatePolicy(java.lang.String policyname,
                     java.util.Properties prop)
                     throws java.rmi.RemoteException,
                            NmsStorageException,
                            UserTransactionException

updates the PolicyObject whose name corresponds to policyname with the Properties prop.

Parameters:

policyname - name of the PolicyObject

prop - the properties

Returns:

boolean true on successful update, false otherwise

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

stopPolicy

boolean stopPolicy(java.lang.String policyname)
                   throws java.rmi.RemoteException,
                          NmsStorageException,
                          UserTransactionException

Stops the execution of PolicyObject for the given policyname. Returns true if the PolicyObject for the given name is already under execution and stopped successfully. Returns false if no Policy exists with the given name or Policy is not already running

Parameters:

policyname - name of the PolicyObject

Returns:

boolean true on successful updation, false otherwise

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

NmsStorageException - if any SQL error occurs while doing database operations

UserTransactionException - if the current transaction is timed out or rolled back.

register

boolean register(PolicyObserver observer)
                 throws java.rmi.RemoteException

Registers the PolicyObserver to the Policy module returns true if successful. Once the Observer is registered successfully , notification will be sent for all add/update/delete/execute/stop events that are happening in module

Parameters:

observer - the PolicyObserver to be registered

Returns:

boolean to represent success or failure

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

isInitialized

boolean isInitialized()
                      throws java.rmi.RemoteException

Returns status of the policy module. Once module initialization is over this method will return true. This is same as return value of isInitialized method of RunProcessInterface corresponding to the Policy module

Returns:

the status of the policy module. True on successful initialization, will return false when initialization is in progress

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

removeObserver

boolean removeObserver(PolicyObserver observer)
                       throws java.rmi.RemoteException

Removes the PolicyObserver registered to the Policy module. Once unregistered, Observer won't be intiamated again

Parameters:

observer - the PolicyObserver to be removed

Returns:

boolean true indicating success , false otherwise.

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

removeAllObservers

void removeAllObservers()
                        throws java.rmi.RemoteException

Remove all PolicyObservers registered to the Policy module

Throws:

java.rmi.RemoteException - if any remote export fails during the execution of a remote method call.

getPolicyConfParameters

java.util.Hashtable getPolicyConfParameters()
                                            throws java.rmi.RemoteException

Method to get all parameters available in conf/policy.conf

Returns:

Hashtable containing all entries present in conf/policy.conf Hashtable will have entries like

 Key                     Data Type 

 classnames                 String array containing all available class names
 displaynames               String array containing all available display names
 policycolor                Properties with the information policy color. It will be 
                           some thing like   Key     ---   Value
                                        DISABLED  = "191-191-191"
                                        STOPPED   =  "255-223-128"
                                        EXECUTED  =  "32-255-255"
                                        SCHEDULED =  "0-255-75"
Throws:
java.rmi.RemoteException - if any remote export fails during the 
                          execution of a remote method call.