Package org.eigenbase.xom

# Class ElementDef

java.lang.Object
org.eigenbase.xom.ElementDef

All Implemented Interfaces:
  `Serializable`, `Cloneable`, `NodeDef`

Direct Known Subclasses:
  `GenericDef`, `MetaDef.Any`, `MetaDef.Array`, `MetaDef.Attribute`, `MetaDef.CData`, `MetaDef.Class`, `MetaDef.Element`, `MetaDef.Import`, `MetaDef.Model`, `MetaDef.Object`, `MetaDef.Plugin`, `MetaDef.StringElement`, `ResourceDef.Code`, `ResourceDef.Property`, `ResourceDef.Resource`, `ResourceDef.ResourceBundle`, `ResourceDef.Text`, `WrapperElementDef`

public abstract class ElementDef extends Object implements NodeDef, Serializable, Cloneable
ElementDef is the base class for all element definitions. It specifies the basic interface as well as provides useful services for all elements.

See Also:
  - Serialized Form

## Constructor Summary

Constructors
Constructor
Description
`ElementDef()`

## Method Summary

Modifier and Type
Method
Description
`void`
`addChild(NodeDef child)`
`void`
`addChildren(NodeDef[] children)`
`protected Object`
`clone()`
Clone an ElementDef.
`static NodeDef`
`constructElement(DOMWrapper wrapper, Class elemClass)`
constructElement is a helper function which builds the appropriate type of ElementDef from an XML Element.
`static NodeDef`
`constructElement(DOMWrapper wrapper, Class enclosure, String prefix)`
constructElement is a helper function which builds the appropriate type of ElementDef from an XML Element.
`ElementDef`
`deepCopy()`
Public version of clone(); returns a deep copy of this ElementDef.
`String`
`diff(ElementDef other)`
The diff function compares this element against another, determining if they are exactly equal.
`protected static void`
`displayAttribute(PrintWriter out, String name, Object value, int indent)`
This convenience function displays an XML attribute value with the given attribute name at the given indentation level.
`protected static boolean`
`displayAttributeDiff(String name, Object value1, Object value2, PrintWriter out, int indent)`
This convenience function displays differences in two versions of the same XML attribute value.
`boolean`
`displayDiff(ElementDef other, PrintWriter out, int indent)`
The displayDiff function compares this element definition against another, compiling a message containing all diffs.
`protected static void`
`displayElement(PrintWriter out, String name, ElementDef value, int indent)`
This convenience function displays any ElementDef with the given parameter name at the given indentation level.
`protected static void`
`displayElementArray(PrintWriter out, String name, NodeDef[] values, int indent)`
This convenience function displays any array of ElementDef values with the given parameter name (assumed to represent an array) at the given indentation level.
`protected static boolean`
`displayElementArrayDiff(String name, NodeDef[] values1, NodeDef[] values2, PrintWriter out, int indent)`
This convenience function diffs any array of ElementDef values with the given array name.
`protected static boolean`
`displayElementDiff(String name, NodeDef value1, NodeDef value2, PrintWriter out, int indent)`
This convenience function displays differences in the values of any two ElementDefs, returning true if they match and false if not.
`protected static void`
`displayIndent(PrintWriter out, int indent)`
This function writes an indentation level to the given PrintWriter.
`protected static void`
`displayString(PrintWriter out, String name, String value, int indent)`
This convenience function displays a String value with the given parameter name at the given indentation level.
`protected static void`
`displayStringArray(PrintWriter out, String name, String[] values, int indent)`
This convenience function displays any array of String values with the given parameter name (assumed to represent an array) at the given indentation level.
`protected static boolean`
`displayStringArrayDiff(String name, String[] values1, String[] values2, PrintWriter out, int indent)`
This convenience function diffs any array of strings with the given array name.
`protected static boolean`
`displayStringDiff(String name, String value1, String value2, PrintWriter out, int indent)`
This convenience function displays differences in two versions of the same string object.
`void`
`displayXML(XMLOutput out)`
`void`
`displayXML(XMLOutput out, int indent)`
Outputs this element definition in XML to any XMLOutput.
`protected static void`
`displayXMLElement(XMLOutput out, ElementDef value)`
This convenience function displays any ElementDef in XML.
`protected static void`
`displayXMLElementArray(XMLOutput out, NodeDef[] values)`
This convenience function displays an array of ElementDef values in XML.
`protected static void`
`displayXMLString(XMLOutput out, String tag, String value)`
This convenience function displays a String value in XML.
`protected static void`
`displayXMLStringArray(XMLOutput out, String tag, String[] values)`
This convenience function displays a String array in XML.
`boolean`
`equals(Object other)`
Determines if this ElementDef is equal to other (deeply), returning true if the two are equal.
`NodeDef[]`
`getChildren()`
Returns the children of this node.
`protected static ElementDef[]`
`getElementChildren(DOMWrapper _def, Class clazz, String prefix)`
`static Class`
`getElementClass(DOMWrapper wrapper, Class enclosure, String prefix)`
getElementClass is a static helper function which finds the XMLDef class corresponding to an Element.
`Location`
`getLocation()`
Returns the location of this element in its document.
`protected static NodeDef[]`
`getMixedChildren(DOMWrapper _def, Class clazz, String prefix)`
`protected static NodeDef[]`
`getMixedChildren_new(DOMWrapper _def, Class clazz, String prefix)`
`String`
`getName()`
Returns the name of this node's tag.
`String`
`getText()`
Returns the text inside this node.
`int`
`getType()`
Returns the type of this element.
`DOMWrapper`
`getWrapper()`
Retrieves the `DOMWrapper` which was used to create this node.
`int`
`hashCode()`
Returns a unique hash of this instance.
`String`
`toCompactXML()`
The toCompactXML function automatically uses displayXML() to produce an XML version of this ElementDef as a String.
`String`
`toString()`
The toString function automatically uses display() to produce a string version of this ElementDef.
`String`
`toXML()`
The toXML function automatically uses displayXML() to produce an XML version of this ElementDef as a String.
`void`
`verifyEqual(ElementDef other)`
Verifies that this ElementDef is equal to other, throwing a XOMException with a lengthy explanation if equality fails.

### Methods inherited from class java.lang.Object

`finalize, getClass, notify, notifyAll, wait, wait, wait`

### Methods inherited from interface org.eigenbase.xom.NodeDef

`display`

## Constructor Details

### ElementDef

public ElementDef()

## Method Details

### getElementClass

public static Class getElementClass(DOMWrapper wrapper, Class enclosure, String prefix) throws XOMException
getElementClass is a static helper function which finds the XMLDef class corresponding to an Element. The Element's tag must start with the given prefix name, and the remainder of the tag must correspond to a static inner class of the given enclosing class.

Parameters:
  `wrapper` - the DOMWrapper whose class to look up.
  `enclosure` - a Class which encloses the Class to lookup.
  `prefix` - a prefix which must appear on the tag name.
Returns:
  the ElementDef Class corresponding to the element, or null if no class could be found (possible if this is a String element.
Throws:
  `XOMException`

### constructElement

public static NodeDef constructElement(DOMWrapper wrapper, Class elemClass) throws XOMException
constructElement is a helper function which builds the appropriate type of ElementDef from an XML Element. This version of the function takes an Element and a Class object specifying the exact class to use in constructing the element.

Parameters:
  `wrapper` - the DOM Element wrapper from which to build this class.
  `elemClass` - the Class to use to construct this class. It must have a constructor which takes the Element type.
Returns:
  a fully constructed ElementDef of the type specified by Class.
Throws:
  `XOMException` - if clazz has no constructor which takes Element, or if construction fails.

### constructElement

public static NodeDef constructElement(DOMWrapper wrapper, Class enclosure, String prefix) throws XOMException
constructElement is a helper function which builds the appropriate type of ElementDef from an XML Element. This function should be used when creating an ElementDef from a list of optional XML element types using ElementParser.requiredOption. Generally, it is better to call the constructors of ElementDef subclasses directly if the exact type of an element is known.

Parameters:
  `wrapper` - the DOM Element Wrapper from which to build this class.
Returns:
  an ElementDef whose exact type depends on the tag name of the element definition.
Throws:
  `XOMException` - if no subclass of ElementDef can be found, or if def is malformed.

### displayXML

public void displayXML(XMLOutput out, int indent)
Description copied from interface: `NodeDef`
Outputs this element definition in XML to any XMLOutput.

Specified by:
  `displayXML` in interface `NodeDef`
Parameters:
  `out` - the XMLOutput class to display the XML

### displayXML

public void displayXML(XMLOutput out)

### displayDiff

public boolean displayDiff(ElementDef other, PrintWriter out, int indent)
The displayDiff function compares this element definition against another, compiling a message containing all diffs. It is used internally by the equals(), diff(), and verifyEquals() functions.

Parameters:
  `other` - the ElementDef to which to compare this element.
  `out` - a PrintWriter to which to display any discovered differences, or null if just doing an equality check (and no diff report is needed).
  `indent` - the current indentation level (used for nice display of diffs).
Returns:
  true if this and other match exactly, false if not.

### getName

public String getName()
Description copied from interface: `NodeDef`
Returns the name of this node's tag.

Specified by:
  `getName` in interface `NodeDef`

### getType

public int getType()
Description copied from interface: `NodeDef`
Returns the type of this element. Values are as for `DOMWrapper.getType()`.

Specified by:
  `getType` in interface `NodeDef`

### getText

public String getText()
Description copied from interface: `NodeDef`
Returns the text inside this node.

Specified by:
  `getText` in interface `NodeDef`

### displayIndent

protected static void displayIndent(PrintWriter out, int indent)
This function writes an indentation level to the given PrintWriter.

Parameters:
  `out` - the PrintWriter to which to write the indent.
  `indent` - the indentation level

### displayString

protected static void displayString(PrintWriter out, String name, String value, int indent)
This convenience function displays a String value with the given parameter name at the given indentation level. It is meant to be called by subclasses of ElementDef.

Parameters:
  `out` - the PrintWriter to which to write this String.
  `name` - the parameter name of this string.
  `value` - the value of the String parameter.
  `indent` - the indentation level.

### displayAttribute

protected static void displayAttribute(PrintWriter out, String name, Object value, int indent)
This convenience function displays an XML attribute value with the given attribute name at the given indentation level. It should be called by subclasses of ElementDef.

Parameters:
  `out` - the PrintWriter to which to write this String.
  `name` - the attribute name.
  `value` - the attribute value.
  `indent` - the indentation level.

### displayElement

protected static void displayElement(PrintWriter out, String name, ElementDef value, int indent)
This convenience function displays any ElementDef with the given parameter name at the given indentation level.

Parameters:
  `out` - the PrintWriter to which to write this ElementDef.
  `name` - the parameter name for this ElementDef.
  `value` - the parameter's value (as an ElementDef).
  `indent` - the indentation level.

### displayElementArray

protected static void displayElementArray(PrintWriter out, String name, NodeDef[] values, int indent)
This convenience function displays any array of ElementDef values with the given parameter name (assumed to represent an array) at the given indentation level. Each value of the array will be written on a separate line with a new indentation.

Parameters:
  `out` - the PrintWriter to which to write this ElementDef.
  `name` - the parameter name for this ElementDef.
  `values` - the parameter's values (as an ElementDef[] array).
  `indent` - the indentation level.

### displayStringArray

protected static void displayStringArray(PrintWriter out, String name, String[] values, int indent)
This convenience function displays any array of String values with the given parameter name (assumed to represent an array) at the given indentation level. Each value of the array will be written on a separate line with a new indentation.

Parameters:
  `out` - the PrintWriter to which to write this ElementDef.
  `name` - the parameter name for this ElementDef.
  `values` - the parameter's values (as a String[] array).
  `indent` - the indentation level.

### displayXMLString

protected static void displayXMLString(XMLOutput out, String tag, String value)
This convenience function displays a String value in XML. parameter name at the given indentation level. It is meant to be called by subclasses of ElementDef.

Parameters:
  `out` - XMLOutput class to which to generate XML.
  `tag` - the Tag name of this String object.
  `value` - the String value.

### displayXMLElement

protected static void displayXMLElement(XMLOutput out, ElementDef value)
This convenience function displays any ElementDef in XML.

Parameters:
  `out` - the XMLOutput class to which to generate XML.
  `value` - the ElementDef to display.

### displayXMLElementArray

protected static void displayXMLElementArray(XMLOutput out, NodeDef[] values)
This convenience function displays an array of ElementDef values in XML.

Parameters:
  `out` - the XMLOutput class to which to generate XML.
  `values` - the ElementDef to display.

### displayXMLStringArray

protected static void displayXMLStringArray(XMLOutput out, String tag, String[] values)
This convenience function displays a String array in XML.

Parameters:
  `out` - the XMLOutput class to which to generate XML.
  `tag` - the tag name for the String elements.
  `values` - the actual string values.

### displayStringDiff

protected static boolean displayStringDiff(String name, String value1, String value2, PrintWriter out, int indent)
This convenience function displays differences in two versions of the same string object.

Parameters:
  `name` - the object name.
  `value1` - the first string.
  `value2` - the second string.
  `out` - the PrintWriter to which to write differences.
  `indent` - the indentation level.
Returns:
  true if the strings match, false if not.

### displayAttributeDiff

protected static boolean displayAttributeDiff(String name, Object value1, Object value2, PrintWriter out, int indent)
This convenience function displays differences in two versions of the same XML attribute value.

Parameters:
  `name` - the attribute name.
  `value1` - the first attribute value.
  `value2` - the second attribute value.
  `out` - the PrintWriter to which to write differences.
  `indent` - the indentation level.
Returns:
  true if the values match, false if not.

### displayElementDiff

protected static boolean displayElementDiff(String name, NodeDef value1, NodeDef value2, PrintWriter out, int indent)
This convenience function displays differences in the values of any two ElementDefs, returning true if they match and false if not.

Parameters:
  `name` - the object name.
  `value1` - the first value.
  `value2` - the second value.
  `out` - the PrintWriter to which to write differences.
  `indent` - the indentation level.
Returns:
  true if the values match, false if not.

### displayElementArrayDiff

protected static boolean displayElementArrayDiff(String name, NodeDef[] values1, NodeDef[] values2, PrintWriter out, int indent)
This convenience function diffs any array of ElementDef values with the given array name. All differences are written to the given PrintWriter at the given indentation level.

Parameters:
  `name` - the array name.
  `values1` - the first array.
  `values2` - the second array.
  `out` - the PrintWriter to which to write differences.
  `indent` - the indentation level.
Returns:
  true if the both arrays match, false if there are any differences.

### displayStringArrayDiff

protected static boolean displayStringArrayDiff(String name, String[] values1, String[] values2, PrintWriter out, int indent)
This convenience function diffs any array of strings with the given array name. All differences are written to the given PrintWriter at the given indentation level.

Parameters:
  `name` - the array name.
  `values1` - the first array.
  `values2` - the second array.
  `out` - the PrintWriter to which to write differences.
  `indent` - the indentation level.
Returns:
  true if the both arrays match, false if there are any differences.

### toString

public String toString()
The toString function automatically uses display() to produce a string version of this ElementDef. The indentation level is always zero.

Overrides:
  `toString` in class `Object`

### toXML

public String toXML()
The toXML function automatically uses displayXML() to produce an XML version of this ElementDef as a String.

Returns:
  an XML representation of this ElementDef, as a String.

### toCompactXML

public String toCompactXML()
The toCompactXML function automatically uses displayXML() to produce an XML version of this ElementDef as a String. The generated XML is compact; free of unnecessary whitespace. Compact XML is useful when embedding XML in a CDATA section or transporting over the network.

Returns:
  an XML representation of this ElementDef, as a String.

### diff

public String diff(ElementDef other)
The diff function compares this element against another, determining if they are exactly equal. If so, the function returns null. If not, it returns a String describing the differences.

### equals

public boolean equals(Object other)
Determines if this ElementDef is equal to other (deeply), returning true if the two are equal.

Overrides:
  `equals` in class `Object`
Returns:
  true if this equals other, false if not.
Throws:
  `ClassCastException` - if other is not an ElementDef.

### hashCode

public int hashCode()
Returns a unique hash of this instance.

Overrides:
  `hashCode` in class `Object`
Returns:
  hash of the toXML() return value

### verifyEqual

public void verifyEqual(ElementDef other) throws XOMException
Verifies that this ElementDef is equal to other, throwing a XOMException with a lengthy explanation if equality fails.

Parameters:
  `other` - the ElementDef to compare to this one.
Throws:
  `XOMException`

### clone

protected Object clone() throws CloneNotSupportedException
Clone an ElementDef. Because all ElementDefs are serializable, we can clone through a memory buffer.

Overrides:
  `clone` in class `Object`
Throws:
  `CloneNotSupportedException`

### deepCopy

public ElementDef deepCopy() throws XOMException
Public version of clone(); returns a deep copy of this ElementDef.

Throws:
  `XOMException`

### getWrapper

public DOMWrapper getWrapper()
Description copied from interface: `NodeDef`
Retrieves the `DOMWrapper` which was used to create this node. Only works if this nodes's `MetaDef.Element.keepDef` was true (or, if it is not set, if the default `MetaDef.Model.defaultKeepDef` is true); otherwise, returns `null`.

Specified by:
  `getWrapper` in interface `NodeDef`
Returns:
  wrapper underlying this node

### getChildren

public NodeDef[] getChildren()
Description copied from interface: `NodeDef`
Returns the children of this node.

Specified by:
  `getChildren` in interface `NodeDef`

### addChild

public void addChild(NodeDef child) throws XOMException

Throws:
  `XOMException`

### addChildren

public void addChildren(NodeDef[] children) throws XOMException

Throws:
  `XOMException`

### getMixedChildren_new

protected static NodeDef[] getMixedChildren_new(DOMWrapper _def, Class clazz, String prefix) throws XOMException

Throws:
  `XOMException`

### getMixedChildren

protected static NodeDef[] getMixedChildren(DOMWrapper _def, Class clazz, String prefix) throws XOMException

Throws:
  `XOMException`

### getElementChildren

protected static ElementDef[] getElementChildren(DOMWrapper _def, Class clazz, String prefix) throws XOMException

Throws:
  `XOMException`

### getLocation

public Location getLocation()
Description copied from interface: `NodeDef`
Returns the location of this element in its document.

Specified by:
  `getLocation` in interface `NodeDef`
Returns:
  location of this element, or null if location is not available