com.ibm.events.catalog
Class ExtendedDataElementDescription

java.lang.Object
  extended bycom.ibm.events.catalog.ExtendedDataElementDescription
All Implemented Interfaces:
java.io.Serializable

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

Describes an extended data element that an event can contain. The information includes:

It may also include:

Since:
5.1.0
Version:
1.26 3/20/05
See Also:
EventDefinition, Serialized Form

Constructor Summary
ExtendedDataElementDescription(java.lang.String name, int type)
          Creates a description for an extended data element identified by its name.
 
Method Summary
 void addChild(ExtendedDataElementDescription description)
          Adds a description of a child extended data element.
 boolean equals(java.lang.Object obj)
          Indicates whether some other object represents the same extended data element description as this object.
 ExtendedDataElementDescription getChild(java.lang.String name)
          Returns the description of a child extended data element.
 ExtendedDataElementDescription[] getChildren()
          Returns all descriptions of child extended data elements.
 byte[] getDefaultHexValue()
          Returns the value set as the hexadecimal default for the extended data element.
 java.lang.String[] getDefaultValues()
          Returns the values set as the defaults for the extended data element.
 int getMaxOccurs()
          Returns the maximum number of times the extended data element must occur.
 int getMinOccurs()
          Returns the minimum number of times the extended data element must occur.
 java.lang.String getName()
          Returns the name of the extended data element (the value of its name property).
 int getType()
          Returns a value that indicates the type of the extended data element (the value of its type property).
 java.lang.String getTypeAsString()
          Returns the type of the extended data element (the value of its type property) as a string.
 void setDefaultHexValue(byte[] value)
          Sets a value to be the hexadecimal default for the extended data element.
 void setDefaultValues(java.lang.String[] values)
          Sets the values to be the defaults for the extended data element.
 void setMaxOccurs(int maxOccurs)
          Sets the maximum number of times the extended data element must occur.
 void setMinOccurs(int minOccurs)
          Sets the minimum number of times the extended data element must occur.
 java.lang.String toString()
          Returns a string representation of this extended data element description.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ExtendedDataElementDescription

public ExtendedDataElementDescription(java.lang.String name,
                                      int type)
                               throws ArgumentNotValidException,
                                      ValueTooLongException
Creates a description for an extended data element identified by its name.

Parameters:
name - The name of the extended data element.
type - The type of the extended data element. It must be one of the integer TYPE_<type>_VALUE constants defined in the class ExtendedDataElement, for example TYPE_INT_VALUE.
Throws:
ArgumentNotValidException - If type is not one of the proper values.
ValueTooLongException - If name is too long. The maximum length is set by the Common Base Event Specification at 64 characters.
Method Detail

getChild

public ExtendedDataElementDescription getChild(java.lang.String name)
Returns the description of a child extended data element.

An extended data element can contain other extended data elements nested to any depth. These are known as children and are themselves described by extended data element descriptions. This method returns the description of the named immediate child of the subject extended data element.

Parameters:
name - The name of the child extended data element.
Returns:
An extended data element description or null if a description does not exists for a child extended data element of the given name.

getChildren

public ExtendedDataElementDescription[] getChildren()
Returns all descriptions of child extended data elements.

An extended data element can contain other extended data elements nested to any depth. These are known as children and are themselves described by extended data element descriptions. This method returns the descriptions of the extended data elements that are the immediate children of the subject extended data element.

Returns:
An array of extended data element descriptions or an empty array if the subject extended data element contains no child extended data elements. This method never returns null.

setDefaultHexValue

public void setDefaultHexValue(byte[] value)
                        throws OperationNotValidException,
                               ValueTooLongException
Sets a value to be the hexadecimal default for the extended data element. If the element's type is not hexBinary, do npot use this method use the setDefaultValues(java.lang.String[]) instead.

The value is specified as an array of bytes. Byte values in the range 0 to 127 represent the hexadecimal pairs 00 to 7F. Byte values in the range -128 to -1 represent the hexadecimal pairs 80 to FF.

Parameters:
value - The hexadecimal value to set as an array of bytes. Specifying null or an empty array clears any value that was previously set.
Throws:
OperationNotValidException - If the extended data element's type is not hexBinary.
ValueTooLongException - If value is too long. The maximum length is 4000 bytes and is limited by a restriction of the event catalog database field in which the value is stored.

getDefaultHexValue

public byte[] getDefaultHexValue()
Returns the value set as the hexadecimal default for the extended data element. If the element's type is not hexBinary, the return array is empty.

The value is returned as an array of bytes. Hexadecimal pairs in the range 00 to 7F are represented by byte values 0 to 127. Hexadecimal pairs in the range 80 to FF are represented by byte values -128 to -1.

Returns:
The default hexadecimal value as an array of bytes or an empty array if the extended data element has no default hexadecimal value or if its type is not hexBinary. This method never returns null.

setDefaultValues

public void setDefaultValues(java.lang.String[] values)
                      throws ArgumentNotValidException,
                             OperationNotValidException,
                             ValueTooLongException
Sets the values to be the defaults for the extended data element. If the element has a singled-valued type (for example, short), only one value can be set. If the element has a multi-valued type (for example, stringArray), any number of values can be set. If the element's type is noValue, no values can be set. If the element's type is hexBinary, this method is not appropriate. Use setDefaultHexValue(byte[]) method instead.

The values are supplied as strings. The using application must ensure that the values represented by the strings are valid for the extended data element's type. For example, if the type is float, it is not appropriate to supply the value "apple".

Parameters:
values - An array of the values to set. Specifying null or an empty array clears any values that were previously set.
Throws:
ArgumentNotValidException - If the number of values given is not appropriate for the type of the extended data element or if any value is null or empty.
OperationNotValidException - If the extended data element's type is hexBinary.
ValueTooLongException - If any value is too long. The maximum length is set by the Common Base Event Specification at 1024 characters.

getDefaultValues

public java.lang.String[] getDefaultValues()
Returns the values set as the defaults for the extended data element. If the element has a single valued type (for example, short), the return array contains only one value. If the element has a multi-valued type (for example, stringArray), the return array can contain any number of values. If the element's type is noValue or hexBinary, the return array is empty.

The values are returned as strings. The using application must convert the values as necessary to the type defined for the extended data element.

Returns:
An array of default values or an empty array if the extended data element has no default values or its type is noValue or hexBinary. This method never returns null.

setMaxOccurs

public void setMaxOccurs(int maxOccurs)
                  throws ArgumentNotValidException
Sets the maximum number of times the extended data element must occur. The default is one.

Parameters:
maxOccurs - The number to set. It must be a non-negative integer greater than or equal to the corresponding minimum (see setMinOccurs(int)). Use the value java.lang.Integer.MAX_VALUE to indicate no upper limit ("unbounded" in XML terminology).
Throws:
ArgumentNotValidException - If maxOccurs is not valid.

getMaxOccurs

public int getMaxOccurs()
Returns the maximum number of times the extended data element must occur.

Returns:
A non-negative integer. The value java.lang.Integer.MAX_VALUE indicates no upper limit ("unbounded" in XML terminology).

setMinOccurs

public void setMinOccurs(int minOccurs)
                  throws ArgumentNotValidException
Sets the minimum number of times the extended data element must occur. The default is one.

Parameters:
minOccurs - The number to set. It must be a non-negative integer less than or equal to the corresponding maximum (see setMaxOccurs(int)).
Throws:
ArgumentNotValidException - If minOccurs is not valid.

getMinOccurs

public int getMinOccurs()
Returns the minimum number of times the extended data element must occur.

Returns:
A non-negative integer.

getName

public java.lang.String getName()
Returns the name of the extended data element (the value of its name property).

Returns:
The name.

getType

public int getType()
Returns a value that indicates the type of the extended data element (the value of its type property). It is one of the integer TYPE_<type>_VALUE constants defined in the class ExtendedDataElement, for example TYPE_INT_VALUE.

Returns:
The type.

getTypeAsString

public java.lang.String getTypeAsString()
Returns the type of the extended data element (the value of its type property) as a string. Examples are int and noValue.

Returns:
The string.

addChild

public void addChild(ExtendedDataElementDescription description)
              throws ArgumentNotValidException,
                     DescriptionExistsException
Adds a description of a child extended data element.

An extended data element can contain other extended data elements nested to any depth. These are known as children and are themselves described by extended data element descriptions. This method adds a description for an immediate child of the subject extended data element.

Parameters:
description - The extended data element description to add.
Throws:
ArgumentNotValidException - If description is null.
DescriptionExistsException - If description describes an extended data element that is already a child of the subject extended data element.

equals

public boolean equals(java.lang.Object obj)
Indicates whether some other object represents the same extended data element description as this object. Two extended data element descriptions 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 child extended data element descriptions, but again order is not important. Child extended data element descriptions are themselves compared internally using this method, so two children match if their fields are equal and their children match in turn.

Parameters:
obj - The reference object to compare to.
Returns:
true if this object and the reference object represent the same extended data element description. Otherwise, false.

toString

public java.lang.String toString()
Returns a string representation of this extended data element description.

Returns:
A string.