biz.c24.io.api.data
Class ComplexDataObject

java.lang.Object
  extended by biz.c24.io.api.data.ComplexDataObject
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
DocumentRoot

public class ComplexDataObject
extends Object
implements Serializable, Cloneable

A data object constructed from other simple and complex objects manifested as elements and attributes.

The resulting structure is a hierarchy of complex objects with 'simple' leaf nodes represented by (generally) immutable value classes such as String, Integer, Boolean etc.
This class is the super class of deployed C24 Integration Objects bean classes and provides a common interface by which deployed classes can be addressed. This interface is similar to DOM in providing methods to recurse over the structure. A common recursive method using the interface would be similar to the following:

 public int countLeafNodes(ComplexDataObject obj)
 {
   int count = 0;
   for (int i=0; i<obj.getElementDeclCount(); i++) // for all the different elements present
   {
     Element e = obj.getElementDecl(i);
     for (int j=0; j<obj.getElementCount(e.getName()); j++) // for all repeats of element 'e'
     {
       Object child = obj.getElement(e.getName(), j);
       if (child instanceof ComplexDataObject)
         count += countLeafNodes((ComplexDataObject) child); // a branch node
       else
         count++; // a leaf node
     }
   }
   for (int i=0; i<obj.getAttrDeclCount(); i++) // for all the different attributes present
   {
     Attribute a = obj.getAttrDecl(i);
     if (obj.isAttrPresent(a.getName())) // if attribute 'a' is present (attributes can not repeat)
     {
       Object child = obj.getAttr(a.getName());
       count++; // attributes can not be complex data objects hence they are always leaf nodes
     }
   }
 }
 

All instances of this class have a reference to a ComplexDataType, accessible via getType(), which stores the meta-data of the data object hierarchy (ie data describing the instance data). This class also provides direct access to this meta-data via the getElementDeclCount(), getElementDecl(int), getAttrDeclCount() and getAttrDecl(int) methods. It is possible build up the data object structure 'on the fly' using the addElementDecl(Element) and addAttrDecl(Attribute) methods in which case the object's structure will differ from it's type. This is required behaviour for parsing certain XML structures, such as ANY elements, but in general is not recommended since it reduces code portability.
Instances of this class can also have an optional reference to a defining element declaration, accessible via the getDefiningElementDecl() method. Among other things this element defines the name that will be used by the root element when expressed in XML.

Warning: Serialized objects of this class or of a deployed class which is derived from it may not be compatible with future releases of C24 Integreation Objects. The current serialization support is appropriate for short term storage or RMI between applications running the same version of C24 Integreation Objects.

In particular, since version 3.6, serialisation of validation listeners and validation mechanism is no longer supported. These settings are now considered part of the ValidationManager and should be treated as such.

See Also:
ComplexDataType, Element, Attribute, Serialized Form

Constructor Summary
ComplexDataObject()
          Constructs a new empty instance.
ComplexDataObject(ComplexDataObject clone)
          Constructs a new instance cloned from clone.
ComplexDataObject(Element definingElementDecl)
          Constructs a new instance defined by the specified element.
ComplexDataObject(Element definingElementDecl, ComplexDataType type)
          Constructs a new instance defined by the specified element but with the specified type.
 
Method Summary
 void addAttrDecl(Attribute attr)
          Adds a meta-data attribute declaration to this object.
 void addAttrDecl(Attribute attr, int index)
          Adds a meta-data attribute declaration to this object at the specified index.
 void addComment(String comment)
          Adds a comment.
 void addElement(String name, Object value)
          Adds value as an instance of the element called name.
 void addElementDecl(Element element)
          Adds a meta-data element declaration to this object.
 void addElementDecl(Element element, int index)
          Adds a meta-data element declaration to this object at the specified index.
 void addNamespaceMapping(NamespaceMapping nm)
          Adds a namespace mapping - a mapping from a prefix to a namespace URI.
 void addValidationListener(ValidationListener listener)
          Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.
 void clear()
          Clears all data from this object.
 void clearAttrs(String name)
          Removes all attributes called name.
 void clearClientProperties()
          Clears all client properties.
 void clearContent()
          Clears the content from this object recursivley.
 void clearElements(String name)
          Removes all instances of the element called name.
 Iterator clientPropertyKeysIterator()
          Returns an iterator over the keys of the client properties.
 Object clone()
           
 ComplexDataObject cloneDeep()
          Returns a deep clone of this object.
 boolean containsAttrDecl(String name)
          Returns whether this object contains a meta-data attribute declaration called name.
 boolean containsChild(DataComponent child)
          Returns whether this object contains an element or attribute child.
 boolean containsElementDecl(String name)
          Returns whether this object contains an element declaration called name.
 Object createContentObject()
          Creates and sets an object as the content of this object.
 boolean equalContents(ComplexDataObject obj, boolean deep, boolean checkContent, boolean checkAttributes, boolean checkElements)
          Checks whether the data contained in obj is equal to the data contained in this object.
 boolean equals(Object obj)
           
 ValidationMechanismEnum getActualValidationMechanism()
          Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.
 Object getAttr(String name)
          Returns the instance of the attribute called name.
 Attribute getAttrDecl(int index)
          Returns the meta-data attribute declaration at index.
 Attribute getAttrDecl(String name)
          Returns the meta-data attribute declaration called name.
 int getAttrDeclCount()
          Returns the number of different meta-data attribute declarations held by this object.
 int getAttrDeclIndex(Attribute attr)
          Returns the index of the specified meta-data attribute declaration.
 Object getChild(DataComponent child, int index)
          Returns the instance at index of the element or attribute child.
 int getChildCount(DataComponent child)
          Returns the number of instances of the element or attribute child.
 int getChildDeclIndex(DataComponent child)
          Returns the index of the element or attribute child declaration.
 int getChildIndex(DataComponent child, Object value)
          Returns the index of value of the element or attribute child.
 Object getClientProperty(Object key)
          Returns the value of the property with the specified key.
 String getComment(int index)
          Returns the comment at index.
 int getCommentCount()
          Returns the number of comments held by this object.
 Object getContent()
          Returns the content of this object.
 Element getDefiningElementDecl()
          Returns the meta-data element declaration that defines this object.
 DocumentRoot getDocumentRoot()
          Returns the document root of this object hierarchy if one is present.
 Object getElement(String name)
          Returns the 1st instance of the element called name.
 Object getElement(String name, int index)
          Returns the instance at index of the element called name.
 int getElementCount(String name)
          Returns the number of instances of the element called name.
 Element getElementDecl(int index)
          Returns the meta-data element declaration at index.
 Element getElementDecl(String name)
          Returns the meta-dataelement declaration called name.
 Element getElementDecl(String name, int index)
          Returns the meta-data element declaration called name at index.
 int getElementDeclCount()
          Returns the number of meta-data different element declarations held by this object.
 int getElementDeclIndex(Element element)
          Returns the index of the specified meta-data element declaration.
 int getElementIndex(String name, Object value)
          Returns the index of value of the element called name.
 Object[] getElements(String name)
          Returns a new array containing all of the elements called name.
 int getIdKey()
          Returns the database primary key.
 Logger getLog()
          Returns the static singleton log4j Logger used to log messages for this object.
 String getMixedContent(int index)
          Returns the item of mixed content at index.
 int getMixedContentCount()
          Returns the number of mixed content items.
 DataModel getModel()
          Returns the model (the root of the meta-data) which defines this object.
 String getName()
          Returns the name of this object which will be taken from the defining element declaration.
 NamespaceMapping getNamespaceMapping(int index)
          Return the namespace mapping at index.
 int getNamespaceMappingCount()
          Returns the number of namespace mappings present in this object.
 NamespaceMapping getNamespaceMappingForPrefix(String prefix, boolean deep)
          Return the namespace mapping for prefix.
 NamespaceMapping getNamespaceMappingForUri(String uri, boolean deep)
          Return the namespace mapping for uri.
 NamespaceMapping[] getNamespaceMappings()
          Returns a newly created array of the namespace mappings held by this object.
 ComplexDataObject getParent()
          Returns the object containing this object or null if this object is the root of the object hierarchy.
 String getProcessingInstruction(String target)
          Returns the value of the processing instruction with the specified target.
 String getQualifiedName()
          Returns a '/' separated path from this node to the root of the object hierarchy.
 ComplexDataObject getRoot()
          Returns the root of this object hierarchy.
 String getSubstitute(String name)
          Gets the name of the element that was substitued by the name.
protected  String getTargetNamespace()
           
 int getTotalAttrCount()
          Returns the total number of attribute instances that this object contains.
 int getTotalElementCount()
          Returns the total number of element instances that this object contains.
 ComplexDataType getType()
          Returns the meta-data type that defines this object.
 ValidationListener[] getValidationListeners()
          Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.
 ValidationMechanismEnum getValidationMechanism()
          Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.
 int hashCode()
           
 void initAttrsFromType(boolean clear)
          Deprecated.  
 void initElementsFromType(boolean clear)
          Deprecated.  
 void initToMinCardinality()
          Initializes this object recursively so that there are at least the minimum cardinality of all required elements and attributes.
 boolean isAttrPresent(String name)
          Returns whether an attribute instance called name is present.
 boolean isContentAllowed()
          Returns whether the meta-data defines this object as containg simple content.
 boolean isMixedContentAllowed()
          Returns whether the meta-data defines this object as containing mixed content.
 boolean isRoot()
          Returns whether this node is the root of the object hierarhcy.
 Object locateAncestorOfType(DataType type)
          Locates an ancestor of this object with the specified type.
protected  String makeSubstitution(String name, int index)
          Called by deployed subclasses to substitute an element.
 Iterator processingInstructionTargetsIterator()
          Returns an iterator over the targets of the processing instructions.
 void putClientProperty(Object key, Object value)
          Stores the client property with the specified key and value.
 void putProcessingInstruction(String target, String value)
          Stores the processing instruction with the specified target and value.
 void removeAttr(String name)
          Removes the instance at position index of the attribute called name.
 void removeClientProperty(Object key)
          Removes the client property with the specified key value.
 void removeComment(String comment)
          Removes a comment.
 void removeElement(String name, int index)
          Removes the instance at position index of the element called name.
 void removeElements(String name)
          Removes all the instance of the element called name.
 void removeNamespaceMapping(NamespaceMapping nm)
          Removes the specfied namespace mapping.
 void removeProcessingInstruction(String target)
          Removes the processing instruction with the specified target.
 void removeValidationListener(ValidationListener listener)
          Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.
 void setAttr(String name, Object value)
          Sets value as the instance of the attribute called name.
 void setChild(DataComponent child, int index, Object value)
          Sets the instance at index of the element or attribute child.
 void setComment(String comment, int index)
          Sets the comment at index.
 void setContent(Object content)
          Sets the content of this object.
 void setDefiningElementDecl(Element definingElementDecl)
          Sets the meta-data element declaration that defines this object.
 void setDefiningElementDecl(Element definingElementDecl, ComplexDataType type)
          Sets the meta-data element declaration that defines this object but with the specified type.
 void setElement(String name, int index, Object value)
          Sets value as the instance (in position index) of the element called name.
 void setElements(String name, Object[] values)
          Clears any instances of the element called name and adds the contents of values in their place.
 void setIdKey(int idKey)
          Sets the database primary key.
 void setMixedContent(String mixedContent, int index)
          Sets the mixed content item at index.
 void setName(String name)
          Sets the name of this object on the defining element declaration.
 void setNamespaceMapping(NamespaceMapping nm, int index)
          Sets the namespace mapping at index.
 void setOrder(int originalIndex, int newIndex)
          Changes the order of this objects elements (applies only when ContentModelEnum.ALL is used by this object's type).
 void setParent(ComplexDataObject parent)
          Sets the parent of this object.
 void setParent(ComplexDataObject parent, String elementDeclName)
          Sets the parent and possibly changes the defining element declaration of this object to one contained by the specfied parent.
 void setType(ComplexDataType type)
          Internal method to set the meta-data type that defines this object.
 void setValidationMechanism(ValidationMechanismEnum validationMechanism)
          Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.
 String toAttrNamesString()
          Returns a string containing the names of the attribute declarations in this object.
 String toElementNamesString()
          Returns a string containing the names of the element declarations in this object.
 String toString()
          Creates a String representation of this object using the models sink.
protected  String unmakeSubstitution(String name, int index)
          Called by subclasses to unmake a substitution and return an elements type to the type of its substitution group head element.
 boolean validate()
          Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.
 boolean validate(ValidationConstraints constraints)
          Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ComplexDataObject

public ComplexDataObject()
Constructs a new empty instance.

This contructor is supplied for bean style instantiation, for safety reasons either ComplexDataObject(Element) or ComplexDataObject(Element, ComplexDataType) should be preferred.

Instances created via this constructor must be initialized by calling either setDefiningElementDecl(Element) or setDefiningElementDecl(Element, ComplexDataType) before any other methods are called. Failure to do so may result in unpredicitable behaviour and unchecked exceptions.


ComplexDataObject

public ComplexDataObject(Element definingElementDecl)
Constructs a new instance defined by the specified element.

Parameters:
definingElementDecl - The element defining the new object.
Throws:
NullPointerException - If definingElementDecl == null.
IllegalArgumentException - If definingElementDecl is abstract.
IllegalArgumentException - If the type of definingElementDecl is not complex.
IllegalArgumentException - If the type of definingElementDecl is abstract.
IllegalArgumentException - If this is not a valid class of the type of definingElementDecl.

ComplexDataObject

public ComplexDataObject(Element definingElementDecl,
                         ComplexDataType type)
Constructs a new instance defined by the specified element but with the specified type.

This constructor should be used to create object representations of substituted elements.

Parameters:
definingElementDecl - The element defining the new object.
type - The type of the object.
Throws:
IllegalArgumentException - If definingElementDecl is abstract.
IllegalArgumentException - If type == null and the type of definingElementDecl is not complex.
IllegalArgumentException - If type or the type of definingElementDecl is abstract.
IllegalArgumentException - If this is not a valid class of the type or the type of definingElementDecl.

ComplexDataObject

public ComplexDataObject(ComplexDataObject clone)
Constructs a new instance cloned from clone.

This method performs a shallow clone - i.e. the resulting object will contain the same objects as the argument. To perform a deep clone use the cloneDeep() method instead.

Parameters:
clone - The object to clone.
See Also:
cloneDeep()
Method Detail

initToMinCardinality

public void initToMinCardinality()
Initializes this object recursively so that there are at least the minimum cardinality of all required elements and attributes.
If there is no namespace declaration and one is required (i.e. this is the root object or this objects parent is from a different namespace to this object) then a default namespace mapping will be created using the empty prefix.
Note: calling this method is not guaranteed to result in a valid object. Specifically, the majority of constraining facets are ignored as are the content of validation rules.


getModel

public DataModel getModel()
Returns the model (the root of the meta-data) which defines this object.

The model is a deployed version of the origianl .dod file and is therefore analogous to an XML schema.

Returns:
The model which may have been set directly but will most likely be taken from the defining element declaration.

getType

public final ComplexDataType getType()
Returns the meta-data type that defines this object.

The returned type will be different from the type of the defining element declaraction if this object uses a derived type - in XML this is modelled as an xsi:type.

Returns:
The type, usually taken from the defining element declaration

setType

public void setType(ComplexDataType type)
Internal method to set the meta-data type that defines this object.

This method is provided for use immediatley after instantiation via the ComplexDataObject() constructor.

Any further calls to this method will result in an IllegalStateException being thrown

Parameters:
type - The new type.
Throws:
IllegalStateException - If the new type of this object is not derived from the old type.

getDefiningElementDecl

public Element getDefiningElementDecl()
Returns the meta-data element declaration that defines this object.

Returns:
The element.

setDefiningElementDecl

public void setDefiningElementDecl(Element definingElementDecl)
Sets the meta-data element declaration that defines this object.

This method is provided for use immediatley after instantiation via the ComplexDataObject() constructor.

Any further calls to this method may result in unpredicitable behaviour and unchecked exceptions

Parameters:
definingElementDecl - The new element.
Throws:
NullPointerException - If definingElementDecl == null.
IllegalArgumentException - If definingElementDecl is abstract.
IllegalArgumentException - If type == null and the type of definingElementDecl is not complex.
IllegalArgumentException - If type or the type of definingElementDecl is abstract.
IllegalArgumentException - If this is not a valid class of the type or the type of definingElementDecl.

setDefiningElementDecl

public void setDefiningElementDecl(Element definingElementDecl,
                                   ComplexDataType type)
Sets the meta-data element declaration that defines this object but with the specified type.

This method should be used to create object representations of substituted elements.
This method is provided for use immediatley after instantiation via the ComplexDataObject() constructor.

Any further calls to this method may result in unpredicitable behaviour and unchecked exceptions

Parameters:
definingElementDecl - The new element.
type - The type.
Throws:
NullPointerException - If definingElementDecl == null.
IllegalArgumentException - If definingElementDecl is abstract.
IllegalArgumentException - If type == null and the type of definingElementDecl is not complex.
IllegalArgumentException - If type or the type of definingElementDecl is abstract.
IllegalArgumentException - If this is not a valid class of the type or the type of definingElementDecl.

isMixedContentAllowed

public boolean isMixedContentAllowed()
Returns whether the meta-data defines this object as containing mixed content.

Returns:
Whether mixed content is allowed.

getMixedContent

public String getMixedContent(int index)
Returns the item of mixed content at index.

Index 0 will return the mixed content before the first element, index 1 will return the mixed content between the first and second etc. It is therefore always possible for there to be one more item of mixed content than there are element values present in the object.

Parameters:
index - The index of the mixed content to return.
Returns:
The mixed content at index.
Throws:
IllegalArgumentException - if this object is not allowed mixed content, i.e. isMixedContentAllowed() returns false.
IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= getMixedContentCount()).

getMixedContentCount

public int getMixedContentCount()
Returns the number of mixed content items.

Returns:
The number of mixed content items.
Throws:
IllegalArgumentException - if this object is not allowed mixed content, i.e. isMixedContentAllowed() returns false.

setMixedContent

public void setMixedContent(String mixedContent,
                            int index)
Sets the mixed content item at index.

Parameters:
mixedContent - The new value.
index - The index to set.
Throws:
IllegalArgumentException - if this object is not allowed mixed content, i.e. isMixedContentAllowed() returns false.
IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= getMixedContentCount()).
See Also:
getMixedContent(int)

isContentAllowed

public boolean isContentAllowed()
Returns whether the meta-data defines this object as containg simple content.

This will return true if this object's type had a simple base type.

Returns:
Whether simple content is allowed.

getContent

public Object getContent()
Returns the content of this object.

Returns:
The content.
Throws:
IllegalArgumentException - if this object is not allowed content, i.e. isContentAllowed() returns false.

setContent

public void setContent(Object content)
Sets the content of this object.

The class of content should be compatible with the simple base type of this object's type.

Parameters:
content - The new value.
Throws:
IllegalArgumentException - if this object is not allowed content, i.e. isContentAllowed() returns false.

createContentObject

public Object createContentObject()
Creates and sets an object as the content of this object.

Returns:
The new content object.

setOrder

public void setOrder(int originalIndex,
                     int newIndex)
Changes the order of this objects elements (applies only when ContentModelEnum.ALL is used by this object's type).

This method can be used to control the order in which the elements of an 'ALL' group are formatted. If this object has been located as the 'ordering object' of another complex data object then rearranging the elements via this method will cause the other complex data objects elements to be rearranged as well.

Parameters:
originalIndex - The index of the element to be moved.
newIndex - The index to move to.

getSubstitute

public String getSubstitute(String name)
Gets the name of the element that was substitued by the name.

Parameters:
name - The substitues name.
Returns:
The name of the substituted element.

makeSubstitution

protected String makeSubstitution(String name,
                                  int index)
Called by deployed subclasses to substitute an element.

Parameters:
name - The name to substitute.
index - The index of the substitute.
Returns:
The name of the substitute.
Throws:
IllegalArgumentException - If no valid substitute called name could be found.

unmakeSubstitution

protected String unmakeSubstitution(String name,
                                    int index)
Called by subclasses to unmake a substitution and return an elements type to the type of its substitution group head element.

Parameters:
name - The name of the substituted element.
index - The index of the substitute.
Returns:
The original name

initElementsFromType

public void initElementsFromType(boolean clear)
Deprecated. 

Re-initialises this objects meta-data element declarations from the type.

Note: this method should be called when ad-hoc elements have been added to the type and they are need to be reproduced in this object.

Parameters:
clear - Whether to first clear any current element declarations set up in this object.

addElementDecl

public void addElementDecl(Element element)
Adds a meta-data element declaration to this object.

Note: this method should only be called when ad-hoc elements need to be added to an object. In general to provide greater portability, the elements should be added in the Designer and the model redeployed.

Parameters:
element - The new element.
Throws:
IllegalArgumentException - If an element with the same name is already present.

addElementDecl

public void addElementDecl(Element element,
                           int index)
Adds a meta-data element declaration to this object at the specified index.

Note: this method should only be called when ad-hoc elements need to be added to an object. In general to provide greater portability, the elements should be added in the Designer and the model redeployed.

Parameters:
element - The new element.
index - The index at which the element should be added.
Throws:
IllegalArgumentException - If an element with the same name is already present.

getElementDeclCount

public final int getElementDeclCount()
Returns the number of meta-data different element declarations held by this object.

Returns:
The number of elements.

getElementDecl

public Element getElementDecl(int index)
Returns the meta-data element declaration at index.

Parameters:
index - The index of the element to return.
Returns:
The element.

getElementDecl

public Element getElementDecl(String name,
                              int index)
Returns the meta-data element declaration called name at index. This method may return different elements for different indicies if substitution groups have been applied.

Parameters:
name - The name of the element.
index - The index in the array of substituted elements.
Returns:
The element.

getElementDecl

public Element getElementDecl(String name)
Returns the meta-dataelement declaration called name.

Parameters:
name - The name of the element.
Returns:
The element.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

getElementDeclIndex

public int getElementDeclIndex(Element element)
Returns the index of the specified meta-data element declaration.

Parameters:
element - The element declaration.
Returns:
The index, or -1 if it does not exist within this object.

containsElementDecl

public boolean containsElementDecl(String name)
Returns whether this object contains an element declaration called name.

Parameters:
name - The name of the element.
Returns:
Whether an element called name exsits.

getElementCount

public int getElementCount(String name)
Returns the number of instances of the element called name.

Parameters:
name - The name of the element.
Returns:
The number of occurances.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

getElement

public Object getElement(String name,
                         int index)
Returns the instance at index of the element called name.

Parameters:
name - The name of the element.
index - The index to return.
Returns:
The object.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

getElements

public Object[] getElements(String name)
Returns a new array containing all of the elements called name.

The arrays runtime type will be taken from the element.

Parameters:
name - The name of the element.
Returns:
The new array.

getElementIndex

public int getElementIndex(String name,
                           Object value)
Returns the index of value of the element called name.

Parameters:
name - The name of the element.
value - The object whose index is to be returned.
Returns:
The index.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

addElement

public void addElement(String name,
                       Object value)
Adds value as an instance of the element called name.

Parameters:
name - The name of the element.
value - The new object.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

setElement

public void setElement(String name,
                       int index,
                       Object value)
Sets value as the instance (in position index) of the element called name.

Parameters:
name - The name of the element.
index - The index of the instance to set.
value - The new object.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

setElements

public void setElements(String name,
                        Object[] values)
Clears any instances of the element called name and adds the contents of values in their place.

Parameters:
name - The name of the element.
values - The new objects, or null if this field is to be cleared.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

removeElement

public void removeElement(String name,
                          int index)
Removes the instance at position index of the element called name.

Parameters:
name - The name of the element.
index - The index of the instance to remove.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

removeElements

public void removeElements(String name)
Removes all the instance of the element called name.

Parameters:
name - The name of the element.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

getElement

public Object getElement(String name)
Returns the 1st instance of the element called name. This method is a shortcut to calling getElement(String, int).

Parameters:
name - The name of the element.
Returns:
The object.
Throws:
IllegalArgumentException - If name is not recognised as the name of an element.

getTotalElementCount

public int getTotalElementCount()
Returns the total number of element instances that this object contains.

Returns:
The count.

clearElements

public void clearElements(String name)
Removes all instances of the element called name.

Parameters:
name - The name of the element to clear.

initAttrsFromType

public void initAttrsFromType(boolean clear)
Deprecated. 

Re-initialises this objects meta-data attribute declarations from the type.

Note: this method should be called when ad-hoc attributes have been added to the type and they are need to be reproduced in this object.

Parameters:
clear - Whether to first clear any current attribute declarations set up in this object.

addAttrDecl

public void addAttrDecl(Attribute attr)
Adds a meta-data attribute declaration to this object.

Note: this method should only be called when ad-hoc attributes need to be added to an object. In general to provide greater portability, the attributes should be added in the Designer and the model redeployed.

Parameters:
attr - The new attribute.
Throws:
IllegalArgumentException - If an attribute with the same name is already present.

addAttrDecl

public void addAttrDecl(Attribute attr,
                        int index)
Adds a meta-data attribute declaration to this object at the specified index.

Note: this method should only be called when ad-hoc attributes need to be added to an object. In general to provide greater portability, the attributes should be added in the Designer and the model redeployed.

Parameters:
attr - The new attribute.
index - The index at which the attribute should be added.
Throws:
IllegalArgumentException - If an attribute with the same name is already present.

getAttrDeclCount

public int getAttrDeclCount()
Returns the number of different meta-data attribute declarations held by this object.

Returns:
The number of attributes.

getAttrDecl

public Attribute getAttrDecl(int index)
Returns the meta-data attribute declaration at index.

Parameters:
index - The index of the attribute to return.
Returns:
The element.

getAttrDecl

public Attribute getAttrDecl(String name)
Returns the meta-data attribute declaration called name.

Parameters:
name - The name of the attribute.
Returns:
The attribute.
Throws:
IllegalArgumentException - If name is not recognised as the name of an attribute.

getAttrDeclIndex

public int getAttrDeclIndex(Attribute attr)
Returns the index of the specified meta-data attribute declaration.

Parameters:
attr - The attribute declaration.
Returns:
The index, or -1 if it does not exist within this object.

containsAttrDecl

public boolean containsAttrDecl(String name)
Returns whether this object contains a meta-data attribute declaration called name.

Parameters:
name - The name of the attribute.
Returns:
Whether an attribute called name exsits.

isAttrPresent

public boolean isAttrPresent(String name)
Returns whether an attribute instance called name is present.

Parameters:
name - The name of the attribute.
Returns:
Whether it is present.
Throws:
IllegalArgumentException - If name is not recognised as the name of an attribute.

getAttr

public Object getAttr(String name)
Returns the instance of the attribute called name.

Parameters:
name - The name of the attribute.
Returns:
The object.
Throws:
IllegalArgumentException - If name is not recognised as the name of an attribute.

setAttr

public void setAttr(String name,
                    Object value)
Sets value as the instance of the attribute called name.

Parameters:
name - The name of the attribute.
value - The new object.
Throws:
IllegalArgumentException - If name is not recognised as the name of an attribute.

removeAttr

public void removeAttr(String name)
Removes the instance at position index of the attribute called name.

Parameters:
name - The name of the attribute.
Throws:
IllegalArgumentException - If name is not recognised as the name of an attribute.

getTotalAttrCount

public int getTotalAttrCount()
Returns the total number of attribute instances that this object contains.

Returns:
The count.

clearAttrs

public void clearAttrs(String name)
Removes all attributes called name.

Parameters:
name - The name of the attributes to remove.

containsChild

public boolean containsChild(DataComponent child)
Returns whether this object contains an element or attribute child.

Parameters:
child - The element or attribute.
Returns:
Whether it is present.

setChild

public void setChild(DataComponent child,
                     int index,
                     Object value)
Sets the instance at index of the element or attribute child.

Parameters:
child - The element or attribute.
index - The index to return.
value - The value to set.
Throws:
IllegalArgumentException - If child is not recognised as an element or attribute in this object.

getChild

public Object getChild(DataComponent child,
                       int index)
Returns the instance at index of the element or attribute child.

Parameters:
child - The element or attribute.
index - The index to return.
Returns:
The object.
Throws:
IllegalArgumentException - If child is not recognised as an element or attribute in this object.

getChildCount

public int getChildCount(DataComponent child)
Returns the number of instances of the element or attribute child.

Parameters:
child - The element or attribute.
Returns:
The number of occurances.
Throws:
IllegalArgumentException - If child is not recognised as an element or attribute in this object.

getChildIndex

public int getChildIndex(DataComponent child,
                         Object value)
Returns the index of value of the element or attribute child.

Parameters:
child - The element or attribute.
value - The object whose index is to be returned.
Returns:
The index.
Throws:
IllegalArgumentException - If child is not recognised as an element or attribute in this object.

getChildDeclIndex

public int getChildDeclIndex(DataComponent child)
Returns the index of the element or attribute child declaration.

Parameters:
child - The element or attribute.
Returns:
The index.
Throws:
IllegalArgumentException - If child is not recognised as an element or attribute in this object.

clear

public void clear()
Clears all data from this object.


clearContent

public void clearContent()
Clears the content from this object recursivley.

This method removes all atomic data from the object, leaving an empty 'shell' of nested complex objects.


clone

public Object clone()
Overrides:
clone in class Object

cloneDeep

public ComplexDataObject cloneDeep()
                            throws CloneNotSupportedException
Returns a deep clone of this object.

Returns:
The clone.
Throws:
CloneNotSupportedException - If the profile used to deploy the bean classed had it's "Generate Deep Clone Methods" property disabled.

getName

public String getName()
Returns the name of this object which will be taken from the defining element declaration.

Returns:
The name of this object.

setName

public void setName(String name)
Sets the name of this object on the defining element declaration.

Parameters:
name - The new name.

getQualifiedName

public String getQualifiedName()
Returns a '/' separated path from this node to the root of the object hierarchy.

Returns:
The qualified name of this object.

getLog

public final Logger getLog()
Returns the static singleton log4j Logger used to log messages for this object.

The log returned will be retrieved from and named after the root object.
Care should be taken not to add log4j appenders to the returned Logger object from within a loop since they will never be garbage collected. Since the returned Logger is a static singleton, well written code should leave the Logger in the exact same state they found it. Better still, all Logger configuration should be done via log4j.properties files or static intializers/

Returns:
The logging object.

getRoot

public ComplexDataObject getRoot()
Returns the root of this object hierarchy.

This will be the ancestor for which getParent() == null.

Returns:
The root.

getDocumentRoot

public DocumentRoot getDocumentRoot()
Returns the document root of this object hierarchy if one is present.

This will be the ancestor for which getParent() instanceof DocumentRoot.

Returns:
The document root or null if this object hierarchy is not rooted within one.

isRoot

public boolean isRoot()
Returns whether this node is the root of the object hierarhcy.

This will be where getParent() == null.

Returns:
Whether this is the root.

getParent

public ComplexDataObject getParent()
Returns the object containing this object or null if this object is the root of the object hierarchy.

Returns:
The parent if one exists, null otherwise.

setParent

public void setParent(ComplexDataObject parent)
Sets the parent of this object.

This method should not generally be called directly since the parent child relationships are automatically assigned when adding complex objects as elements to a parent.

Parameters:
parent - The parent, or null to break any existing relationship.
See Also:
setParent(ComplexDataObject, String)

setParent

public void setParent(ComplexDataObject parent,
                      String elementDeclName)
Sets the parent and possibly changes the defining element declaration of this object to one contained by the specfied parent.

This method should not generally be called directly since the parent child relationships are automatically assigned when adding complex objects as elements to a parent.

Parameters:
parent - The parent, or null to break any existing relationship.
elementDeclName - The name of the defining element declaration of this object or null if it is not to be changed.
See Also:
setParent(ComplexDataObject)

locateAncestorOfType

public Object locateAncestorOfType(DataType type)
Locates an ancestor of this object with the specified type.

Parameters:
type - The type of the ancestor to be located.
Returns:
The ancestor if one was found or null otherwise.

validate

public boolean validate()
                 throws ValidationException
Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.

Validates this object and all objects contained within it. This method calls validate(ValidationConstraints) with a new ValidationConstraints object.

Returns:
true if the validation was successful.
Throws:
ValidationException - if the the validation fails and the validation mechanism is ValidationMechanismEnum.VALIDATION_MECHANISM_EXCEPTION.

validate

public boolean validate(ValidationConstraints constraints)
                 throws ValidationException
Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.

Validates this object according to the supplied constraints.

Parameters:
constraints - The validation constraints.
Returns:
true is the validation was successful.
Throws:
ValidationException - if the the validation fails and the validation mechanism is ValidationMechanismEnum.VALIDATION_MECHANISM_EXCEPTION.

setValidationMechanism

public void setValidationMechanism(ValidationMechanismEnum validationMechanism)
Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.

Sets the validation mechanism which will be used for this object.

If validationMechanism = ValidationMechanismEnum.VALIDATION_MECHANISM_PARENT then this object's parent will be used to determine the validation mechanism. Note: if this node is the root then ValidationMechanismEnum.VALIDATION_MECHANISM_EXCEPTION will be used by default. If validationMechanism = ValidationMechanismEnum.VALIDATION_MECHANISM_EXCEPTION then ValidationExceptions will be thrown. If validationMechanism = ValidationMechanismEnum.VALIDATION_MECHANISM_SYNCHRONOUS_EVENT then synchronous ValidationEvents will be created. If validationMechanism = ValidationMechanismEnum.VALIDATION_MECHANISM_ASYNCHRONOUS_EVENT then asynchronous ValidationEvents will be created.
Note: when this property is changed any elements and attributes of this object (recursively) whose respective validation mechanism properties are set to ValidationMechanismEnum.VALIDATION_MECHANISM_PARENT will use the new value as well.

Parameters:
validationMechanism - The validation mechanism to use.
Throws:
NullPointerException - If validationMechanism is null.

getValidationMechanism

public ValidationMechanismEnum getValidationMechanism()
Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.

Returns the validation mechanism used by this object.

If the result of getActualValidationMechanism() is ValidationMechanismEnum.VALIDATION_MECHANISM_PARENT this method will return the validation mechanism of its parent (unless it is the root in which case it will default to ValidationMechanismEnum.VALIDATION_MECHANISM_EXCEPTION. Therefore exception processing is the default validation mechanism.

Returns:
The validation mechanism to use (one of ValidationMechanismEnum.VALIDATION_MECHANISM_EXCEPTION, ValidationMechanismEnum.VALIDATION_MECHANISM_SYNCHRONOUS_EVENT or ValidationMechanismEnum.VALIDATION_MECHANISM_ASYNCHRONOUS_EVENT).

getActualValidationMechanism

public ValidationMechanismEnum getActualValidationMechanism()
Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.

Returns the ACTUAL validation mechanism which has been set on this object. This method will return the validation mechanism bean property. It therefore differs from getValidationMechanism() because it will not defer calls to its parent.

Returns:
The actual validation mechanism setting (one of ValidationMechanismEnum.VALIDATION_MECHANISM_EXCEPTION, ValidationMechanismEnum.VALIDATION_MECHANISM_SYNCHRONOUS_EVENT, ValidationMechanismEnum.VALIDATION_MECHANISM_ASYNCHRONOUS_EVENT or ValidationMechanismEnum.VALIDATION_MECHANISM_PARENT).

addValidationListener

public void addValidationListener(ValidationListener listener)
Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.

Adds a validation listener to be notified of validation events. Note: getValidationMechanism() must return either ValidationMechanismEnum.VALIDATION_MECHANISM_SYNCHRONOUS_EVENT or ValidationMechanismEnum.VALIDATION_MECHANISM_ASYNCHRONOUS_EVENT for events to be propagated to listeners.

Parameters:
listener - The validation listener to be added.

removeValidationListener

public void removeValidationListener(ValidationListener listener)
Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.

Removes a validation listener.

Parameters:
listener - The validation listener to be removed.

getValidationListeners

public ValidationListener[] getValidationListeners()
Deprecated. Use ValidationManager instead - this method will be removed in the next major version release.

Returns the validation listeners added to this object.

Returns:
The validation listeners.

toString

public String toString()
Creates a String representation of this object using the models sink.

The format of the returned string representation can be customized by changing the "Output Mask" property on the associated data model in the Designer and redeploying the code.

Overrides:
toString in class Object
Returns:
The String representation.

getClientProperty

public Object getClientProperty(Object key)
Returns the value of the property with the specified key.

Parameters:
key - The key being queried/
Returns:
The value of this property or null if none exists.
See Also:
putClientProperty(java.lang.Object, java.lang.Object)

clientPropertyKeysIterator

public Iterator clientPropertyKeysIterator()
Returns an iterator over the keys of the client properties. The types of the iterators elements will depend entirely on what client properties have been set via putClientProperty(java.lang.Object, java.lang.Object).

Returns:
The iterator.

putClientProperty

public void putClientProperty(Object key,
                              Object value)
Stores the client property with the specified key and value.

Parameters:
key - The key.
value - The value.

removeClientProperty

public void removeClientProperty(Object key)
Removes the client property with the specified key value.

Parameters:
key - The key to remove.

clearClientProperties

public void clearClientProperties()
Clears all client properties.


getTargetNamespace

protected String getTargetNamespace()

addNamespaceMapping

public void addNamespaceMapping(NamespaceMapping nm)
Adds a namespace mapping - a mapping from a prefix to a namespace URI.

Parameters:
nm - The new namespace mapping.
Throws:
NullPointerException - If nm == null.

setNamespaceMapping

public void setNamespaceMapping(NamespaceMapping nm,
                                int index)
Sets the namespace mapping at index.

Parameters:
nm - The new namespace mapping.
index - The index.
Throws:
NullPointerException - If nm == null.
IndexOutOfBoundsException - If index > getNamespaceMappingCount()

removeNamespaceMapping

public void removeNamespaceMapping(NamespaceMapping nm)
Removes the specfied namespace mapping.

Parameters:
nm - The namespace mapping to remove.
Throws:
NullPointerException - If nm == null.

getNamespaceMappingCount

public int getNamespaceMappingCount()
Returns the number of namespace mappings present in this object.

Returns:
The count.

getNamespaceMapping

public NamespaceMapping getNamespaceMapping(int index)
Return the namespace mapping at index.

Parameters:
index - The index of the namespace mapping to return.
Returns:
The mapping.
Throws:
IndexOutOfBoundsException - If index > getNamespaceMappingCount()

getNamespaceMappings

public NamespaceMapping[] getNamespaceMappings()
Returns a newly created array of the namespace mappings held by this object.

Returns:
The mappings.

getNamespaceMappingForUri

public NamespaceMapping getNamespaceMappingForUri(String uri,
                                                  boolean deep)
Return the namespace mapping for uri.

Parameters:
uri - The uri of the namespace mapping to return.
deep - Whether to look up the object hierarchy for a suitable mapping.
Returns:
The mapping, or null if none was found.

getNamespaceMappingForPrefix

public NamespaceMapping getNamespaceMappingForPrefix(String prefix,
                                                     boolean deep)
Return the namespace mapping for prefix.

Parameters:
prefix - The prefix of the namespace mapping to return.
deep - Whether to look up the object hierarchy for a suitable mapping.
Returns:
The mapping, or null if none was found.

getCommentCount

public int getCommentCount()
Returns the number of comments held by this object.

Returns:
The number of comments.

getComment

public String getComment(int index)
Returns the comment at index.

Parameters:
index - The index of the comment to return.
Returns:
The comment.
Throws:
IndexOutOfBoundsException - If index > getCommentCount().

setComment

public void setComment(String comment,
                       int index)
Sets the comment at index.

Parameters:
comment - The new value.
index - The index to set.
Throws:
NullPointerException - If comment is null.
IndexOutOfBoundsException - if the index is out of range (index < 0 || index >= getCommentCount()).

addComment

public void addComment(String comment)
Adds a comment.

Parameters:
comment - The new comment.
Throws:
NullPointerException - If comment is null.

removeComment

public void removeComment(String comment)
Removes a comment.

Parameters:
comment - The comment to bew removed.
Throws:
NullPointerException - If comment is null.

getProcessingInstruction

public String getProcessingInstruction(String target)
Returns the value of the processing instruction with the specified target.

Parameters:
target - The target of the processing instruction to return.
Returns:
The value of the processing instruction or null
See Also:
putProcessingInstruction(java.lang.String, java.lang.String)

processingInstructionTargetsIterator

public Iterator processingInstructionTargetsIterator()
Returns an iterator over the targets of the processing instructions. The iterators elements will all be of type String.

Returns:
The iterator.

putProcessingInstruction

public void putProcessingInstruction(String target,
                                     String value)
Stores the processing instruction with the specified target and value.

Parameters:
target - The target.
value - The value.
Throws:
NullPointerException - If target or value is null.

removeProcessingInstruction

public void removeProcessingInstruction(String target)
Removes the processing instruction with the specified target.

Parameters:
target - The target to remove.
Throws:
NullPointerException - If target is null.

hashCode

public int hashCode()
Overrides:
hashCode in class Object

equals

public boolean equals(Object obj)
Overrides:
equals in class Object

equalContents

public boolean equalContents(ComplexDataObject obj,
                             boolean deep,
                             boolean checkContent,
                             boolean checkAttributes,
                             boolean checkElements)
Checks whether the data contained in obj is equal to the data contained in this object.

Parameters:
obj - The object to query.
deep - Whether to check for equality at all levels in the hierarchy.
checkContent - Whether to check for content equality.
checkAttributes - Whether to check for attribute equality.
checkElements - Whether to check for element equality.
Returns:
Whether the data held by the objects are equal.

toElementNamesString

public String toElementNamesString()
Returns a string containing the names of the element declarations in this object.

Returns:
The string.

toAttrNamesString

public String toAttrNamesString()
Returns a string containing the names of the attribute declarations in this object.

Returns:
The string.

getIdKey

public int getIdKey()
Returns the database primary key.
WARNING: this field will be removed in a future release.

Returns:
The key.

setIdKey

public void setIdKey(int idKey)
Sets the database primary key.
WARNING: this field will be removed in a future release.

Parameters:
idKey - The key.


C24 Technologies © 2002-2012: All Rights Reserved.