16 Creating EDR Listeners

This chapter describes how to create an external event data record (EDR) listener in Oracle Communications Services Gatekeeper.

Understanding External EDR Listeners

External EDR listeners are Java Message Service (JMS) topic subscribers.

The diagram below illustrates three different ways of listening for EDRs as a JMS listener.

Figure 16-1 Flow for external EDR, alarm, and CDR listeners

Description of Figure 16-1 follows
Description of ''Figure 16-1 Flow for external EDR, alarm, and CDR listeners''

EDRs are published externally using a JMS topic. This makes it possible to implement language-independent listeners anywhere on the network in a standard way. It is possible to implement an EDR listener in several ways:

  • Alternative 1: Using a pure JMS listener. Implement the javax.jms.MessageListener interface. It is up to the implementation class to implement any filtering mechanism needed.

  • Alternative 2: Using a subclass of JMSListener with no filter specified. In that case, the JMSListener class will use a tag, if available in the EDR, to filter the EDR into a specific category: EDR, alarm or CDR.

  • Alternative 3: Using a subclass of JMSListener with a specified filter. This filter is used to perform the filtering. If a default filter is used to perform the same filtering as Services Gatekeeper, all classes used in the xml configuration files must be present in the current class loader. Otherwise, some EDRs will not be correctly filtered.

Example Using a Pure JMS Listener

Example 16-1 Using a Pure JMS Listener

public class ClientJMSListener implements MessageListener {
  public void onMessage(Message msg) {
    // Extract the EdrData object or array
    if(o instanceof EdrData[]) {
      for(EdrData edr : (EdrData[])o) {
        //do something with each EDR
      }
    } 
  }
}

Example Using JMSListener Utility with No Filter

Example 16-2 Using a Subclass of JMSListener with No Filter Specified

public class SampleEdrJMSListener extends JMSListener {
  public SampleEdrJMSListener(String url) throws Exception {
    // Register in the JMS topic. No filter is specified so 
    // the "tag" filtering mechanism will be used.
    register(url);
  }
  @Override
  public void onEdr(EdrData edr, ConfigDescriptor descriptor) {
    // The "tag" mechanism will filter the stream of EDRs according
    // to the internal filtering. To know which type of EDR is 
    // actually provided in this method, we have to determine the 
    // instance of the ConfigDescriptor as follow:
    if(descriptor instanceof EdrConfigDescriptor) {
      // do something with this EDR
    } else if(descriptor instanceof AlarmConfigDescriptor) {
      // do something with this alarm
    } else if(descriptor instanceof CdrConfigDescriptor) {
      // do something with this CDR
    }
  }
}

Using JMSListener Utility with a Filter

Example 16-3 Using a Subclass of JMSListener with a Specified Filter

public class SampleEdrJMSListener extends JMSListener {

  public SampleEdrJMSListener(String url) throws Exception {
    // Register in the JMS topic. Use the default alarm filter. 
    // Note that in this case all classes needed by the alarm.xml file 
    // must be in the current class loader in order for the filtering 
    // to work correctly.
    register(url, EdrFilterFactory.createDefaultFilterForAlarm());
  }
  @Override
  public void onEdr(EdrData edr, ConfigDescriptor descriptor) {
    // Only AlarmConfigDescriptor should be received here. 
    // Just check before casting.
    if(descriptor instanceof AlarmConfigDescriptor) {
      ... do something with this alarm
    }
  }
}

Note:

When using the JMSListener class, make sure that any modification to an EDR, CDR, or alarms descriptor in Services Gatekeeper is also updated in the edrjmslistener.jar file.

Understanding an EDR listener utility

The EDR listener utility contains a set of classes to use when creating an external JMS listener using the JMSListener.

The helper classes are in Middleware_home/ocsg_pds/lib/wlng/edrjmslistener.jar.

Class JMSListener

Table 16-1 lists the important JMSListener methods. See the "All Classes" section of Services Gatekeeper Java API Reference for details on JMSListener.

Table 16-1 JMSListener Methods

Method Description

public void register(String url)

Registers the JMS listener to the EDR topic using no filter. The filtering will be done using the tagging mechanism. The parameter url specifies the URL of a Network Tier server.

public void register(String url, EdrFilter filter)

Registers the JMS listener to the EDR topic using the specified filter.

public void onEdr(EdrData edr, ConfigDescriptor descriptor)

Method that the subclass can override to get notified each time an EDR is received.

The descriptor is a subclass of ConfigDescriptor that identifies the type of EDR: one of EdrConfigDescriptor, AlarmConfigDescriptor or CdrConfigDescriptor.


Understanding the Helper JMSListener Helper Classes

Table 16-2 shows the JMSListener helper classes and their important methods. See the "All Classes" section of Services Gatekeeper Java API Reference for details on these JMSListener helper classes.

Table 16-2 JMSLisytener Helper Classes

JMSListener Helper Class Description

EdrFilterFactory

Creates the default filter used by Services Gatekeeper to filter the EDRs using the edr.xml, alarm.xml, or cdr.xml file in the edrjmslistener.jar file, depending on EDR listener alternative used.

EdrData

Does one of the following:

  • Contains all the values that EDRs (alarm and CDR) have.

  • Gets the value associated with the specified key.

  • Gets the values associated with the specified key.

ConfigDescriptor

The parent class of EdrConfigDescriptor, AlarmConfigDescriptor and CdrConfigDescriptor.

EdrConfigDescriptor

Does one of the following:

  • Contains the data specified in the descriptors in the edr.xml configuration file: the identifier and the description.

  • Returns the identifier of the EDR.

  • Returns the description of the EDR.

AlarmConfigDescriptor

Contains the data specified in the descriptors in the alarm.xml configuration file: the identifier, the severity and the description of the alarm.

CdrConfigDescriptor

Identifies a CDR. This descriptor does not contain any additional data.


Updating EDR configuration files

If you are using external EDR listeners, and the alarm, CDR, or EDR descriptors have been updated in Services Gatekeeper, the corresponding files need to be updated in edrjmslistener.jar. Update the corresponding xml file with the updated entries in the edr directory in edrjmslistener.jar.