DOMElementParser (eigenbase-xom 1.3.7 API)

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

```
public class DOMElementParser
extends Object
```
DOMElementParser is a utility wrapper around DOMWrapper. Implements a parseable stream of child DOMWrappers and also provides validation on an XML document beyond the DTD.

Constructor Summary

Constructors
Constructor and Description
`DOMElementParser(DOMWrapper wrapper, String prefix, Class enclosure)` Constructs a new ElementParser based on an Element of the XML parse tree wrapped in a DOMWrapper, and a prefix (to be applied to all element tags except the root), and the name of the enclosing class.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`NodeDef[]`	`classArray(Class elemClass, int min, int max)` This function retrieves a collection of elements which are subclasses of the given class, returning them as an array.
`NodeDef[]`	`getArray(Class elemClass, int min, int max)` This function retrieves a collection of elements which are subclasses of the given class, returning them as an array.
`Object`	`getAttribute(String attrName, String attrType, String defaultValue, String[] values, boolean required)` Retrieve an Attribute from the parser.
`NodeDef`	`getElement(Class elementClass, boolean required)` This function retrieves an Element from this parser, advancing the parser if the element is found.
`static Class`	`getPluginClass(Class managerClass)` Get a Class object representing a plugin class, given a manager class that implements the static method getXMLDefClass().
`static Class`	`getPluginClass(String packageName, String className)` Get a Class object representing a plugin class, identified either directly by a Java package and Java class name, or indirectly by a Java package and Java class which defines a method called getXMLDefClass() to return the appropriate class.
`String`	`getString(String elementName, boolean required)` This function retrieves a String element from this parser, advancing the parser if the element is found.
`String[]`	`getStringArray(String elemName, int min, int max)` This function returns a collection of String elements of the given name, returning them as an array.
`String`	`getText()` This function is used to return a CDATA section as text.
`int`	`lastOptionIndex()` Returns the option index of the element returned through the last requiredOption call.
`DOMWrapper[]`	`optionalArray(String elemName, int min, int max)` This function retrieves a collection of elements with the given name, returning them as an array.
`String`	`optionalAttribute(String attrName)` This function retrieves an optional Attribute by name from the current Element.
`Boolean`	`optionalBooleanAttribute(String attrName)` This function retrieves an optional Attribute by name from the current Element, converting it to an Boolean.
`Double`	`optionalDoubleAttribute(String attrName)` This function retrieves an optional Attribute by name from the current Element, converting it to a Double.
`DOMWrapper`	`optionalElement(String elementName)` This function retrieves an optional Element from this parser, advancing the parser if the element is found.
`Integer`	`optionalIntegerAttribute(String attrName)` This function retrieves an optional Attribute by name from the current Element, converting it to an Integer.
`String`	`optionalString(String elementName)` This function retrieves an optional String element from this parser, advancing the parser if the element is found.
`String`	`requiredAttribute(String attrName)` This function retrieves a required Attribute by name from the current Element.
`Boolean`	`requiredBooleanAttribute(String attrName)` This function retrieves an required Attribute by name from the current Element, converting it to a Boolean.
`NodeDef`	`requiredClass(Class classTemplate)` This function retrieves a required Element of a specific class from this parser, advancing the parser after the read.
`static String`	`requiredDefAttribute(DOMWrapper wrapper, String attrName, String defaultVal)` This static version of requiredAttribute uses any element definition as a basis for the attribute.
`DOMWrapper`	`requiredElement(String elementName)` This function retrieves a required Element from this parser, advancing the parser after the read.
`Integer`	`requiredIntegerAttribute(String attrName)` This function retrieves an required Attribute by name from the current Element, converting it to an Integer.
`DOMWrapper`	`requiredOption(String[] elementNames)` This function retrieves a required element which may have one of a number of names.
`String`	`requiredString(String elementName)` This function retrieves a required String element from this parser, advancing the parser after the read.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - DOMElementParser
```
public DOMElementParser(DOMWrapper wrapper,
                        String prefix,
                        Class enclosure)
                 throws XOMException
```
    Constructs a new ElementParser based on an Element of the XML parse tree wrapped in a DOMWrapper, and a prefix (to be applied to all element tags except the root), and the name of the enclosing class.
    
    Parameters:
    
    wrapper - a DOMWrapper representing the section of the XML parse tree to traverse.
    
    Throws:
    
    XOMException
- Method Detail
  - requiredString
```
public String requiredString(String elementName)
                      throws XOMException
```
    This function retrieves a required String element from this parser, advancing the parser after the read.
    
    Parameters:
    
    elementName - the name of the element to retrieve.
    
    Returns:
    
    the String value stored inside the element to retrieve.
    
    Throws:
    
    XOMException - if there is no element with the given name.
  - optionalString
```
public String optionalString(String elementName)
                      throws XOMException
```
    This function retrieves an optional String element from this parser, advancing the parser if the element is found. If no element of the correct name is found, this function returns null.
    
    Parameters:
    
    elementName - the name of the element to retrieve.
    
    Returns:
    
    the String value stored inside the element to retrieve.
    
    Throws:
    
    XOMException
  - requiredElement
```
public DOMWrapper requiredElement(String elementName)
                           throws XOMException
```
    This function retrieves a required Element from this parser, advancing the parser after the read.
    
    Parameters:
    
    elementName - the name of the element to retrieve.
    
    Returns:
    
    the DOMWrapper to retrieve.
    
    Throws:
    
    XOMException - if there is no element with the given name.
  - getText
```
public String getText()
```
    This function is used to return a CDATA section as text. It does no parsing.
    
    Returns:
    
    the contents of the CDATA element as text.
  - optionalElement
```
public DOMWrapper optionalElement(String elementName)
                           throws XOMException
```
    This function retrieves an optional Element from this parser, advancing the parser if the element is found. If no element of the correct name is found, this function returns null.
    
    Parameters:
    
    elementName - the name of the element to retrieve.
    
    Returns:
    
    the DOMWrapper to retreive, or null if none found.
    
    Throws:
    
    XOMException
  - requiredOption
```
public DOMWrapper requiredOption(String[] elementNames)
                          throws XOMException
```
    This function retrieves a required element which may have one of a number of names. The parser is advanced after the read.
    
    Parameters:
    
    elementNames - an array of allowed names. Names are compared in a case-insensitive fashion.
    
    Returns:
    
    the first element with one of the given names.
    
    Throws:
    
    XOMException - if there are no more elements to read or if the next element's name is not in the elementNames list.
  - requiredClass
```
public NodeDef requiredClass(Class classTemplate)
                      throws XOMException
```
    This function retrieves a required Element of a specific class from this parser, advancing the parser after the read. The class must be derived from ElementDef.
    
    Throws:
    
    XOMException
  - lastOptionIndex
```
public int lastOptionIndex()
```
    Returns the option index of the element returned through the last requiredOption call.
  - requiredAttribute
```
public String requiredAttribute(String attrName)
                         throws XOMException
```
    This function retrieves a required Attribute by name from the current Element.
    
    Parameters:
    
    attrName - the name of the attribute.
    
    Returns:
    
    the String value of the attribute.
    
    Throws:
    
    XOMException - if no attribute of this name is set.
  - requiredDefAttribute
```
public static String requiredDefAttribute(DOMWrapper wrapper,
                                          String attrName,
                                          String defaultVal)
                                   throws XOMException
```
    This static version of requiredAttribute uses any element definition as a basis for the attribute. It is used by Plugin definitions to return attributes before the parser is created.
    
    Parameters:
    
    wrapper - the Element in which to find the attribute.
    
    attrName - the name of the attribute to retrieve.
    
    defaultVal - the default value of the attribute to retrieve.
    
    Throws:
    
    XOMException - if no attribute of this name is set.
  - optionalAttribute
```
public String optionalAttribute(String attrName)
                         throws XOMException
```
    This function retrieves an optional Attribute by name from the current Element.
    
    Parameters:
    
    attrName - the name of the attribute.
    
    Returns:
    
    the String value of the attribute, or null if the attribute is not set.
    
    Throws:
    
    XOMException
  - optionalIntegerAttribute
```
public Integer optionalIntegerAttribute(String attrName)
                                 throws XOMException
```
    This function retrieves an optional Attribute by name from the current Element, converting it to an Integer.
    
    Parameters:
    
    attrName - the name of the attribute.
    
    Returns:
    
    the Integer value of the attribute, or null if the attribute is not set.
    
    Throws:
    
    XOMException - if the value is set to an illegal integer value.
  - optionalDoubleAttribute
```
public Double optionalDoubleAttribute(String attrName)
                               throws XOMException
```
    This function retrieves an optional Attribute by name from the current Element, converting it to a Double.
    
    Parameters:
    
    attrName - the name of the attribute.
    
    Returns:
    
    the Double value of the attribute, or null if the attribute is not set.
    
    Throws:
    
    XOMException - if the value is set to an illegal double value.
  - requiredIntegerAttribute
```
public Integer requiredIntegerAttribute(String attrName)
                                 throws XOMException
```
    This function retrieves an required Attribute by name from the current Element, converting it to an Integer.
    
    Parameters:
    
    attrName - the name of the attribute.
    
    Returns:
    
    the Integer value of the attribute.
    
    Throws:
    
    XOMException - if the value is not set, or is set to an illegal integer value.
  - optionalBooleanAttribute
```
public Boolean optionalBooleanAttribute(String attrName)
                                 throws XOMException
```
    This function retrieves an optional Attribute by name from the current Element, converting it to an Boolean. The string value "true" (in any case) is considered TRUE. Any other value is considered false.
    
    Parameters:
    
    attrName - the name of the attribute.
    
    Returns:
    
    the Boolean value of the attribute, or null if the attribute is not set.
    
    Throws:
    
    XOMException - if the value is set to an illegal integer value.
  - requiredBooleanAttribute
```
public Boolean requiredBooleanAttribute(String attrName)
                                 throws XOMException
```
    This function retrieves an required Attribute by name from the current Element, converting it to a Boolean. The string value "true" (in any case) is considered TRUE. Any other value is considered false.
    
    Parameters:
    
    attrName - the name of the attribute.
    
    Returns:
    
    the Boolean value of the attribute.
    
    Throws:
    
    XOMException
  - optionalArray
```
public DOMWrapper[] optionalArray(String elemName,
                                  int min,
                                  int max)
                           throws XOMException
```
    This function retrieves a collection of elements with the given name, returning them as an array.
    
    Parameters:
    
    elemName - the element name.
    
    min - the minimum number of elements required in the array. Set this parameter to 0 to indicate no minimum.
    
    max - the maximum number of elements allowed in the array. Set this parameter to 0 to indicate no maximum.
    
    Returns:
    
    an Element array containing the discovered elements.
    
    Throws:
    
    XOMException - if there are fewer than min or more than max elements with the name elemName.
  - classArray
```
public NodeDef[] classArray(Class elemClass,
                            int min,
                            int max)
                     throws XOMException
```
    This function retrieves a collection of elements which are subclasses of the given class, returning them as an array. The array will contain ElementDef objects automatically constructed to be of the correct class.
    
    Parameters:
    
    elemClass - the element class.
    
    min - the minimum number of elements required in the array. Set this parameter to 0 to indicate no minimum.
    
    max - the maximum number of elements allowed in the array. Set this parameter to 0 to indicate no maximum.
    
    Returns:
    
    an ElementDef array containing the discovered elements.
    
    Throws:
    
    XOMException - if there are fewer than min or more than max elements with the name elemName.
  - getElement
```
public NodeDef getElement(Class elementClass,
                          boolean required)
                   throws XOMException
```
    This function retrieves an Element from this parser, advancing the parser if the element is found. The Element's corresponding ElementDef class is looked up and its constructor is called automatically. If the requested Element is not found the function returns null unless required is set to true. In this case, a XOMException is thrown.
    
    Parameters:
    
    elementClass - the Class of the element to retrieve.
    
    required - true to throw an exception if the element is not found, false to simply return null.
    
    Returns:
    
    the element, as an ElementDef, or null if it is not found and required is false.
    
    Throws:
    
    XOMException - if required is true and the element could not be found.
  - getArray
```
public NodeDef[] getArray(Class elemClass,
                          int min,
                          int max)
                   throws XOMException
```
    This function retrieves a collection of elements which are subclasses of the given class, returning them as an array. The array will contain ElementDef objects automatically constructed to be of the correct class.
    
    Parameters:
    
    elemClass - the element class.
    
    min - the minimum number of elements required in the array. Set this parameter to 0 to indicate no minimum.
    
    max - the maximum number of elements allowed in the array. Set this parameter to 0 to indicate no maximum.
    
    Returns:
    
    an ElementDef array containing the discovered elements.
    
    Throws:
    
    XOMException - if there are fewer than min or more than max elements with the name elemName.
  - getString
```
public String getString(String elementName,
                        boolean required)
                 throws XOMException
```
    This function retrieves a String element from this parser, advancing the parser if the element is found. If no element of the correct name is found, this function returns null, unless required is true, in which case a XOMException is thrown.
    
    Parameters:
    
    elementName - the name of the element to retrieve.
    
    required - true to throw an exception if the element is not found, false to simply return null.
    
    Returns:
    
    the String value stored inside the element to retrieve, or null if no element with the given elementName could be found.
    
    Throws:
    
    XOMException
  - getStringArray
```
public String[] getStringArray(String elemName,
                               int min,
                               int max)
                        throws XOMException
```
    This function returns a collection of String elements of the given name, returning them as an array.
    
    Parameters:
    
    elemName - the element name.
    
    min - the minimum number of elements required in the array. Set this parameter to 0 to indicate no minimum.
    
    max - the maximum number of elements allowed in the array. Set this parameter to 0 to indicate no maximum.
    
    Returns:
    
    a String array containing the discovered elements.
    
    Throws:
    
    XOMException - if there are fewer than min or more than max elements with the name elemName.
  - getPluginClass
```
public static Class getPluginClass(String packageName,
                                   String className)
                            throws XOMException
```
    Get a Class object representing a plugin class, identified either directly by a Java package and Java class name, or indirectly by a Java package and Java class which defines a method called getXMLDefClass() to return the appropriate class.
    
    Parameters:
    
    packageName - the name of the Java package containing the plugin class.
    
    className - the name of the plugin definition class.
    
    Throws:
    
    XOMException - if the plugin class cannot be located or if the designated class is not suitable as a plugin class.
  - getPluginClass
```
public static Class getPluginClass(Class managerClass)
                            throws XOMException
```
    Get a Class object representing a plugin class, given a manager class that implements the static method getXMLDefClass().
    
    Parameters:
    
    managerClass - any Class that implements getXMLDefClass.
    
    Returns:
    
    the plugin Class.
    
    Throws:
    
    XOMException
  - getAttribute
```
public Object getAttribute(String attrName,
                           String attrType,
                           String defaultValue,
                           String[] values,
                           boolean required)
                    throws XOMException
```
    Retrieve an Attribute from the parser. The Attribute may be of any Java class, provided that the class supports a constructor from the String class. The Attribute's value will be returned as an Object, which must then be cast to the appropraite type. If the attribute is not defined and has no default, either null is returned (if required is false), or a XOMException is thrown (if required is true).
    
    Parameters:
    
    attrName - the name of the attribute to retreive.
    
    attrType - a String naming a Java Class to serve as the type. If attrType contains a "." character, the class is looked up directly from the type name. Otherwise, the class is looked up in the java.lang package. Finally, the class must have a constructor which takes a String as an argument.
    
    defaultValue - the default value for this attribute. If values is set, the defaultValue must also be one of the set of values. defaultValue may be null.
    
    values - an array of possible values for the attribute. If this parameter is not null, then the attribute's value must be one of the listed set of values or an exception will be thrown.
    
    required - if set, then this function will throw an exception if the attribute has no value and defaultValue is null.
    
    Returns:
    
    the Attribute's value as an Object. The actual class of this object is determined by attrType.
    
    Throws:
    
    XOMException

Class DOMElementParser

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

DOMElementParser

Method Detail

requiredString

optionalString

requiredElement

getText

optionalElement

requiredOption

requiredClass

lastOptionIndex

requiredAttribute

requiredDefAttribute

optionalAttribute

optionalIntegerAttribute

optionalDoubleAttribute

requiredIntegerAttribute

optionalBooleanAttribute

requiredBooleanAttribute

optionalArray

classArray

getElement

getArray

getString

getStringArray

getPluginClass

getPluginClass

getAttribute