com.ibm.events.catalog
Interface EventCatalog

All Superinterfaces:
javax.ejb.EJBObject, java.rmi.Remote

public interface EventCatalog
extends javax.ejb.EJBObject

Remote interface for the event catalog enterprise bean in the Common Event Infrastructure.

An event catalog stores the following information.

Event definitions

An event definition describes extended data elements and properties that an event can have. All Common Base Events that have the same extension name share the same event definition, and the name of the event definition is the same as the extension name.

Event definitions are arranged in a hierarchy in which a child event definition inherits the extended data element and property descriptions of its parent. The event definition at the top of the hierarchy is known as the root event definition. Only one root event definition can exist.

When an event definition is retrieved, there is a choice whether to return the unresolved event definition or to resolve the inheritance hierarchy and return a composite of the event definition and all the extended data element and property descriptions it inherits. Different applications will have different needs. For example, an eventvalidator will want the resolved event definition so it can immediately check whether an event conforms to it. An event definition editor will want the unresolved event definition. All methods that get event definitions include a parameter to specify whether to resolve the inheritance. Resolution occurs according to a set of rules called the event definition inheritance rules.


Grouping of Common Base Event extensions into event source categories

An event source category is a way of grouping event extensions according to the type of sources that can produce events of given extensions. One event source category can include many Common Base Event extensions, and a Common Base Event extension can be in many event source categories.

Since:
5.1.0
Version:
1.15 6/9/04
See Also:
EventDefinition

Method Summary
 void addEventDefinition(EventDefinition definition, boolean replace)
          Adds an event definition to the event catalog or replaces an existing event definition.
 void addEventDefinitions(EventDefinition[] definitions, boolean replace)
          Adds an event definition array to the event catalog or replaces existing event definitions.
 void bindEventExtensionToSourceCategory(java.lang.String eventExtensionName, java.lang.String eventSourceCategory)
          Binds an event extension to an event source category.
 EventDefinition[] getAncestors(java.lang.String name, boolean resolve)
          Returns the event definitions that are the ancestors of a given event definition in the inheritance hierarchy.
 EventDefinition[] getChildren(java.lang.String name, boolean resolve)
          Returns the event definitions that are the immediate children of a given event definition in the inheritance hierarchy.
 EventDefinition[] getDescendants(java.lang.String name, boolean resolve)
          Returns the event definitions that are the descendants of a given event definition in the inheritance hierarchy.
 EventDefinition getEventDefinition(java.lang.String name, boolean resolve)
          Returns an event definition.
 EventDefinition[] getEventDefinitions(java.lang.String pattern, boolean resolve)
          Returns event definitions whose names match a pattern.
 java.lang.String[] getEventExtensionNamesForSourceCategory(java.lang.String eventSourceCategory)
          Returns the names of the Common Base Event extensions that are members of a given event source category.
 java.util.Collection getEventExtensionToSourceCategoryBindings(java.lang.String eventExtensionNamePattern, java.lang.String eventSourceCategoryPattern)
          Returns bindings between Common Base Event extensions whose names match a pattern and event source categories that match a pattern.
 EventDefinition getParent(java.lang.String name, boolean resolve)
          Returns the event definition that is the immediate parent of a given event definition in the inheritance hierarchy.
 EventDefinition getRoot()
          Returns the root event definition.
 java.lang.String[] getSourceCategoriesForEventExtension(java.lang.String eventExtensionName)
          Returns the event source categories that have a given event extension as a member.
 void removeEventDefinition(java.lang.String name)
          Removes an event definition from the event catalog.
 void unbindEventExtensionFromSourceCategory(java.lang.String eventExtensionName, java.lang.String eventSourceCategory)
          Removes the binding of an event extension to an event source category.
 
Methods inherited from interface javax.ejb.EJBObject
getEJBHome, getHandle, getPrimaryKey, isIdentical, remove
 

Method Detail

getAncestors

public EventDefinition[] getAncestors(java.lang.String name,
                                      boolean resolve)
                               throws EventsException,
                                      java.rmi.RemoteException
Returns the event definitions that are the ancestors of a given event definition in the inheritance hierarchy.
Parameters:
name - The name of the event definition.
resolve - If true, the inheritance hierarchy is resolved and the returned objects are each a composite of a base event definition and all the extended data element and property descriptions it inherits. If false, the returned objects are only the unresolved event definitions.
Returns:
An array of the event definitions that contains the event definition's ancestors from the root down to and including its immediate parent, or an empty array if the event definition has no children. This method never returns null.
Throws:
EventDefinitionNotFoundException - If no event definition of the given name exists in the event catalog.
ValueTooLongException - If the specified name is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If the specified name is null or an empty string.

getChildren

public EventDefinition[] getChildren(java.lang.String name,
                                     boolean resolve)
                              throws EventsException,
                                     java.rmi.RemoteException
Returns the event definitions that are the immediate children of a given event definition in the inheritance hierarchy.
Parameters:
name - The name of the event definition.
resolve - If true, the inheritance hierarchy is resolved and the returned objects are each a composite of a base event definition and all the extended data element and property descriptions it inherits. If false, the returned objects are the unresolved event definitions only.
Returns:
An array of the child event definitions or an empty array if the event definition has no children. This method never returns null.
Throws:
EventDefinitionNotFoundException - If the named event definition does not exist in the event catalog.
ValueTooLongException - If the specified name is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If name is null or an empty string.

getDescendants

public EventDefinition[] getDescendants(java.lang.String name,
                                        boolean resolve)
                                 throws EventsException,
                                        java.rmi.RemoteException
Returns the event definitions that are the descendants of a given event definition in the inheritance hierarchy.
Parameters:
name - The name of the event definition.
resolve - If true, the inheritance hierarchy is resolved and the returned objects are each a composite of a raw event definition and all the extended data element and property descriptions it inherits. If false, the returned objects are the raw event definitions only.
Returns:
An array of all descendant events or an empty array if the event definition has no children. This method never returns null.
Throws:
EventDefinitionNotFoundException - If the named event definition does not exist in the event catalog.
ValueTooLongException - If the specified name is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If name is null or an empty string.

getEventDefinition

public EventDefinition getEventDefinition(java.lang.String name,
                                          boolean resolve)
                                   throws EventsException,
                                          java.rmi.RemoteException
Returns an event definition.
Parameters:
name - The name of the event definition.
resolve - If true, the inheritance hierarchy is resolved and the returned object is a composite of the raw event definition and all the extended data element and property descriptions it inherits. If false, the returned object is the raw event definition only.
Returns:
The event definition or null if an event definition of this name exists does nt exist.
Throws:
ValueTooLongException - If the specified name is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If name is null or an empty string.

getEventDefinitions

public EventDefinition[] getEventDefinitions(java.lang.String pattern,
                                             boolean resolve)
                                      throws EventsException,
                                             java.rmi.RemoteException
Returns event definitions whose names match a pattern.
Parameters:
pattern - A pattern to be matched against the names of event definitions. % matches any sequence of zero or more characters. _ matches any single character. Any %, _ or \ in the name must be escaped with \. All other characters match exactly.
resolve - If true, the inheritance hierarchy is resolved and the returned objects are each a composite of a raw event definition and all the extended data element and property descriptions it inherits. If false, the returned objects are the raw event definitions only.
Returns:
An array of event definitions, or an empty array if the catalog contains no event definitions matching the given pattern. The event definitions are arranged in ascending order of name. This method never returns null.
Throws:
ValueTooLongException - If the specified pattern is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If pattern is null or an empty string.

getEventExtensionNamesForSourceCategory

public java.lang.String[] getEventExtensionNamesForSourceCategory(java.lang.String eventSourceCategory)
                                                           throws EventsException,
                                                                  java.rmi.RemoteException
Returns the names of the Common Base Event extensions that are members of a given event source category.
Parameters:
eventSourceCategory - the event source category.
Returns:
an array in ascending order of event extension names, or an empty array if the given event source category contains no members. This method never returns null.
Throws:
ValueTooLongException - If the specified eventSourceCategory is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If eventSourceCategory is null or an empty string.

getEventExtensionToSourceCategoryBindings

public java.util.Collection getEventExtensionToSourceCategoryBindings(java.lang.String eventExtensionNamePattern,
                                                                      java.lang.String eventSourceCategoryPattern)
                                                               throws EventsException,
                                                                      java.rmi.RemoteException
Returns bindings between Common Base Event extensions whose names match a pattern and event source categories that match a pattern. The bindings are returned as a java.util.Collection of string arrays in which each array names an event extension and an event source category to which it is bound.

For example, the following code displays the bindings of all event extensions whose names begin with "insurance_claim_start".

 Collection col = catalog.getEventExtensionToSourceCategoryBindings("insurance_claim_start%", "%");
 Iterator it = col.iterator();
 while (it.hasNext()) {
     String[] binding = (String[])it.next();
     System.out.println("Common Base Event extension " + binding[0] + " is bound to event source category " + binding[1]);
 }
 
The following statement returns all bindings.
 Collection col = catalog.getEventExtensionToSourceCategoryBindings("%", "%");
 

Parameters:
eventExtensionNamePattern - A pattern to be matched against the names of event extensions. % matches any sequence of zero or more characters. _ matches any single character. All other characters match exactly.
eventSourceCategoryPattern - A pattern to be matched against event source categories. % matches any sequence of zero or more characters. _ matches any single character. Any %, _ or \ in the name must be escaped with \. All other characters match exactly.
Returns:
A java.util.Collection in which each element is an array of two string objects. The first string names a event extension and the second string is an event source category to which the event extension is bound. The java.util.Collection is empty if no bindings exist. This method never returns null.
Throws:
ValueTooLongException - If either the specified eventExtensionNamePattern or eventSourceCategoryPattern is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If either eventExtensionNamePattern or eventSourceCategoryPattern is null or an empty string.

getParent

public EventDefinition getParent(java.lang.String name,
                                 boolean resolve)
                          throws EventsException,
                                 java.rmi.RemoteException
Returns the event definition that is the immediate parent of a given event definition in the inheritance hierarchy.
Parameters:
name - The name of the event definition.
resolve - If true, the inheritance hierarchy is resolved and the returned object is a composite of the raw event definition and all the extended data element and property descriptions it inherits. If false, the returned object is only the raw event definition.
Returns:
The parent event definition or null if the event definition is the root event definition.
Throws:
EventDefinitionNotFoundException - If the named event definition does not exist in the event catalog.
ValueTooLongException - If the specified name is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - if name is null or an empty string.

getRoot

public EventDefinition getRoot()
                        throws EventsException,
                               java.rmi.RemoteException
Returns the root event definition.
Returns:
The root event definition or null if a root event definition does not exists.
Throws:
EventsException - If any error occurs when accessing the event catalog database.

getSourceCategoriesForEventExtension

public java.lang.String[] getSourceCategoriesForEventExtension(java.lang.String eventExtensionName)
                                                        throws EventsException,
                                                               java.rmi.RemoteException
Returns the event source categories that have a given event extension as a member.
Parameters:
eventExtensionName - The name of the event extension.
Returns:
An array in ascending order of event source categories or an empty array if the given event extension is not a member of any event source category. This method never returns null.
Throws:
ValueTooLongException - If the specified eventExtensionName is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If eventExtensionName is null or an empty string.

addEventDefinition

public void addEventDefinition(EventDefinition definition,
                               boolean replace)
                        throws EventsException,
                               java.rmi.RemoteException
Adds an event definition to the event catalog or replaces an existing event definition.

If the replace parameter is false, the event definition is added as a new event definition. Its name must be unique.

If the replace parameter is true, the event definition replaces an existing event definition of the same name. The new event definition and the event definition it replaces occupy the same place in the hierarchy of event definitions. Therefore both event definitions must both name the same parent. Any children of the event definition being replaced become children of the new event definition. However the extended data element and property descriptions of the event definition being replaced are not carried over. They are deleted and replaced by those of the new event definition.

Parameters:
definition - The event definition to add.
replace - Replace any existing event definition of the same name.
Throws:
ArgumentNotValidException - If definition is null.
EventDefinitionExistsException - If replace is false and the Event Catalog already contains an event definition having the same name as this one.
ParentNotValidException - If one of the following is true: the event definition names as its parent an event definition that does not exist in the Event Catalog; the event definition is a root (it names no parent) but there is already a root event definition in the Event Catalog; an existing event definition of the same name is being replaced and the parent named by the replacement is not the parent of the existing event definition.
InheritanceNotValidException - If adding the event definition would violate the {@linkevent definition inheritance rules}.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If definition is null.

addEventDefinitions

public void addEventDefinitions(EventDefinition[] definitions,
                                boolean replace)
                         throws EventsException,
                                java.rmi.RemoteException
Adds an event definition array to the event catalog or replaces existing event definitions.

If the replace parameter is false, an event definition in the array is added as a new event definition. Its name must be unique.

If the replace parameter is true, an event definition in the array replaces any existing event definition of the same name. The new event definition and the event definition it replaces occupy the same place in the hierarchy of event definitions. Therefore both event definitions must both name the same parent. Any children of the event definition being replaced become children of the new event definition. However the extended data element and property descriptions of the event definition being replaced are not carried over. They are deleted and replaced by those of the new event definition.

Parameters:
definitions - An array of event definitions.
replace - Replace any existing event definition of the same name.
Throws:
java.rmi.RemoteException - If definitions is null.
EventDefinitionExistsException - If replace is false and the event catalog already contains an event definition with the same name as this one.
ParentNotValidException - If one of the following is true: an event definition in the array names as its parent an event definition that does not exist in the event catalog; an event definition in the array is a root (it names no parent) but there is already a root event definition in the Event Catalog; an existing event definition of the same name is being replaced and the parent named by the replacement is not the parent of the existing event definition.
InheritanceNotValidException - If adding an event definition in the array would violate the {@linkevent definition inheritance rules}.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If any of the definition elements is null.

bindEventExtensionToSourceCategory

public void bindEventExtensionToSourceCategory(java.lang.String eventExtensionName,
                                               java.lang.String eventSourceCategory)
                                        throws EventsException,
                                               java.rmi.RemoteException
Binds an event extension to an event source category. In other words, it makes the event extension a member of the given event source category. No action is taken if the event extension is already a member of the event source category.

The mapping of event extension to an event source category is many to many. This means an event extension may be a member of several event source categories, and an event source category can include several event extensions.

Parameters:
eventExtensionName - The name of the event extension.
eventSourceCategory - The event source category.
Throws:
ValueTooLongException - If either eventExtensionName or eventSourceCategory is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If either eventExtensionName or eventSourceCategory is null or an empty string.

removeEventDefinition

public void removeEventDefinition(java.lang.String name)
                           throws EventsException,
                                  java.rmi.RemoteException
Removes an event definition from the event catalog. All event definitions below the event definition hierarchy are also removed. This includes its children, the children of its children and so on.

This method does not warn if an event definition being removed is currently referenced by an event in the data store

Parameters:
name - The name of the event definition to remove.
Throws:
ValueTooLongException - If name is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If name is null or an empty string.

unbindEventExtensionFromSourceCategory

public void unbindEventExtensionFromSourceCategory(java.lang.String eventExtensionName,
                                                   java.lang.String eventSourceCategory)
                                            throws EventsException,
                                                   java.rmi.RemoteException
Removes the binding of an event extension to an event source category. In other words, it deletes the event extension's membership of the given event source category. No action is taken if the event extension is not a member.
Parameters:
eventExtensionName - The name of the event extension.
eventSourceCategory - The event source category.
Throws:
ValueTooLongException - If either eventExtensionName or eventSourceCategory is too long.
EventsException - If any error occurs when accessing the event catalog database.
java.rmi.RemoteException - If either eventExtensionName or eventSourceCategory is null or an empty string.