com.ibm.events.catalog

Class EventDefinition

  • java.lang.Object
    • 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:
    • Its name
    • The name of its parent event definition
    • Descriptions of the extended data elements that an event using this event definition can contain (see ExtendedDataElementDescription)
    • Descriptions of the properties that an event that uses this event definition can contain (see PropertyDescription)

    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:

    • Changing the number of times an extended data element can appear
    • Changing the constraints on the value of a property

    The following aspects cannot be overridden:

    • Changing the type of an extended data element
    • Specifying that a required property is not required

    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.

    • Type: child must match parent.

    • Minimum occurrence: child always overrides parent.

    • Maximum occurrence: child always overrides parent.

    • Default values: child may override parent (child's values replace all parent's values); child inherits from parent if it has no values of its own.

    • Default hex value: child may override parent; child inherits from parent if it has no value of its own.

    • Nested extended data element description: child inherits from parent if it does not already have a nested description of the same name; if child does have a nested description of the same name, each of its fields may override or inherit from the corresponding nested description in the parent according to these same rules.

    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:

    • Default value: the child can override the parent. The child inherits from the parent if it has no value of its own.

    • Required: the child always overrides the parent but cannot set false if parent is true.

    • Permitted values, minimum/maximum values (note: it is not possible to set both permitted values and minimum/maximum values on a property description): the child can override the parent freely (including specifying minimum/maximum values where the parent has permitted values, and vice versa). The child inherits from the parent if it has neither permitted values nor minimum/maximum values of its own.

    Some results of this rule are:

    • If the parent has minimum/maximum values and the child sets permitted values, the parent's minimum/maximum values are ignored;
    • If both the parent and the child have permitted values, only the child's values are effective.

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

      Constructors 
      Constructor and Description
      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.
    • 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.
      • 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 Business Process ManagerTM
Release 8