Package org.eigenbase.xom

## Class ElementDef

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

All Implemented Interfaces:
  `java.io.Serializable`, `java.lang.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 java.lang.Object
    implements NodeDef, java.io.Serializable, java.lang.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
`ElementDef()`

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`void` `addChild​(NodeDef child)`
`void` `addChildren​(NodeDef[] children)`
`protected java.lang.Object` `clone()` Clone an ElementDef.
`static NodeDef` `constructElement​(DOMWrapper wrapper, java.lang.Class elemClass)` constructElement is a helper function which builds the appropriate type of ElementDef from an XML Element.
`static NodeDef` `constructElement​(DOMWrapper wrapper, java.lang.Class enclosure, java.lang.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.
`java.lang.String` `diff​(ElementDef other)` The diff function compares this element against another, determining if they are exactly equal.
`protected static void` `displayAttribute​(java.io.PrintWriter out, java.lang.String name, java.lang.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​(java.lang.String name, java.lang.Object value1, java.lang.Object value2, java.io.PrintWriter out, int indent)` This convenience function displays differences in two versions of the same XML attribute value.
`boolean` `displayDiff​(ElementDef other, java.io.PrintWriter out, int indent)` The displayDiff function compares this element definition against another, compiling a message containing all diffs.
`protected static void` `displayElement​(java.io.PrintWriter out, java.lang.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​(java.io.PrintWriter out, java.lang.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​(java.lang.String name, NodeDef[] values1, NodeDef[] values2, java.io.PrintWriter out, int indent)` This convenience function diffs any array of ElementDef values with the given array name.
`protected static boolean` `displayElementDiff​(java.lang.String name, NodeDef value1, NodeDef value2, java.io.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​(java.io.PrintWriter out, int indent)` This function writes an indentation level to the given PrintWriter.
`protected static void` `displayString​(java.io.PrintWriter out, java.lang.String name, java.lang.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​(java.io.PrintWriter out, java.lang.String name, java.lang.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​(java.lang.String name, java.lang.String[] values1, java.lang.String[] values2, java.io.PrintWriter out, int indent)` This convenience function diffs any array of strings with the given array name.
`protected static boolean` `displayStringDiff​(java.lang.String name, java.lang.String value1, java.lang.String value2, java.io.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, java.lang.String tag, java.lang.String value)` This convenience function displays a String value in XML.
`protected static void` `displayXMLStringArray​(XMLOutput out, java.lang.String tag, java.lang.String[] values)` This convenience function displays a String array in XML.
`boolean` `equals​(java.lang.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, java.lang.Class clazz, java.lang.String prefix)`
`static java.lang.Class` `getElementClass​(DOMWrapper wrapper, java.lang.Class enclosure, java.lang.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, java.lang.Class clazz, java.lang.String prefix)`
`protected static NodeDef[]` `getMixedChildren_new​(DOMWrapper _def, java.lang.Class clazz, java.lang.String prefix)`
`java.lang.String` `getName()` Returns the name of this node's tag.
`java.lang.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.
`java.lang.String` `toCompactXML()` The toCompactXML function automatically uses displayXML() to produce an XML version of this ElementDef as a String.
`java.lang.String` `toString()` The toString function automatically uses display() to produce a string version of this ElementDef.
`java.lang.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 Detail

#### ElementDef

    public ElementDef()

### Method Detail

#### getElementClass

    public static java.lang.Class getElementClass​(DOMWrapper wrapper,
                                                  java.lang.Class enclosure,
                                                  java.lang.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,
                                           java.lang.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,
                                           java.lang.Class enclosure,
                                           java.lang.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,
                               java.io.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 java.lang.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 java.lang.String getText()

Description copied from interface: `NodeDef`
Returns the text inside this node.

Specified by:
  `getText` in interface `NodeDef`

#### displayIndent

    protected static void displayIndent​(java.io.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​(java.io.PrintWriter out,
                                        java.lang.String name,
                                        java.lang.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​(java.io.PrintWriter out,
                                           java.lang.String name,
                                           java.lang.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​(java.io.PrintWriter out,
                                         java.lang.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​(java.io.PrintWriter out,
                                              java.lang.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​(java.io.PrintWriter out,
                                             java.lang.String name,
                                             java.lang.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,
                                           java.lang.String tag,
                                           java.lang.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,
                                                java.lang.String tag,
                                                java.lang.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​(java.lang.String name,
                                               java.lang.String value1,
                                               java.lang.String value2,
                                               java.io.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​(java.lang.String name,
                                                  java.lang.Object value1,
                                                  java.lang.Object value2,
                                                  java.io.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​(java.lang.String name,
                                                NodeDef value1,
                                                NodeDef value2,
                                                java.io.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​(java.lang.String name,
                                                     NodeDef[] values1,
                                                     NodeDef[] values2,
                                                     java.io.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​(java.lang.String name,
                                                    java.lang.String[] values1,
                                                    java.lang.String[] values2,
                                                    java.io.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 java.lang.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 `java.lang.Object`

#### toXML

    public java.lang.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 java.lang.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 java.lang.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​(java.lang.Object other)

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

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

#### hashCode

    public int hashCode()

Returns a unique hash of this instance.

Overrides:
  `hashCode` in class `java.lang.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 java.lang.Object clone()
                              throws java.lang.CloneNotSupportedException

Clone an ElementDef. Because all ElementDefs are serializable, we can clone through a memory buffer.

Overrides:
  `clone` in class `java.lang.Object`
Throws:
  `java.lang.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,
                                                    java.lang.Class clazz,
                                                    java.lang.String prefix)
                                             throws XOMException

Throws:
  `XOMException`

#### getMixedChildren

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

Throws:
  `XOMException`

#### getElementChildren

    protected static ElementDef[] getElementChildren​(DOMWrapper _def,
                                                     java.lang.Class clazz,
                                                     java.lang.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