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, 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 and Description
ElementDef()

Method Summary

Modifier and Type	Method and 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_new(DOMWrapper _def, Class clazz, String prefix)
protected static NodeDef[]	getMixedChildren(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 Detail

ElementDef

public ElementDef()

Method Detail

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