IBM WebSphere Application ServerTM
Release 8

com.ibm.events.catalog
Class EventDefinition

java.lang.Object
  extended by com.ibm.events.catalog.EventDefinition
All Implemented Interfaces:
java.io.Serializable

public class EventDefinition
extends java.lang.Object
implements java.io.Serializable

Represents an event definition. An event definition consists of:

The name of an event definition is the same as the name of the Common Base Event extension that uses it.

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 following inherited aspects can be overridden:

The following aspects cannot be overridden:

An event definition contains a flag that can be queried using the isResolved() method. If true, the flag indicates that the inheritance hierarchy has been resolved and the event definition is a composite of the base event definition and all the extended data element and property descriptions it inherits. If false, the flag indicates that the object is the unresolved event definition only.

The event definition at the top of the hierarchy is known as the root event definition. The event catalog can contain only one root event definition. Attempting to add another root event definition will result in a ParentNotValidException.

Changes to an event definition are not persisted unless the event definition is replaced in the event catalog by calling the EventCatalog.addEventDefinition(EventDefinition definition, boolean replace) method with replace set to true.

EVENT DEFINITION INHERITANCE RULES

Event definition inheritance rules define how a child event definition inherits or overrides the extended data element and property descriptions of its parent.

When adding an event definition to the event catalog, be aware of the following:

Make sure the event definition does not override anything it should not. The EventCatalog.addEventDefinition() method checks for this and throws an InheritanceNotValidExceptionif there is a violation.

Make sure no existing descendants will be rendered invalid by anything in the event definition being added. This can only happen when the event definition is replacing an existing one and the existing one has children. Suppose for example that a child (or any descendant) describes an extended data element named "policy" and of type "string". If the event definition being added describes an extended data element of the same name but type "int", the child will be in violation of the rules. The EventCatalog.addEventDefinition() method checks for this also and again fails with InheritanceNotValidException.

Extended data element descriptions

An event definition inherits an extended data element description as-is from a parent if it does not already have a description of the same name. If it does have a description of the same name, each field of the description may override or inherit from the parent as follows.

Property descriptions

An event definition inherits a property description "as is" from a parent if it does not already have a description of the same name and path. If it does have a description of the same name and path, each field of the description overrides or inherits from the parent as follows:

Some results of this rule are:

Since:
5.1.0
Version:
1.3 1/17/06
See Also:
EventCatalog, ExtendedDataElementDescription, PropertyDescription, Serialized Form

Constructor Summary
EventDefinition(java.lang.String name, java.lang.String parentName)
          Creates an empty event definition that does not contain extended data element descriptions or property descriptions.
 
Method Summary
 void addExtendedDataElementDescription(ExtendedDataElementDescription description)
          Adds a description of an extended data element that an event that uses this event definition can contain.
 void addPropertyDescription(PropertyDescription description)
          Adds a description of a property that an event that uses this event definition can contain.
 boolean equals(java.lang.Object obj)
          Indicates whether some other object represents the same event definition as this object.
 ExtendedDataElementDescription getExtendedDataElementDescription(java.lang.String name)
          Returns an extended data element description from the list of extended data element descriptions.
 ExtendedDataElementDescription[] getExtendedDataElementDescriptions()
          Returns descriptions of the extended data elements that an event using this event definition may contain.
 java.lang.String getName()
          Returns the name of this event definition.
 java.lang.String getParentName()
          Returns the name of this event definition's immediate parent.
 PropertyDescription getPropertyDescription(java.lang.String name, java.lang.String path)
          Returns a property description from the list of property descriptions.
 PropertyDescription[] getPropertyDescriptions()
          Returns descriptions of the properties that an event that uses this event definition can contain.
 boolean isResolved()
          Returns a flag that indicates whether the inheritance hierarchy has been resolved.
 void setResolved(boolean resolved)
          Sets a flag to indicate whether the inheritance hierarchy has been resolved.
 java.lang.String toString()
          Returns a string representation of this event definition.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

EventDefinition

public EventDefinition(java.lang.String name,
                       java.lang.String parentName)
                throws ValueTooLongException
Creates an empty event definition that does not contain extended data element descriptions or property descriptions. The resolved flag (see isResolved()) is set to false.

Parameters:
name - The name of the event definition.
parentName - The name of the event definition's parent. Specifying null or empty identifies this to be the root event definition.
Throws:
ValueTooLongException - If either name or parentName is too long. An event definition name is synonymous with a Common Base Event extension name, and the Common Base Event Specification sets the maximum length of the extension name to be 64 characters.
java.lang.IllegalArgumentException - if name is null or empty.
Method Detail

getExtendedDataElementDescription

public ExtendedDataElementDescription getExtendedDataElementDescription(java.lang.String name)
Returns an extended data element description from the list of extended data element descriptions.

Parameters:
name - The name of the extended data element whose description is required.
Returns:
An extended data element description or null if the list of extended data element descriptions does nto contain entry for an extended data element of the given name.

getExtendedDataElementDescriptions

public ExtendedDataElementDescription[] getExtendedDataElementDescriptions()
Returns descriptions of the extended data elements that an event using this event definition may contain.

Returns:
An array of extended data element descriptions, or an empty array if this event definition does not describe extended data elements. This method never returns null.

getName

public java.lang.String getName()
Returns the name of this event definition.

Returns:
The name.

getParentName

public java.lang.String getParentName()
Returns the name of this event definition's immediate parent.

Returns:
The name or null if this is the root event definition.

getPropertyDescription

public PropertyDescription getPropertyDescription(java.lang.String name,
                                                  java.lang.String path)
Returns a property description from the list of property descriptions.

Parameters:
name - The name of the property whose description is required.
path - The path of the property whose description is required. Specifying null or the empty string identifies a property that exists at the top level in the Common Base Event.
Returns:
An property description or null if the list of property descriptions does not contain entry for a property of the given name and path.

getPropertyDescriptions

public PropertyDescription[] getPropertyDescriptions()
Returns descriptions of the properties that an event that uses this event definition can contain.

Returns:
An array of property descriptions or an empty array if this event definition does not describe properties. This method never returns null.

setResolved

public void setResolved(boolean resolved)
Sets a flag to indicate whether the inheritance hierarchy has been resolved. true means that this object is a composite of the raw event definition and all the extended data element and property descriptions it inherits (see event definition inheritance rules ). false means that this object is only the raw event definition.

Parameters:
resolved - The value to set.

isResolved

public boolean isResolved()
Returns a flag that indicates whether the inheritance hierarchy has been resolved. If true, this object is a composite of the raw event definition and all the extended data element and property descriptions it inherits (see event definition inheritance rules ). If false, this object is only the raw event definition.

This flag only has meaning for event definitions retrieved from the event catalog database. The event catalog sets the flag according to the value specified for the resolve parameter on the method called to get the event definition.

Returns:
true if the inheritance hierarchy has been resolved and this object is a composite. Otherwise false.

addExtendedDataElementDescription

public void addExtendedDataElementDescription(ExtendedDataElementDescription description)
                                       throws ArgumentNotValidException,
                                              DescriptionExistsException
Adds a description of an extended data element that an event that uses this event definition can contain.

Parameters:
description - The extended data element description to add.
Throws:
ArgumentNotValidException - If description is null.
DescriptionExistsException - If this event definition already contains a description for an extended data element of the same name.

addPropertyDescription

public void addPropertyDescription(PropertyDescription description)
                            throws ArgumentNotValidException,
                                   DescriptionExistsException
Adds a description of a property that an event that uses this event definition can contain.

Parameters:
description - The property description to add.
Throws:
ArgumentNotValidException - If description is null.
DescriptionExistsException - If this event definition already contains a description for a property of the same name and path.

equals

public boolean equals(java.lang.Object obj)
Indicates whether some other object represents the same event definition as this object. Two event definitions are equal if all their fields are equal. In the case of multi-valued fields, both must contain the same set of values although not necessarily in the same order. Both must contain matching sets of extended data element descriptions and property descriptions, but again order is not important.

Overrides:
equals in class java.lang.Object
Parameters:
obj - The reference object to compare to.
Returns:
true if this object and the reference object represent the same event definition. Otherwise, false.

toString

public java.lang.String toString()
Returns a string representation of this event definition.

Overrides:
toString in class java.lang.Object
Returns:
A string.

IBM WebSphere Application ServerTM
Release 8