com.tivoli.twg.monitor.api
Class TWGMonAPI

java.lang.Object
  extended bycom.tivoli.twg.monitor.api.TWGMonAPI

public class TWGMonAPI
extends java.lang.Object

This is an object to encapsulate interfacing to the monitor server this method provides a programming API that can be used in other JVM's to contact and communicate with the monitor server.

This class is instantiated by the class that wishes to use the monitor API. This class will handle establishing a session with the Resource Monitor JVM.

The waitForServerReady or isServerReady methods can be used to check if the server is ready for an instantiated TWGMonAPI object to use it.

Once the object is instantiated, the getAttribute and freeAttribute methods may be used to gain access to an attribute on a system. With the object returned from getAttribute, monitoring may be started and stopped and data points checked.

The getDataRC call may be used to check the return code associated with the last received data point. The isThresholdActive method may be used to check whether an unresolved threshold event is present for an attribute the toString method may be used to get a formated copy of the data returned for an attribute.

The following is a sample of the code needed to set up and use the API object:

 public static void main(String argv[])
 {
    TWGMonAPI   api = null;
    long        moid;
  
    // Enable Component tracing for monitors
    TWGRas.initialize();
  
    // set up the service node class with all the information it needs
    ServiceNodeLocalImplFactory snlif = new ServiceNodeLocalImplFactory();
    ServiceNode.SetServiceNodeFactory(snlif);
  
    System.out.println("create and start the API");
    if (TWGRas.isDebugEnabled(TWGRas.MONITORS))
       TWGRas.debug(TWGRas.MONITORS, "TWGMonAPI.main: create and start the API");
    try {
       api = new TWGMonAPI( Locale.ENGLISH, 5000);
    } catch (com.tivoli.twg.monitor.api.TWGMonException e) {
       ;
    } // end try
  
    .
    .
    .
  
    System.out.println("shutdown API");
    if (TWGRas.isDebugEnabled(TWGRas.MONITORS))
       TWGRas.debug(TWGRas.MONITORS, "TWGMonAPI.main: shutdown API");
    api.shutdown();
  
    System.out.println("nulling API");
    if (TWGRas.isDebugEnabled(TWGRas.MONITORS))
       TWGRas.debug(TWGRas.MONITORS, "TWGMonAPI.main: null API");
    api = null;
  
    if (TWGRas.isDebugEnabled(TWGRas.MONITORS))
       TWGRas.debug(TWGRas.MONITORS, "TWGMonAPI.main: exiting");
    System.out.println("exiting");
  
    return;
 }
 

See Also:
TWGMonAttribute

Field Summary
static int RC_FAILURE
          Return code indicating an operation failed.
static int RC_SUCCESS
          Return code indicating an operation succeeded.
protected  ServiceNode sn
          service node for instances of this class to use in this JAVA virtual machine
protected  boolean streamRequests
          indicates that we should send/receive IntelByteBuffer streams
 
Constructor Summary
TWGMonAPI(java.util.Locale locale, long updateMsecs)
           
TWGMonAPI(java.util.Locale locale, long updateMsecs, ServiceNode sn)
          This is the constructor for the API object.
 
Method Summary
 int deleteAttributeAlias(long[] moidList, TWGMonPath aliasPath, boolean tree)
          Method to allow removal of Aliases for monitor attributes
 int deleteThreshold(TWGMonThreshold apiThresh)
          Delete the threshold information from the server
protected  TWGMonRsp extractReplyParm(Command cmd, int outParmIndex, java.lang.Class replyClass)
          method to simplify the grunt work of extracting a monitor server response from a Command object
 void finalize()
          called by the garbage collector to clean up the object.
 TWGMonNodeList findAttributes(TWGMonPath progPath, LongValueSet moids, java.util.Locale locale, long timeout)
          handles the request to the monitor server to get a list of attributes that are monitorable.
 void findAttributesAsync(TWGMonPath progPath, LongValueSet moids, java.util.Locale locale, long timeout, TWGMonNodeListener listener)
          handles the request to the monitor server to get a list of attributes that are monitorable.
 boolean freeAttribute(TWGMonAttribute attribute)
          Handles the request to the Monitor Server to stop monitoring and to release an attribute.
 long[] getAllNativeMOIDs()
          Helper function to retreive all of the Native Director managed object IDs.
 TWGMonThreshold[] getAllThresholds(boolean includeTasks)
          Populate the threshold information with all thresholds.
 TWGMonAttribute getAttribute(TWGMonPath progPath, long moid)
          Handles the request to the Monitor Server to get an attribute and to start monitoring it.
 TWGMonThreshold[] getThresholdInfoForGroup(long moid, TWGMonPath progPath, boolean wantsExactMatch)
          Populate the threshold information for a path associated with a given group.
 TWGMonThreshold[] getThresholdInfoForSystem(long moid, TWGMonPath progPath, boolean wantsExactMatch)
          Populate the threshold information for a path on a given system.
static boolean isServerReady()
          method provided to allow the caller to check if the monitor server has initialized to the point that it is ready to handle requests
protected  Command sendMonCommand(TWGMonCmd moncmd, int cmdCode)
          Adds the monitor command to a command object and sends it to the monitor server.
 int setAttributeAlias(long[] moidList, TWGMonPath aliasPath, TWGMonPath[] aliasPathDisplayStrings, TWGMonPath realPath, boolean tree)
          Method to allow setup of Aliases for monitor attributes
 int setThreshold(TWGMonThreshold apiThresh)
          Send the threshold information to the server
 void shutdown()
          Called to clean up the TWGMonAPI object.
static void waitForServerReady()
          method provided to allow the caller to wait until the monitor server has initialized to the point that it is ready to handle requests
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

RC_SUCCESS

public static final int RC_SUCCESS
Return code indicating an operation succeeded.

See Also:
Constant Field Values

RC_FAILURE

public static final int RC_FAILURE
Return code indicating an operation failed.

See Also:
Constant Field Values

sn

protected ServiceNode sn
service node for instances of this class to use in this JAVA virtual machine


streamRequests

protected boolean streamRequests
indicates that we should send/receive IntelByteBuffer streams

Constructor Detail

TWGMonAPI

public TWGMonAPI(java.util.Locale locale,
                 long updateMsecs,
                 ServiceNode sn)
          throws TWGMonException
This is the constructor for the API object. The thread that instantiates this object will be blocked until the server has a chance to initialize to the point that it is ready to accept requests for work

Parameters:
locale - requested locale of monitor attributes
updateMsecs - milliseconds to sleep between data update requests
Throws:
TWGMonException - indicates that there was a sever error while waiting for the server to initialize. The most likely reason for this exception to be generated by this method is communication problems while trying to check if the server is active.

TWGMonAPI

public TWGMonAPI(java.util.Locale locale,
                 long updateMsecs)
          throws TWGMonException
Method Detail

waitForServerReady

public static void waitForServerReady()
                               throws TWGMonException
method provided to allow the caller to wait until the monitor server has initialized to the point that it is ready to handle requests

Throws:
TWGMonException - indicates that there was a sever error while waiting for the server to initialize. The most likely reason for this exception to be generated by this method is communication problems while trying to check if the server is active.

isServerReady

public static boolean isServerReady()
                             throws TWGMonException
method provided to allow the caller to check if the monitor server has initialized to the point that it is ready to handle requests

Returns:
boolean indicating if the monitor server is active yet
Throws:
TWGMonException - indicates that there was a sever error while waiting for the server to initialize. The most likely reason for this exception to be generated by this method is communication problems while trying to check if the server is active.

shutdown

public void shutdown()
Called to clean up the TWGMonAPI object. This will result in a shutdown of the service node this object has been using to communicate with the monitor server and the polling thread that has been gathering updates of data.


finalize

public void finalize()
              throws java.lang.Throwable
called by the garbage collector to clean up the object. this will result in a shutdown of the service node this object has been using to communicate with the monitor server and the polling thread that has been gathering updates of data

Throws:
java.lang.Throwable - items thrown by base class are passed to caller

findAttributes

public TWGMonNodeList findAttributes(TWGMonPath progPath,
                                     LongValueSet moids,
                                     java.util.Locale locale,
                                     long timeout)
                              throws TWGMonException
handles the request to the monitor server to get a list of attributes that are monitorable. What is returnd is a list of nodes that describe what was found on server. This method blocks until all updates are received.

Parameters:
progPath - programmatic Path to check for nodes on
moids - list of managed objects to check for objects under the path on
locale - locale to return the displayable information for
timeout - maximum time to wait for stuff to come back from the server
Returns:
TWGMonNodeList containing the list of nodes that were gathered for the target path and systems
Throws:
TWGMonException - indicates an error occured in processing the request The most likely cause was invalid parameters

findAttributesAsync

public void findAttributesAsync(TWGMonPath progPath,
                                LongValueSet moids,
                                java.util.Locale locale,
                                long timeout,
                                TWGMonNodeListener listener)
                         throws TWGMonException
handles the request to the monitor server to get a list of attributes that are monitorable. What is returnd is a list of nodes that describe what was found on server.

Parameters:
progPath - programmatic Path to check for nodes on
moids - list of managed objects to check for objects under the path on
locale - locale to return the displayable information for
timeout - maximum time to wait for stuff to come back from the server
listener - object to be notified when the request completes. it will be passed the results that were gathered. The call back to this object can occur before this routine returns.
Throws:
TWGMonException - indicates an error occured in processing the request The most likely cause was invalid parameters

getAttribute

public TWGMonAttribute getAttribute(TWGMonPath progPath,
                                    long moid)
Handles the request to the Monitor Server to get an attribute and to start monitoring it.

Parameters:
progPath - programmatic path to create the attribute on
moid - managed object id to create the attribute on
Returns:
attribute instance, or null if a parameter was incorrect

freeAttribute

public boolean freeAttribute(TWGMonAttribute attribute)
Handles the request to the Monitor Server to stop monitoring and to release an attribute.

Returns:
boolean indicating if the call succeded or not

getThresholdInfoForSystem

public TWGMonThreshold[] getThresholdInfoForSystem(long moid,
                                                   TWGMonPath progPath,
                                                   boolean wantsExactMatch)
Populate the threshold information for a path on a given system. if the progPath that is given is empty (zero levels), and the wants exact match flag is false, all system thresholds for the managed object will be returned.

Parameters:
moid - managed object id of the system to be queried
progPath - programmatic path for the attribute to be checked for thresholds
wantsExactMatch - flag indicates if the user wants an exact match with path passed in
Returns:
TWGMonThreshold[] containing a references to any threshold objects that was found or null if an error occured.

getThresholdInfoForGroup

public TWGMonThreshold[] getThresholdInfoForGroup(long moid,
                                                  TWGMonPath progPath,
                                                  boolean wantsExactMatch)
Populate the threshold information for a path associated with a given group. if the progPath that is given is empty (zero levels), and the wants exact match flag is false, all group thresholds for the managed object will be returned.

Parameters:
moid - managed object id of the group to be queried
progPath - programmatic path for the attribute to be checked for thresholds
wantsExactMatch - flag indicates if the user wants an exact match with path passed in
Returns:
TWGMonThreshold[] containing a references to any threshold objects that was found or null if an error occured.

getAllThresholds

public TWGMonThreshold[] getAllThresholds(boolean includeTasks)
Populate the threshold information with all thresholds.

Parameters:
includeTasks - flag indicates if the user wants an threshold plan tasks included with thresholds
Returns:
TWGMonThreshold[] containing a references to any threshold objects that was found or null if an error occured.

setThreshold

public int setThreshold(TWGMonThreshold apiThresh)
Send the threshold information to the server

Parameters:
apiThresh - Threshold object containing the threshold information to send to the monitor server
Returns:
int containing a TWGMonRC based returned code for the threshold operation

deleteThreshold

public int deleteThreshold(TWGMonThreshold apiThresh)
Delete the threshold information from the server

Returns:
int containing a TWGMonRC based returned code for the threshold operation
See Also:
com.tivoli.twg.monitor.TWGMonRC

setAttributeAlias

public int setAttributeAlias(long[] moidList,
                             TWGMonPath aliasPath,
                             TWGMonPath[] aliasPathDisplayStrings,
                             TWGMonPath realPath,
                             boolean tree)
Method to allow setup of Aliases for monitor attributes

The general idea is that a real path is specified that identifies the programatic path to an attribute or the top of a subtree of attributes that are to have their paths mapped to the alias path. The alias path is used as a substitution for the real path. The AliasPathDisplayStrings are TWGMonPaths that contain the locale specific console strings for the alias path. The English path should always be provided since the product will default to english strings if the information for a requested locale is not available. There should be a path provided for all locales the alias is expected to be viewed in. The tree flag indicates the type of alias being established (subtree vs single attribute)

Example of usage:

 // set up the alias to the path,
 TWGMonPath  aliasPath = new TWGMonPath();
 aliasPath.AddLevel("IBM Sample Shortcut");
  
 TWGMonPath  realPath = new TWGMonPath();
 real.AddLevel("Director Agent");
 real.AddLevel("MONCPU");
  
 TWGMonPath[] aliasPathDisplayStrings = new TWGMonPath[2];
  
 TWGMonPath englishPathStrings = newTWGMonPath();
 englishPathStrings.addLevel("CPU Shortcut");
 englishPathStrings.setLocale(Locale.ENGLISH);
 aliasPathDisplayStrings[0] = englishPathStrings;
  
 TWGMonPath frenchPathStrings = newTWGMonPath();
 frenchPathStrings.addLevel("Le CPU Shortcut");
 frenchPathStrings.setLocale(Locale.FRENCH);
 aliasPathDisplayStrings[1] = frenchPathStrings;
  
 // monAPIobject is an instance of the monitor Api object
 // this line will set the alias against all currently known Native
 // managed objects as a TREE based allias
 monAPIobject.setAttributeAlias(monAPIobject.getAllNativeMOIDs(),
                                aliasPath,
                                aliasPathDisplayStrings,
                                realPath,
                                true );
 

Parameters:
moidList - array of managed object ids to set the alias against
aliasPath - programmatic path to define as the alias path
aliasPathDisplayStrings - Locale Specific Displayable path information for the alias path
realPath - actual programmatic path to map the alias path to
tree - flag indicating if this is mapping one attribute or an attribute subtree. if true, it is mapping a subtree
Returns:
int TWGMonRC return code indicating success or failure of the request. TWGMonAPI.RC_FAILURE is returned for parameter errors, all other return codes are based of the TWGMonRC result.
Since:
Director 2.11
See Also:
com.tivoli.twg.monitor.TWGMonRC

deleteAttributeAlias

public int deleteAttributeAlias(long[] moidList,
                                TWGMonPath aliasPath,
                                boolean tree)
Method to allow removal of Aliases for monitor attributes

The parameters include the list of managed objects to remove the alias from, the alias path that is no longer valid and whether the alias path to remove was a subtree or individual attribute alias.

Example of usage:

  
 // set up the alias to the path
 TWGMonPath  aliasPath = new TWGMonPath();
 aliasPath.AddLevel("IBM Sample Shortcut");
  
 // monAPIobject is an instance of the monitor Api object
 // this line will remove the alias against all currently known Native
 // managed objects (this example makes the assumption that the list of
 // objects remained the same from the time the alias was set).
 monAPIobject.deleteAttributeAlias(monAPIobject.getAllNativeMOIDs(),
                                   aliasPath,
                                   true );
 

Parameters:
aliasPath - programmatic path to define as the alias path
tree - flag indicating if this is mapping one attribute or an attribute subtree. if true, it is mapping a subtree
Returns:
int TWGMonRC return code indicating success or failure of the request
Since:
Director 2.11
See Also:
com.tivoli.twg.monitor.TWGMonRC

getAllNativeMOIDs

public long[] getAllNativeMOIDs()
Helper function to retreive all of the Native Director managed object IDs.

Returns:
long[] array of navtive moids or null

sendMonCommand

protected Command sendMonCommand(TWGMonCmd moncmd,
                                 int cmdCode)
                          throws TWGMonException
Adds the monitor command to a command object and sends it to the monitor server. it handles all the smarts reguarding whether to byte stream or java serialize the request.

Parameters:
moncmd - the TWGMonCmd class derived object that is to be sent to the server
cmdCode - the command code to marke the Command object with
Returns:
Command object containing the command and its response from the server
Throws:
TWGMonException

extractReplyParm

protected TWGMonRsp extractReplyParm(Command cmd,
                                     int outParmIndex,
                                     java.lang.Class replyClass)
method to simplify the grunt work of extracting a monitor server response from a Command object

Parameters:
cmd - command object containing the response object
outParmIndex - index of the output paramter to retrieve from the command object
replyClass - class object that identifies the class type of the response that is expected