A Filter System Object is a cohesive unit of functionality that performs a well-defined task on XML events flowing through the system. Filters are chained together inside Filter Stacks to solve specific parts of application problems. These filter stacks can then be replicated, reconfigured and reused to perform similar tasks inside Event Correlation Applications (ECA’s).

Most filters process events in a synchronous manner using a one-element queue and utilizing the thread of the calling object (the parent Filter Stack). This policy conserves valuable system resources, since the number of filters in a stack can be fairly significant for each individual filter to have its own thread.

Perform the following steps when writing a typical EventGnosis Filter:

1. Extend the abstract class com.eventgnosis.filters.FilterBase, which itself extends
   com.eventgnosis.system.SystemObject. Since a Filter is a SystemObject you inherit significant functionality, and your new object will be part of the startup and runtime object hierarchy automatically, given that this Filter is active and configured into an ECA. This behind-the-scenes work is automatically performed by the ECS framework.
   
   
2. Come up with a terse English text description of your Filter with configuration parameters between the ‘%’ modeled after the filterType examples in EV_HOME/config/extra/emptyECA.xml. The GUI will assume that any text surrounded by ‘%’ is a parameter and will be presented to the user as a configuration parameter, validated and stored with a configuration value. Every parameter you use should have a corresponding parameterType definition in the EMML (XML) file. Finally, this parameter will be parsed by the ECS Configuration Manager at startup and used by the particular Filter to set its configuration in its setVars() method.
   Example XML:

   <filterType description="If event matches %Condition% route to %DestinationName%." objectId="RouteEventFilter" schema="">
        <implement class="com.eventgnosis.filters.RouteEventFilter" source="ecs.jar" type="Java" />
   </filterType>

   This XML snippet should be added to the file EV_HOME/config/extra/emptyECA.xml, the configuration source for the GUI and the ECS. Note that this example has two parameters (Condition & DestinationName), which will be set and validated by the GUI when a user selects a “RouteEventFilter” Filter. You will also need to set the path to your implementation here
   (com.eventgnosis.filter.RouteEventFilter) and its jar. Typically, you could create an add-on jar that is separate from the ecs.jar and is specific to your company, and uses a specific package/class name such as com.yourcompany.filters.filterName. This new jar must, of course, be in the classpath of the ECS for it to be recognized.
   
   

3. Add any specific attributes that are needed to retain any state information for your filter to the implementing class, as in the private attributes at the top of the class
   com.eventgnosis.filters.RouteEventFilter.
   
   
4. Implement setVars(). First call the superclass method, extracting each ECA configuration parameter into your filter attributes for this instance of the filter. Examples of configuration parameters for the RouteEventFilter are Condition and DestinationName. Note that each parameter set by the GUI can be extracted using the object EmmlConfig (eCfg) object using method getParameter( name, instance# ), where name is the name of the parameter from its XML description and instance number is a simple index of which configuration instance (there can be more than one with the same name) starting from zero. The first instance is zero, the next instance is one, and so on. Note that getParameter(…) returns a String. If the Filter’s class attribute is not of type java.lang.String it must be converted (cast) to its requisite type. Conversion methods for the most common types can be found in com.eventgnosis.util.Util.java. Furthermore, some parameter types set by the GUI are not primitives but are composite types, such as the type Condition. A composite type can be referred to in a SystemObject description, but it must then be defined with a parameterType XML snippet in ECA so that the GUI can understand the composition:

   <parameterType description="???" objectId="Condition" schema="">
        <implement class="com.eventgnosis.filters.Condition" source="ecs.jar" type="Java" /> 
   </parameterType>

   If composite types are utilized, they must, of course, be implemented, and added into your jar and the usual information specified in the “implement” section so that the ECS can locate your code. Examples of such implementations are com.eventgnosis.filters.Condition, and its use in setVars() in com.eventgnosis.filters.RouteEventFilter. In summary, each Filter attribute must be carefully processed in setVars() using the following steps:

   1. Get the parameter instance as a string specified by name and index.
   2. Convert to the requisite class attribute type, if it’s not a Java String.
   3. Check for conversion errors, and if so, log errors and consider disabling the object for fatal values or applying a default value.
   4. Implement the consistency rules between parameters, and error out if there are serious inconsistencies.
5. Implement processEvent(), probably the most important method, which is called by the framework for each incoming event. After processing the event, this method returns a routing list – tuples of {Event/Destination} – which will be used to appropriately route events through the system to zero or more destinations. A good reference implementation for processEvent() is
   com.eventgnosis.filters.RouteEventFilter. Typically, a filter performs distinct operations on an event, depending on the preconfigured values of the Condition object. The superclass methods setCondition() and matchCondition() are very useful in this regard since your specific processing is usually contingent on the value of the condition, existing inside the matchCondition() if/else block. Significant utilities exist for adding/editing/deleting the fields of an event. Reference examples exhibiting this capability are com.eventgnosis.filters.AddFieldFilter, com.eventgnosis.filters.EditFieldFilter and com.eventgnosis.filters.DeleteFieldFilter. Very complex filter behavior is possible with advanced implementations. A separate thread for a given filter is added when independent time control/alarming is necessary (see com.eventgnosis.filters.DetectUniqueIncompleteSequenceFilter). Complex correlation behavior can be localized to a single filter by providing database access, Java sub-objects and variable event routing, as in the com.eventgnosis.filters.RouteEventFilter. Finally, the paradigm of firing a list of Actions dependent on certain conditions lends tremendous power to action-taking based on recognized event conditions inside a filter. This set of actions can be logically configured to initiate a set of actions dependent on the existence or non-existence of value, timing or other conditions recognized within a filter. This type of functionality makes ECS functionality pretty much up to the imagination, unlimited by the usual implementation barriers.
   
   
6. Implement getConfigXml(), which is a snapshot of configuration state.
   
   
7. Implement getRuntimeXml(), which is a snapshot of runtime state.