com.ibm.events.catalog
Class PropertyDescription

java.lang.Object
  |
  +--com.ibm.events.catalog.PropertyDescription
All Implemented Interfaces:
java.io.Serializable

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

Describes a property that an event can contain. Any property can be described, provided it is defined in the Common Base Event Specification as a simple type. Examples are severity and priority. This class does not handle properties that are complex types, such as msgDataElement, although it can be used to describe simple properties that are children of such a property.

The information held about a property includes:

It can also include the following information:

The path is an XPath expression operating on the model of the Common Base Event defined in the Common Base Event Specification. It identifies the parent property of the property being described. These are some examples:

The XPath syntax allows specific instances of a repeated property to be addressed. For example:

IMPORTANT NOTE: A property description only overrides an identically named property description in a parent event definition if the path expressions are identical in every respect including case.

Since:
5.1.0
Version:
1.18 6/9/04
See Also:
EventDefinition, Serialized Form

Constructor Summary
PropertyDescription(java.lang.String name, java.lang.String path)
          Creates a description for a property identified by its name and path.
 
Method Summary
 boolean equals(java.lang.Object obj)
          Indicates whether another object represents the same property description as this object.
 java.lang.String getDefaultValue()
          Returns the value set as the default for the property.
 java.lang.String getDisplayName()
          Returns the path and name of the property concatenated to a single string suitable for display.
 java.lang.String getMaxValue()
          Returns the maximum value that the property can take.
 java.lang.String getMinValue()
          Returns the minimum value that the property can take.
 java.lang.String getName()
          Returns the name of the property.
 java.lang.String getPath()
          Returns the path that locates the property within the event.
 java.lang.String[] getPermittedValues()
          Returns the values that the property can take.
 boolean isRequired()
          Indicates whether the property is required or optional.
 void setDefaultValue(java.lang.String value)
          Sets a value to be the default for the property.
 void setMaxValue(java.lang.String value)
          Constrains the property by setting the maximum value it can take.
 void setMinValue(java.lang.String value)
          Constrains the property by setting the minimum value it is can take.
 void setPermittedValues(java.lang.String[] values)
          Constrains the property by setting the values can take.
 void setRequired(boolean required)
          Sets a flag that indicates whether the property is required or optional.
 java.lang.String toString()
          Returns a string representation of this property description.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PropertyDescription

public PropertyDescription(java.lang.String name,
                           java.lang.String path)
                    throws ValueTooLongException
Creates a description for a property identified by its name and path.

IMPORTANT NOTE: A property description will only override an identically named property description in a parent event definition if the paths are identical in every respect including case.

Parameters:
name - The name of the property.
path - An XPath expression that locates the property within the event. For more information see the class description. Specifying null or the empty string specifies that the property exists at the top level in the Common Base Event. It is the caller's responsibility to ensure the expression is syntactically valid and that it addresses a property of the event.
Throws:
ValueTooLongException - If either name or path is too long. The maximum lengths are 64 and 1024 characters respectively and are limited by the capacity of the event catalog database fields that are used to store the values.
Method Detail

setDefaultValue

public void setDefaultValue(java.lang.String value)
                     throws ValueTooLongException
Sets a value to be the default for the property.

The value is supplied as a string. The using application must ensure that the value represented by the string is valid for the property's type as declared in the Common Base Event Specification. For example, if the property's type is int, it is not appropriate to supply the value apple.

It is meaningful for a property to both have a default and be required. Storing a default allows a completer to provide the property if it is required but not provided. An event generator might generate an event that is not valid because a required property is missing, but a completer could apply the default so that the event is valid by the time it is consumed.

Parameters:
value - The value to set. Specifying null or the empty string clears any value previously set.
Throws:
ValueTooLongException - If value is too long. The maximum length is 1024 characters and is limited by the capacity of the event catalog database field that is used to store the value.

getDefaultValue

public java.lang.String getDefaultValue()
Returns the value set as the default for the property.

The value is returned as a string. The using application must convert the value as necessary to the type declared for the property in the Common Base Event Specification.

Returns:
The default value, or null if no default value is set.

getDisplayName

public java.lang.String getDisplayName()
Returns the path and name of the property concatenated to a single string suitable for display. The path and name are separated by a forward slash. If the path is null, the string begins with the forward slash.
Returns:
The display name.

setMaxValue

public void setMaxValue(java.lang.String value)
                 throws OperationNotValidException,
                        ValueTooLongException
Constrains the property by setting the maximum value it can take.

The value is supplied as a string. The using application must ensure that the value represented by the String is valid for the property's type as declared in the Common Base Event Specification. For example, if the property's type is int, it is not appropriate to supply the value "apple".

A property can have a set of permitted values, or a minimum and/or maximum value, but not both.

Parameters:
value - The value to set. Specifying null or the empty string clears any value that was previously set.
Throws:
OperationNotValidException - If permitted values are already set.
ValueTooLongException - If value is too long. The maximum length is 1024 characters and is limited by the capacity of the event catalog database field that is used to store the value.

getMaxValue

public java.lang.String getMaxValue()
Returns the maximum value that the property can take.

The value is returned as a string. The using application must convert the value as necessary to the type declared for the property in the Common Base Event Specification.

A property can have a set of permitted values or a minimum and/or maximum value, but not both.

Returns:
The maximum value or null if no maximum value is set.

setMinValue

public void setMinValue(java.lang.String value)
                 throws OperationNotValidException,
                        ValueTooLongException
Constrains the property by setting the minimum value it is can take.

The value is supplied as a string. The using application must ensure that the value represented by the string is valid for the property's type as declared in the Common Base Event specification. For example, if the property's type is int, it is not appropriate to supply the value apple.

A property can have a set of permitted values or a minimum and/or maximum value, but not both.

Parameters:
value - The value to set. Specifying null or the empty string clears any value that was previously set.
Throws:
OperationNotValidException - If permitted values are already set.
ValueTooLongException - If value is too long. The maximum length is 1024 characters and is limited by the capacity of the event catalog database field that is used to store the value.

getMinValue

public java.lang.String getMinValue()
Returns the minimum value that the property can take.

The value is returned as a string. Tthe using application must convert the value as necessary to the type declared for the property in the Common Base Event Specification.

A property can have a set of permitted values or a minimum and/or maximum value, but not both.

Returns:
The minimum value or null if no minimum value is set.

getName

public java.lang.String getName()
Returns the name of the property.
Returns:
The name.

getPath

public java.lang.String getPath()
Returns the path that locates the property within the event. For more information see the class description.
Returns:
The path or null if the property exists at the top level in the event.

setPermittedValues

public void setPermittedValues(java.lang.String[] values)
                        throws ArgumentNotValidException,
                               OperationNotValidException,
                               ValueTooLongException
Constrains the property by setting the values can take.

The values are supplied as strings. The using application must ensure that the values represented by the Strings are valid for the property's type as declared in the Common Base Event Specification. For example, if the property's type is int, it is not appropriate to supply the value apple.

A property can have a set of permitted values or a minimum and/or maximum value, but not both.

Parameters:
values - An array of the values to set. Specifying null or an empty array clears any values previously set.
Throws:
ArgumentNotValidException - If any value is null or empty.
OperationNotValidException - If a minimum or maximum value, or both, is already set.
ValueTooLongException - If any value is too long. The maximum length is 1024 characters and is limited by the capacity of the event catalog database field that is used to store the values.

getPermittedValues

public java.lang.String[] getPermittedValues()
Returns the values that the property can take.

The values are returned as strings. The using application must convert the values as necessary to the type declared for the property in the Common Base Event Specification.

A property can have a set of permitted values or a minimum and/or maximum value, but not both.

Returns:
An array of permitted values or an empty array if no set of permitted values is defined. This method never returns null.

setRequired

public void setRequired(boolean required)
Sets a flag that indicates whether the property is required or optional. The initial value of the flag is false, which indicates that the property to be optional.

A property can be required and have a default. Storing a default allows a completer to provide the property if it is required but not provided. An event generator might generate an event that is not valid because a required property is missing, but a completer could apply the default so that the event is valid by the time it is consumed.

Parameters:
required - If true, the property is required. If false, the property is optional.

isRequired

public boolean isRequired()
Indicates whether the property is required or optional. For related information, see setRequired(boolean).
Returns:
true if the property is required, or false if the property is optional.

equals

public boolean equals(java.lang.Object obj)
Indicates whether another object represents the same property description as this object. Two property descriptions are equal if all their fields are equal. In the case of multi-valued fields, both objects must contain the same set of values although not necessarily in the same order.
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 property description. Otherwise, false.

toString

public java.lang.String toString()
Returns a string representation of this property description.
Overrides:
toString in class java.lang.Object
Returns:
A string.