The Alert Management API

With releases 6 the capabilities of the Alert Management Service have been increased to provide more control for the user. The service is now divided into three services:

• Alert Administration Service enables monitoring and control of the alerts stored in the event database in Enterprise Manager

• Alert Configuration Service on the GlassFish Server provides more control over the persistence of alerts generated in the event management component.

• Alert Notification Service on the GlassFish Server provides more control over the type of alerts that are delivered to a scripting client from the event management component.

---

Caution - Persistence on and journaling off means that the removal of events are completed upon delivery to all current clients. Persistence on and journaling on means there is no removal of the events. Remember, if the removable policy is enabled, the events will removed.

---

Support for Databases

The Alert Management API supports five databases:

• Derby, which is delivered with the GlassFish Application Server installation

• Oracle

• Sybase

• DB2

• PointBase

AlertConfigurationService

The AlertConfigurationService enables the Enterpriser Manager and other management clients to manage and control the delivery reliability of alerts from applications or JBI based components to their clients. Enterprise Manager always receives alerts when it is started, while all other clients are required to register in order to receive alerts. The configuration to manage includes the enabling and disabling of the persistence of alerts in the database as well as the policy to manage the deletion of alerts.

Persisted Alerts Removal Policy

The composite removal policy is defined by controlling three items:

• Alerts Count

  The maximum number of alerts that can be persisted. When this policy is enforced, the oldest-generated alerts are removed.

• Alerts Age

  The maximum amount of time, that is, “age,” that an alert can be persisted.

• Alerts Level

  Every generated alert has one priority level, from low to high, associated with it:

  • INFO

  • WARNING

  • MINOR

  • MAJOR

  • CRITICAL

  • FATAL

  All the alerts that have a lower priority up to the defined level are removed.

The implementation is based upon a “first come first served” policy, as described in the Alert Configuration Service API. The policy is a combination of all the defined policy items, an “and” condition, and is applied even if the result of the executed policy item nullifies the execution of the next policy item.

By default, persistence is set to “not enabled.” If you change the persistence default to “enabled” but journaling is not “on,” you do not need to set the policy. However, if journaling is set to “on,” you can set the policy for Alerts Count, Alerts Age, and Alerts Level.

Alert Configuration Service API

* Enable alerts persistence in the alerts database.
     * enabling it allow for reliable alerts delivery in
     * case of delivery channel failure or Application 
     * server restart.
     *  
     * @param enableJournaling 
     *                    true - will prevent the system from
     *                           removing alerts after they 
     *                           are delivered. The alert stay 
     *                           in the database until the 
     *                           user removes them.
     *                    false - The system will remove the alert
     *                            upon acknowledgment from 
     *                            the reliable client in case one was
     *                            setup or upon send the alert to 
     *                            all the non reliable client/s.
     * @throws ManagementRemoteException if JMX related exception is 
     *         thrown or the list of target name is null or empty.
     */
     public void enableAlertsPersistence(Boolean enableJournaling) throws 
     *        ManagementRemoteException;
    
     /**
     * Disable alerts persistence in the alerts database.
     * 
     * @throws ManagementRemoteException if JMX related exception is 
     *         thrown or the list of target name is null or empty.
     */
     public void disableAlertsPersistence() throws ManagementRemoteException;
      
     
     /**
     * @return the last setting of alert persistence enabling operation.
     *         true if enable otherwise false.
     * @throws ManagementRemoteException if JMX related exception.
     */
     public  Boolean isAlertsPersistenceEnabled()throws 
     * ManagementRemoteException;
    
    /**
     * @return the last setting of alert journal enabling operation.
     *         true if enable otherwise false.
     * @throws ManagementRemoteException if JMX related exception.
     */
    public Boolean isAlertsJournalEnabled()throws ManagementRemoteException;
     
    /**
     * set the JNDI name of the data source database to be used 
     * for persistence. if not provided at least once the persistence 
     * will be disabled even if enableAlertsPersistence was set to true.
     * 
     * @param jndiName - of the data source to be used in conjunction with 
     *   enableAlertsPersistence set to true
    
     * @throws ManagementRemoteException if JMX related exception is 
     *         thrown orjndiName parameter is null or empty.  
     */
    public void setPersistenceDataSourceJndiName(String jndiName) throws 
    * ManagementRemoteException;
    /**
    
     * @return the last set JNDI name for the alert persistence data source.
     * @throws ManagementRemoteException
     */
    public String  getPersistenceDataSourceJndiName() throws ManagementRemoteException;
    
    /**
     * set the database type to be used for persistence.
     * Derby is the assumed default database. If different database is 
     * used this method should be called prior to enabling the persistence.
     * 
    
     * @param dbtype - one of the predefined typed defined in {@link 
     *             com.sun.caps.management.api.alerts.AlertPersistenceDBType}
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public void setPersistenceDataBaseType(AlertPersistenceDBType dbtype) throws 
     *             ManagementRemoteException;
    
    /**
     * @return The return value represent the last set DB type 
     *             {@link com.sun.caps.management.api.alerts.AlertPersistenceDBType}
     *             for each.
     * @throws ManagementRemoteException if JMX related exception is thrown.     */
    public AlertPersistenceDBType  getPersistenceDataBaseType() throws 
    ManagementRemoteException;
    
    /**
     * Set the maximum time a persisted alert will be stored in the alert database 
     * before it will be deleted as part of the removal policy 
     * @param timeToLive - maximum time in millisecond.
     * 
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public void setPersistedAlertsMaxAge(Long timeToLive) throws 
    ManagementRemoteException;
   
    /**
     * return the last setting for the allowed persisted alert age.
     * A value of 0 current time which could cause all persisted alerts to be deleted.
     * A negative value this policy element is ignored.   
     * @return  the returned value  representing as time in milliseconds set for each.
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public Long getPersistedAlertsMaxAge() throws ManagementRemoteException;
   
    /**
     * set the maximum number of  alerts allowed to be persisted  before it will be 
     * deleted as part of the removal policy
     * @param size - Maximum number of alerts.
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public void setPersistedAlertsMaxCount(Long size) throws ManagementRemoteException;
    
    /**
     * return the last setting for the  maximum of  alerts allowed to be persisted.
     * A value of 0 mean no alerts persisted. It behave as if the user 
     *  set enableAlertsPersistence to false
     *   
     * A negative value this policy element is ignored.
     * @return the returned value represent the maximum number of alerts allowed to be 
     *         persisted on each target.
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public Long getPersistedAlertsMaxCount() throws ManagementRemoteException;
    
    /**
     *  The priority based alert level that will be part of the removal policy.
     *  the priorities are as follows (from low to high):
     *  INFO,WARNING,MINOR,MAJOR,CRITICAL,FATAL.
     *  all alerts from the provided level and below will be candidates for removal.
     *  
     * @param level - an AlertLevelType representing the level.
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public void setPersistedAlertsLevel(AlertLevelType level) throws 
    ManagementRemoteException;
    /**
     * @return  the returned value represent the last setting for the level of alerts 
     *          that allowed to be removed from persistence for each target.
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public AlertLevelType getPersistedAlertsLevel() throws ManagementRemoteException;
   
   
    /**
     * set the effective policy for the removal of persisted alerts.
     * @param policyList - an array of AlertRemovalPolicyType where the priority
     *                     of the given policy is defined by its position in the list.
     *                     i.e the lower the index that policy will be applied first.
     *                     possible values are:
     *                     ALERTS_AGE,ALERTS_COUNT,ALERTS_LEVEL.
     *                     
     *                     null value or empty array indicate no policy will be 
     *                     enforced.
    
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public void setPersistedAlertsRemovelPolicy(AlertRemovalPolicyType[] policyList) 
    *          throws ManagementRemoteException;
    
    /**
     * @return the return value representing an array the last setting the policy used 
     *         when persisted alerts are to be removed. An empty array mean no policy 
     *         is enforced.
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public String[] getPersistedAlertsRemovalPolicy() throws ManagementRemoteException;
   
    
    /**
     * enable or disable the ability to use removal policy.
     * @param enableExecuation -  true the current setting is enforced. False the 
     *           current policy is ignored.
    
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public void enablePersistedAlertsPolicyExecution(Boolean enableExecution) throws
    *            ManagementRemoteException;
    
    /**
     * @return the returned value represent the last setting that enable/disable the 
     *         removal policy
     * @throws ManagementRemoteException
     */
    public Boolean isPersistedAlertsPolicyExecutionEnabled()throws 
    *          ManagementRemoteException;
    
    /**
     * set how often the persisted alerts removal policy will be executed.
     * @param excutionInterval - The interval is defined in milliseconds.  
    
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public void setPersistedAlertsRemovelPolicyExecInterval(Long excutionInterval)
    *          throws ManagementRemoteException;
    
    /**
     * @return the returned value representing The last interval setting of 
     *         the persisted alerts removal policy will be executed.
     * @throws ManagementRemoteException if JMX related exception is thrown.
     */
    public Long getPersistedAlertsRemovelPolicyExecInterval() throws 
     *         ManagementRemoteException;
    
    /**
     * Set the persisted alerts table name.
     * Note: if the same database is used across the whole enterprise. it
     *       must be unique for each domain used.  
     * @param tableName - the table name to be used for the stored alerts
     * @throws ManagementRemoteException
     */
    public void setAlertTableName(String tableName) throws ManagementRemoteException;
    
    
    /**
     * @return The current assign persisted alerts table name.
     * @throws ManagementRemoteException
     */
    public String getAlertTableName() throws ManagementRemoteException;
    /**
     * 
     * @return return the total number of alerts currently persisted. This value 
     * is volatile and may V between two sequential calls to this method.
     * @throws ManagementRemoteException
     */
    public  Integer getPersistedAlertsCount() throws ManagementRemoteException;
   
    /**
     * the API allows the caller to set all the parameters defined in the other API in
     * this interface. All the setting are applied prior to enabling the persistence.
     * @param enableJournaling
     *                    true - will prevent the system from removing alerts after 
     *                           they are delivered. The alert stay in the database 
     *                           until the user remove them.
     *                    false - The system will remove the alert upon acknowledgment 
     *                            from the reliable client in case one was setup or 
     *                            upon send the alert to all the non reliable client/s.
     * @param jndiName - JNDI name of the data source database to be used for 
     * persistence.
     * @param dbtype - one of the predefined typed defined in 
     *                    {@link com.sun.caps.management.api.alerts.
     *                     AlertPersistenceDBType}
     * @param timeToLive -  maximum time in millisecond.
     * @param maxCount - Maximum number of alerts.
     * @param level -  an AlertLevelType representing the level.
     * @param policyList - an array of AlertRemovalPolicyType where the priority
     *                     of the given policy is defined by its position in the list.
     *                     i.e the lower the index that policy will be applied first.
     *                     possible values are:
     *                     ALERTS_AGE,ALERTS_COUNT,ALERTS_LEVEL.
     * @param enablePolicyExecution - true the current setting is enforced. False the 
     *         current policy is ignored.
     * @param interval The interval the policy will be executed (is defined in 
     *         milliseconds). 
     * @param inMemoryCacheSize - The interval is defined in milliseconds. 
    
     * @throws ManagementRemoteException if JMX related exception is thrown or 
     *         the list of target names is null or empty.
     */
     public void enableAlertsPersistence(Boolean enableJournaling,String jndiName,
                                         AlertPersistenceDBType dbtype,Long timeToLive,
                                         Long maxCount,AlertLevelType level,
                                         AlertRemovalPolicyType[] policyList,
                                         Boolean enablePolicyExecution,Long interval,
                                         Integer inMemoryCacheSize) throws 
     *                                   ManagementRemoteException;

AlertNotificationService

The Alert Notification Service notifies the client, such as Groovy, of an event. However, for the client to receive notifications it must subscribe using the Alert Notification Service API. There is a noticeable change between prior releases and Release 6 regarding reliable and non-reliable clients. With Release 5.1.x, the client was reliable, meaning that no events could be removed until their delivery was confirmed. With Release 6, a client can be non-reliable, which means there is no guarantee the client will receive every event. In Release 6, the last client set as “reliable” makes all clients before it unreliable.

Alerts Notification Service API

/**
     * request to the event management system to get an events that satisfy the
     * filter provided. The method will validate the call-back object for the 
     * call-back method name and parameter (see below for more information).
     * This method allow the caller to register multiple time with diffrent
     * filtering,target and call-back parameters.
     * 
     * @param filter - the filter that will be applied to the events prior to 
     *                 forwarding them to this client. the valid keys for the map
     *                 are defined in  {@link com.sun.caps.management.api.alerts.
     *                 AlertNotificationFilterElementType}.
     *                 For the ALERTSEVERITY type the valid value are define in
     *                 {@link com.sun.caps.management.api.alerts.AlertLevelType#}.
     *                 
     * @param targetNames - the server instances that is subscription will initially be
     *                      filtered on. if targetNames is/are defined it/they have 
     *                      precedence over the servername element in the filter 
     *                      mentioned above.
     *                  
     * @param CallbackObject an instance of the client object that contain the 
     *                       call back method to be called when event received 
     *                       from the server.
     * @param methodName the method name to be invoke when event received from the 
     *                       server.
     *       IMPORTANT: THE METHOD MUST HAVE ONE PARAMETER OF TYPE 
     *                      {@link com.sun.caps.management.api.alerts.Alert"} ALERT.
     * 
     * @param requireReliableDelivery - true mean this client request that all events 
     *                       should be delivered to him reliably otherwise the client 
     *                       may miss event.
     *       IMPORTANT: THE SYSTEM ALLOW ONLY ONE RELIABLE CLIENT. THE  LAST CLIENT
     *                       TO SET IT TO TRUE TAKES OVER THE RELIABLE DELIVERY. IT 
     *                       WILL AFFECT ALL THE SUBSCRIPTIONS DONE BY THE CLIENT IN 
     *                       THE CURRENT APPLICATION SESSION.
     *                  
     * @param exceptionCallBack an instance of the client object that contain the call 
     *                       back method to be called when an connectivity exception 
     *                       is generated by this service.
     * 
     * @param exceptionMethodName the method name to be invoke when an exception is 
     *                       generated by this service.
     *       IMPORTANT: THE METHOD MUST HAVE ONE PARAMETER OF TYPE 
     *                       {@link java.lang.Exception} EXCEPTION. 
     *       
     *       NOTE: the exception call be should be the same for all subscriptions 
     *                       calls otherwise the last the exception call back 
     *                       defined by the last subscription will be used.
     *     
     * @return Unique identification string that need to be used in the un-subscribe 
     *                       operation.
     *                             
     * @throws ManagementRemoteException 
     *         1. if fail to communicate with the event management system 
     *         2. unable to invoke call back method because of invalid parameter.
     */
    public String subscribe(Map filter,String[] targetName,Object CallbackObject,String
     *          methodName, Boolean requireReliableDelivery,Object exceptionCallBack,
                String exceptionMethodName) throws ManagementRemoteException;
    
    /**
     * request the event management system to stop forwarding events to this client 
     * based on the subscription the caller made using the subscribe method.
     * once all the caller unsubscribe all the IDs any events that are waiting 
     * to be delivered to this client will be discarded.
     * 
     * @param - subscriptionIDs A list of IDs return by the subscribe call/s  that the
     *          caller wish to unsubscribe from.
     *                 
     * @throws ManagementRemoteException if fail to communicate with the Domain server.
     */
    public void unsubscribe(String[] subscriptionIDs) throws ManagementRemoteException;
    
    /**
     * utility method that returns the parameters the client used to subscribe for 
     * alerts for the given subscription ID.
     * 
     * @param - subscriptionIDs list return by the subscribe call/s.
     *          
     * return a map keyed IDs on the provided as a parameter and values as 
     *        SubcriptionInformationinstances.
     *        @see com.sun.caps.management.api.alerts.SubcriptionInformation 
     * @throws ManagementRemoteException if fail to communicate with the Domain server.
     */
    public Map getSubscriptionInformation(String[] subscriptionIDs);