Solstice Enterprise Manager 4.1 Developing Java Applications Doc Set ContentsPreviousNextIndex

Chapter 3

Using the Java Alarm API

The Java Alarm API defines the classes and methods which allow you to create applications that perform alarm management operations. This chapter covers the most important aspects of using the API and provides detailed examples. For more information about the API, refer to Java API Reference.

The following topics are covered in this chapter:

These topics are arranged, as far as possible, to reflect the order you need to follow when creating alarm management applications. For example, before getting alarms, you must have associated an AlarmLog object with a log, created a query, and specified the attributes to be returned. This sequence becomes clear as you go through this chapter.

3.1 Overview

Alarms are events indicating abnormal conditions that the MIS logs (through the logging subsystem) into alarm logs (the default log object is AlarmLog). Each log entry (record) represents an alarm and is created based on the mapping provided in evv2oclist object in the MIS and the filter created for the log. An alarm:

When the MIS receives an event, it uses a predefined filter to determine whether the event is an alarm and logs it accordingly as an alarm record. You can use the Alarms window to view and monitor alarms.

The Java Alarm API provides a programmatic interface to achieve functionality similar to the Alarms window. The Java Alarm API hides the implementation details of how logs stored in databases are accessed and processed, and provides the classes and methods that allow you to create alarm management applications. If the implementation details change, your application still works. See the following figure.


FIGURE 3-1   The Java Alarm API

Note – The Java Alarm API works only on alarms that are derived from the GDMO object emAlarmRecord and does not work with user-defined alarms.

3.1.1 Alarm Management Tasks

The Java Alarm API allows you to perform the following alarm management tasks:

These tasks can be performed using the following main classes of the Java Alarm API:

See the following figure.


FIGURE 3-2   Main "Players" in the Java Alarm API

Each instance of the AlarmLog class represents an alarm log and contains methods for accessing and modifying alarm information. The query classes provide the filtering mechanism needed by some of the AlarmLog class methods. The listener classes provide the mechanism for reacting to alarms.

3.1.2 Alarm Management Task Flow

When creating alarm management applications, keep in mind the following model of task flow, as illustrated in the following figure.


FIGURE 3-3   Flow of Tasks When Handling an Event

3.2 Instantiating the AlarmLog Class

The first step to take when performing alarm operations is to instantiate the AlarmLog class. This class represents the MIS's log objects that contain alarms. Each instance of this class represents one log. See the following figure.


FIGURE 3-4   AlarmLog Objects
 

To Instantiate the AlarmLog Class

1. Create a LogName object as shown in the following example:

LogName logName = new LogName(MISName, "AlarmLog");

The logName object allows you to hide the naming internals of the log. When creating the logName object, you must supply the following two arguments:

2. Create an AlarmLog object as shown in the following example:

AlarmLog log = new AlarmLog(platform, logName);

The AlarmLog object constructor takes the following parameters:

3.3 Creating Query Objects

The Java Alarm API allows you to create filter objects that you can use to query alarm logs. For example, you can create queries to retrieve all alarm records that have a perceived severity that is major or critical.

 

To Create a Query Object

1. Create one or more FilterItem objects that define the conditions to check for in the query.

This topic is described in Section 3.3.1 Creating FilterItem Objects.

2. Create a Filter object that combines the FilterItem objects you defined in Step1 based on a logical criteria (AND or OR).

This topic is described in Section 3.3.2 Creating Filter Objects.

3. Create a GenericQuery object that combines the Filter objects you defined in Step2 based on a logical criteria (AND or OR). See the following figure.

This topic is described in Section 3.3.3 Creating GenericQuery Objects.

FIGURE 3-5   Query Objects

As shown in FIGURE 3-5, the GenericQuery object is used to join various Filter objects and the Filter object is used to join various FilterItem objects. Constructing a GenericQuery object in this fashion hides the implementation details of filtering, allows FilterItem and Filter objects to be reused in the same application to create different queries, and allows you to create complicated queries.

3.3.1 Creating FilterItem Objects

A FilterItem object represents a condition in a query that affects only one alarm record attribute. For example, you might want to retrieve all alarm records whose PERCEIVED_SEVERITY attribute is equal to EMSeverity.MAJOR or EMSeverity.CRITICAL.

To create a FilterItem object, you need to provide the following three parameters:

Following is an example of a code segment that creates a FilterItem object:

EMSeverity[] sev = {

                EMSeverity.MAJOR,

                EMSeverity.CRITICAL

            };

FilterItem filterItem1 = 

new FilterItem(AlarmRecordAttribute.PERCEIVED_SEVERITY, 
RelationCriteria.EQUAL, sev);

This code creates a FilterItem object based on the severity of the alarm record.

The first statement in the code above defines the attribute values that will be used when creating the FilterItem object filterItem1.

The second statement creates the FilterItem object filterItem1. All alarm records whose perceived severity is major or critical will pass this filter.

3.3.2 Creating Filter Objects

A Filter object implements an alarm filter. You construct a filter by combining an instance of the LogicalCriteria object with a list of FilterItem objects. In other words, an alarm filter consists of one or more conditions combined together by the logical operators AND or OR.

To create a Filter object, you need to provide the following two parameters:

Following is a code segment that creates a Filter object:

LogicalCriteria logCriteria1 = new LogicalCriteria OR;

Filter filter = new Filter(logCriteria1, filterItem1);

In this code segment, the first statement defines OR as the logical operator to be used when creating the filter.

The second statement creates the Filter object filter based on the logical operator defined in the previous statement and the FilterItem object defined in Section 3.3.1 Creating FilterItem Objects.

To add more FilterItem objects to the filter object, you can use the addFilter method as follows:

filter.addFilterItem(filterItem2);

filter.addFilterItem(filterItem3);

In this case, the filter object consists of three conditions combined by the OR operator (filterItem1 OR filterItem2 OR filterItem3).

3.3.3 Creating GenericQuery Objects

A GenericQuery object implements a generic alarm filter. You construct a GenericQuery object by combining a LogicalCriteria object with FilterItem objects.

To create a GenericQuery object, you need to provide the following two parameters:

Following is a code segment that creates a GenericQuery object:

GenericQuery query = new GenericQuery();

query.addFilter(filter1);

query.addFilter(filter2);

In this code segment, the first statement creates a new GenericQuery object (query). The second and third statements add two Filter objects to the query. These two filters are combined using the AND operator.

3.4 Creating AlarmRecordAttributeSet Objects

Each record in an alarm log consists of 22 fields or attributes. However, in many instances you only need to retrieve or modify a subset of these attributes, which you can specify using the AlarmRecordAttributeSet objects. These objects are used by the API methods that retrieve or modify alarm record attributes.

The following table contains a list of the 22 alarm record attributes that are represented as variables in the AlarmRecordAttribute class:

TABLE 3-1   AlarmRecord Attributes 
Attribute Description
ACK_OPERATOR
 User ID of the operator who acknowledged the alarm
ACK_STATE
 Specifies whether the alarm is acknowledged
ACK_TEXT
 Text added when the alarm was acknowledged
ACK_TIME
 Time when the alarm was acknowledged
CLEAR_OPERATOR
 User ID of the operator who cleared the alarm
CLEAR_STATE
 Specifies whether the alarm is cleared
CLEAR_TEXT
 Text added when the alarm was cleared
CLEAR_TIME
 Time when the alarm was cleared
DISPLAY_OPERATOR
 User ID of the operator who made a change to the display state flag
DISPLAY_STATE
 A flag that can be used by applications to determine whether to display an alarm
DISPLAY_TEXT
 Text added when the alarm display flag is changed
DISPLAY_TIME
 Time when the alarm display state was changed
EVENT_TIME
 Time when the event occurred
EVENT_TYPE
 Type of event
LOGGING_TIME
 Time when the event got logged
LOG_RECORD_ID
 ID of the log record created
MANAGED_OBJECT_INSTANCE
 Actual object that raised this alarm
PERCEIVED_SEVERITY
 Severity of the alarm
PROBABLE_CAUSE
 Probable cause of the alarm
ADDITIONAL_TEXT
 Additional information about the alarm
LOG_NAME
 Name of the log in which this alarm is logged
MIS_NAME
 MIS name on which this log exists


To define a set of alarm record attributes, create an AlarmRecordAttributeSet object and add the required attributes (using the add method) as shown in the following code example:

CODE EXAMPLE 3-1   Defining Alarm Record Attributes
AlarmRecordAttributeSet attrSet = new AlarmRecordAttributeSet();

attrSet.add(AlarmRecordAttribute.LOG_RECORD_ID);

attrSet.add(AlarmRecordAttribute.PERCEIVED_SEVERITY);

attrSet.add(AlarmRecordAttribute.PROBABLE_CAUSE);

attrSet.add(AlarmRecordAttribute.CLEAR_STATE);

attrSet.add(AlarmRecordAttribute.CLEAR_TIME);

attrSet.add(AlarmRecordAttribute.CLEAR_TEXT);

attrSet.add(AlarmRecordAttribute.CLEAR_OPERATOR);

attrSet.add(AlarmRecordAttribute.ACK_STATE);

attrSet.add(AlarmRecordAttribute.ACK_TIME);

attrSet.add(AlarmRecordAttribute.ACK_TEXT);

attrSet.add(AlarmRecordAttribute.LOGGING_TIME);

attrSet.add(AlarmRecordAttribute.EVENT_TYPE);

attrSet.add(AlarmRecordAttribute.MANAGED_OBJECT_INSTANCE);

attrSet.add(AlarmRecordAttribute.LOG_NAME);

attrSet.add(AlarmRecordAttribute.ADDITIONAL_TEXT);

attrSet.add(AlarmRecordAttribute.DISPLAY_OPERATOR);

attrSet.add(AlarmRecordAttribute.DISPLAY_STATE);

attrSet.add(AlarmRecordAttribute.DISPLAY_TIME);

attrSet.add(AlarmRecordAttribute.EVENT_TIME);

3.5 Getting Alarms

Once the AlarmLog and query objects are created, you can perform alarm management operations. This section describes how to get:

3.5.1 Getting Alarm Counts

To get the number of alarms in an alarm log that satisfy a particular query, use the getAlarms method of the AlarmLog class as shown in the following code segment:

count = log.getAlarmCount(query);

This code segment gets the alarm count based on query. If query is null, the getAlarmCount method returns the total number of alarms in the alarm log.

3.5.2 Getting Alarms

To retrieve the attributes of alarms that satisfy a particular query, use the getAlarms method of the AlarmLog object as shown in the following code segment:

AlarmRecord[] alarms = log.getAlarms(query, attrSet);

This code segment retrieves the alarm records that satisfy the query and stores them into the alarms array. The returned attributes contain the attributes specified by attrSet only.

3.5.3 Getting Alarms in Batches

It is often more efficient to retrieve alarm information in batches. This method frees the system to perform other operations while alarm information is being gathered.

To retrieve alarms in batches, you need to define a BatchListener object and pass it as an argument to the getAlarmsInBatches method. This method takes the following parameters:

The following code example shows how to get alarms in batches.

CODE EXAMPLE 3-2   Getting Alarms in Batches
BatchListener batchList = new BatchListener("Critical");

System.out.println("Getting critical alarms in batches");

int batchId = log.getAlarmsInBatches(query, 5000, batchList, attrSet);

System.out.println("Batch Id: " + batchId);

..........

..........

..........

class BatchListener implements AlarmsBatchListener {

	 String id = null;

	 public BatchListener(String id) {

	 	 	  this.id = id;

	 }

	 public void batchReceived(int callId, AlarmRecord[] record) {

	 	 	  System.out.println("BatchId: " + callId);

	 	 	  System.out.println( "Number of alarms received: " + record.length);


  

  

     

	 }


  

  

     

	 public void batchDone(int callId) {


  

  

     

 	  	 	 System.out.println("BatchId :" + callId);


  

  

     

	 	 	 System.out.println("Batch complete");


  

  

     

	 }


  

  

     

}


  













   Notice that this code segment also contains the 
implementation of the batchReceived and batchDone methods of the BatchListener class. These methods 
specify what to do when a batch is received and when batching 
is done.






   3.6	 Clearing and 
Acknowledging Alarms






   Clearing and acknowledging alarms is a routine 
task that you perform when managing alarms. The AlarmLog class provides the setClearAlarms and setAckAlarms methods that you can use to 
clear and acknowledge alarms. The following code example 
shows how to acknowledge and clear alarms.


 CODE EXAMPLE 3-3 	
  Clearing and Acknowledging 
Alarms 


  
  

     

  ................


  

  

     

  AlarmRecord[] alarms = log.getAlarms(q1, attrSet);


  

  

     

  ...............


  

  

     

  AlarmRecordId alrmId =alarms[0].getLogRecordId();


  

  

     

  AlarmRecordId[] alrm = {alrmId};


  

  

     

  log.setAckAlarms(alrm, "meaningful text needed");


  

  

     

  log.setClearAlarms(alrm, "meaningful text needed");


  

  

     

  ............ 


  













   In this code segment, the setAckAlarms and setClearAlarms methods acknowledge and 
clear the alarm whose log id is specified by the alarms array (in this case the array 
contains only one id) by modifying the ACK_TEXT and CLEAR_TEXT attributes, respectively, of 
the corresponding alarm record in the corresponding 
log.






   You can also clear alarms by sending an event 
using the sendClearAlarmsEvent method. This method 
sends an event that clears all alarms that originated from 
the same source all at once without having to clear them 
one-by-one, as in the setClearAlarms method. 



  
  

     

log.sendClearAlarmsEvent(alrm);


  














   3.7	 Listening for Alarm 
Log Events






   One of the main tasks in alarm management is to 
define how your application reacts to alarm records being 
created, deleted, or modified. This task is done by creating 
listener objects that define how to react to such events. 
These objects will be notified of such events by the logging 
subsystem. 






   The Java Alarm API provides the following four 
interfaces for creating alarm event listener objects:








 

To Create an Alarm Event Listener





 	1.	 Use the setEventAttrSet method to specify the list 
of attributes to be returned.



 	2.	 Use the addAlarmLogListener method to register to 
receive an event when the alarm log is created, deleted, or 
modified, as shown in the following example.



  
  

     

//Listen for objectCreationEvent

 

//------------------------------

 

log.setEventAttrSet(attrSet);

 

System.out.println("Listening for alarm events");

 

log.addAlarmLogListener(new EventListener());


  













   Note – If attributes other than the 
one specified in attrSet changes, 
an empty event is generated.





 	3.	 Fill the bodies of the AlarmLogListener methods with the 
appropriate code (see CODE EXAMPLE 3-5). 






   3.8	 Sample 
Programs






   This section provides sample programs that 
perform alarm management.






   3.8.1	 AlarmBatch






   This program gets alarms in batches. The query is 
based on perceivedSeverity, and 
the batchSize is 5000. See the following code 
example.


 CODE EXAMPLE 3-4 	  AlarmBatch 


  
  

     

/*


  

  

     

 * Copyright 10/30/98 Sun Microsystems, Inc. All Rights Reserved.


  

  

     

 */


  

  

     

/*


  

  

     


  

  

     

  AlarmBatch <servername> <mis-name> <username> <password>


  

  

     

  <servername> - is the machine name on which the server is running.


  

  

     

  <mis-name> - is the machine name on which the mis is running.


  

  

     

  <username> - is the user login name.


  

  

     

  <password> - is the password of the user login.


  

  

     


  

  

     

*/


  

  

     

import com.sun.em.api.alarm.*;


  

  

     

import com.sun.em.api.common.*;


  

  

     

import java.util.Enumeration;


  

  

     

import java.util.Vector;


  

  

     

import com.sun.em.api.pmi.*;


  

  

     


  

  

     

public class AlarmBatch {


  

  

     


  

  

     

  static void usage() {


  

  

     

    System.err.println("Usage:");


  

  

     

    System.err.println("AlarmBatch  <servername> 
<mis-name> 
<username> <password > ");


  

  

     

    System.exit(-1);


  

  

     

  }


  

  

     


  

  

     

  public static void main(String[] args) {


  

  

     

    try {


  

  

     

      new AlarmBatch(args);


  

  

     

    }


  

  

     

    catch (Exception e) {


  

  

     

      e.printStackTrace();


  

  

     

    }


  

  

     


  

  

     

    System.out.println("Done.");


  

  

     

    System.exit(0);


  

  

     


  

  

     

  }


  

  

     


  

  

     

  public AlarmBatch(String[] args)


  

  

     

    throws AlarmException {


  

  

     


  

  

     

      if (args.length < 4)


  

  

     

        usage();


  

  

     


  

  

     

      //Create an attribute set: The set of alarm record attributes 


  

  

     

      //in which you are interested.


  

  

     

      
//--------------------------------------------------------------


  

  

     

      AlarmRecordAttributeSet attrSet = new AlarmRecordAttributeSet();


  

  

     

      attrSet.add(AlarmRecordAttribute.LOG_RECORD_ID);


  

  

     

      attrSet.add(AlarmRecordAttribute.PERCEIVED_SEVERITY);


  

  

     

      attrSet.add(AlarmRecordAttribute.PROBABLE_CAUSE);


  

  

     

      attrSet.add(AlarmRecordAttribute.CLEAR_STATE);


  

  

     

      attrSet.add(AlarmRecordAttribute.CLEAR_TIME);


  

  

     

      attrSet.add(AlarmRecordAttribute.ACK_TIME);


  

  

     

      attrSet.add(AlarmRecordAttribute.LOGGING_TIME);


  

  

     

      attrSet.add(AlarmRecordAttribute.EVENT_TYPE);


  

  

     

      attrSet.add(AlarmRecordAttribute.ACK_STATE);


  

  

     

      attrSet.add(AlarmRecordAttribute.MANAGED_OBJECT_INSTANCE);


  

  

     

      attrSet.add(AlarmRecordAttribute.ACK_OPERATOR);


  

  

     

      attrSet.add(AlarmRecordAttribute.ACK_TEXT);


  

  

     

      attrSet.add(AlarmRecordAttribute.CLEAR_OPERATOR);


  

  

     

      attrSet.add(AlarmRecordAttribute.CLEAR_TEXT);


  

  

     

      attrSet.add(AlarmRecordAttribute.ADDITIONAL_TEXT);


  

  

     

      attrSet.add(AlarmRecordAttribute.DISPLAY_OPERATOR);


  

  

     

      attrSet.add(AlarmRecordAttribute.DISPLAY_STATE);


  

  

     

      attrSet.add(AlarmRecordAttribute.DISPLAY_TIME);


  

  

     

      attrSet.add(AlarmRecordAttribute.EVENT_TIME);


  

  

     


  

  

     

      try {


  

  

     

        System.out.println("Connecting to " + args[1] + "...");


  

  

     


  

  

     

        //Create a Platform object based on the arguments passed


  

  

     

        
//-------------------------------------------------------


  

  

     

        Platform platform = new Platform(args[0],args[1] , args[2],args[3]);


  

  

     

        System.out.println("Platform instantiation complete ");


  

  

     


  

  

     

        //Instantiate a AlarmLog Object for a log named "AlarmLog"


  

  

     

        
//--------------------------------------------------------


  

  

     

        System.out.println("AlarmLog instantiation");


  

  

     

        LogName logName = new LogName(args[1], "AlarmLog");


  

  

     

        AlarmLog log = new AlarmLog(platform, logName);


  

  

     


  

  

     

        //Create a query


  

  

     

        //---------------


  

  

     


  

  

     

        //Create array of perceived severity values to be used to  


  

  

     

        //create a filter item


  

  

     

        EMSeverity[] sev = {


  

  

     

          EMSeverity.CRITICAL


  

  

     

        };


  

  

     


  

  

     

        // Create a FilterItem based on  perceivedSeverity


  

  

     

        FilterItem filterItem1 = new FilterItem(AlarmRecordAttribute.PERCEIVED_SEVERITY,


  

  

     

        RelationCriteria.EQUAL, sev); 


  

  

     

                                                


  

  

     

        Filter filter = new Filter(filterItem1);


  

  

     

        GenericQuery query = new GenericQuery(filter);


  

  

     


  

  

     

        //Test batch mechanism


  

  

     

        //--------------------


  

  

     


  

  

     

        // Create a listener object instance to handle to batch events


  

  

     

        BatchListener batchList = new BatchListener("Critical");


  

  

     

        System.out.println("Getting critical alarms in batches");


  

  

     

        //Get alarms in batches of 5000 each


  

  

     

        int batchId = log.getAlarmsInBatches(query, 5000, batchList, attrSet);


  

  

     

        System.out.println("Batch Id: " + batchId);


  

  

     


  

  

     

        //Stop batch


  

  

     

        //----------


  

  

     

        System.out.println("Stopping the batch");


  

  

     

        log.stopGetAlarmsInBatches(batchId);


  

  

     


  

  

     

      }


  

  

     

      catch(Exception e1) {


  

  

     

        e1.printStackTrace();


  

  

     

      }


  

  

     

  }


  

  

     


  

  

     

}


  

  

     


  

  

     

// Implements a listener object to handle batch events


  

  

     

//-----------------------------------------------------


  

  

     

class BatchListener implements AlarmsBatchListener {


  

  

     


  

  

     

  String id = null;


  

  

     

  public BatchListener(String id) {


  

  

     

    this.id = id;


  

  

     

  }


  

  

     


  

  

     

  // When a batch is received the following method is called


  

  

     

  public void batchReceived(int callId, AlarmRecord[] record) {


  

  

     

    System.out.println("BatchId: " + callId);


  

  

     

    System.out.println( "Number of alarms received: " + record.length);


  

  

     


  

  

     

  }


  

  

     


  

  

     

  // When all batches have been received the following method is called


  

  

     

  public void batchDone(int callId) {


  

  

     

    System.out.println("BatchId :" + callId);


  

  

     

    System.out.println("Batch complete");


  

  

     


  

  

     

  }


  

  

     

  private static final String sccsID = "@(#)AlarmBatch.java     1.5 98/10/30 Sun Microsystems";


  

  

     


  

  

     

}


  













   3.8.2	 AlarmEvent






   The following code example:






   3.8.3	 AlarmClear






   The following code example:






   3.8.4	 AlarmDelete






   The following code example:






   3.8.5	 AlarmQuery






   The following code example:




 





   

















Sun Microsystems, Inc.

Copyright information. All rights 
reserved.






Doc Set  |  
Contents
  |  
Previous
  |  
Next
  |  
Index