IcedTea-Web NetX

## net.sourceforge.nanoxml
Class XMLElement

    java.lang.Object
      net.sourceforge.nanoxml.XMLElement

    public class XMLElement

extends java.lang.Object

XMLElement is a representation of an XML object. The object is able to parse XML code.

Parsing XML Data
  You can parse XML data using the following code:
  `XMLElement xml = new XMLElement();
  FileReader reader = new FileReader("filename.xml");
  xml.parseFromReader(reader);`

Retrieving Attributes
  You can enumerate the attributes of an element using the method `enumerateAttributeNames`. The attribute values can be retrieved using the method `getAttribute`. The following example shows how to list the attributes of an element:
  `XMLElement element = ...;
  Enumeration enum = element.enumerateAttributeNames();
  while (enum.hasMoreElements()) {
  String key = (String) enum.nextElement();
  String value = (String) element.getAttribute(key);
  System.out.println(key + " = " + value);
  }`

Retrieving Child Elements
  You can enumerate the children of an element using `enumerateChildren`. The number of child elements can be retrieved using `countChildren`.

Elements Containing Character Data
  If an elements contains character data, like in the following example:
  `<title>The Title</title>`
  you can retrieve that data using the method `getContent`.

Subclassing XMLElement
  When subclassing XMLElement, you need to override the method `createAnotherElement` which has to return a new copy of the receiver.

See Also:
  `XMLParseException`

Constructor Summary
`` `XMLElement()` Creates and initializes a new XML element.
`protected` `XMLElement(java.util.Hashtable<java.lang.String,char[]> entities, boolean skipLeadingWhitespace, boolean fillBasicConversionTable, boolean ignoreCase)` Creates and initializes a new XML element.

Method Summary
`void` `addChild(XMLElement child)` Adds a child element.
`protected boolean` `checkCDATA(java.lang.StringBuffer buf)` Scans a special tag and if the tag is a CDATA section, append its content to `buf`.
`protected boolean` `checkLiteral(java.lang.String literal)` Scans the data for literal text.
`int` `countChildren()` Returns the number of child elements of the element.
`protected XMLElement` `createAnotherElement()` Creates a new similar XML element.
`java.util.Enumeration` `enumerateAttributeNames()` Enumerates the attribute names.
`java.util.Enumeration` `enumerateChildren()` Enumerates the child elements.
`protected XMLParseException` `expectedInput(java.lang.String charSet)` Creates a parse exception for when the next character read is not the character that was expected.
`protected XMLParseException` `expectedInput(java.lang.String charSet, char ch)` Creates a parse exception for when the next character read is not the character that was expected.
`java.lang.Object` `getAttribute(java.lang.String name)` Returns an attribute of the element.
`java.lang.String` `getContent()` Returns the PCDATA content of the object.
`int` `getLineNr()` Returns the line nr in the source data on which the element is found.
`java.lang.String` `getName()` Returns the name of the element.
`protected XMLParseException` `invalidValue(java.lang.String name, java.lang.String value)` Creates a parse exception for when an invalid value is given to a method.
`protected XMLParseException` `invalidValueSet(java.lang.String name)` Creates a parse exception for when an invalid valueset is given to a method.
`void` `parseFromReader(java.io.Reader reader)` Reads one XML element from a java.io.Reader and parses it.
`void` `parseFromReader(java.io.Reader reader, int startingLineNr)` Reads one XML element from a java.io.Reader and parses it.
`protected char` `readChar()` Reads a character from a reader.
`protected void` `resolveEntity(java.lang.StringBuffer buf)` Resolves an entity.
`void` `sanitizeInput(java.io.Reader isr, java.io.OutputStream pout)` Reads an xml file and removes the comments, leaving only relevant xml code.
`protected void` `scanElement(XMLElement elt)` Scans an XML element.
`protected void` `scanIdentifier(java.lang.StringBuffer result)` Scans an identifier from the current reader.
`protected void` `scanPCData(java.lang.StringBuffer data)` Scans a #PCDATA element.
`protected void` `scanString(java.lang.StringBuffer string)` This method scans a delimited string from the current reader.
`protected char` `scanWhitespace()` This method scans an identifier from the current reader.
`protected char` `scanWhitespace(java.lang.StringBuffer result)` This method scans an identifier from the current reader.
`void` `setAttribute(java.lang.String name, java.lang.Object value)` Adds or modifies an attribute.
`void` `setContent(java.lang.String content)` Changes the content string.
`void` `setName(java.lang.String name)` Changes the name of the element.
`protected void` `skipComment()` Skips a comment.
`protected void` `skipSpecialTag(int bracketLevel)` Skips a special tag or comment.
`protected XMLParseException` `syntaxError(java.lang.String context)` Creates a parse exception for when a syntax error occured.
`protected XMLParseException` `unexpectedEndOfData()` Creates a parse exception for when the end of the data input has been reached.
`protected XMLParseException` `unknownEntity(java.lang.String name)` Creates a parse exception for when an entity could not be resolved.
`protected void` `unreadChar(char ch)` Pushes a character back to the read-back buffer.

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

Constructor Detail

### XMLElement

    public XMLElement()

  Creates and initializes a new XML element. Calling the construction is equivalent to:
  `new XMLElement(new Hashtable(), false, true)`
  Postconditions:
    - countChildren() => 0
    - enumerateChildren() => empty enumeration
    - enumeratePropertyNames() => empty enumeration
    - getChildren() => empty vector
    - getContent() => ""
    - getLineNr() => 0
    - getName() => null

### XMLElement

    protected XMLElement(java.util.Hashtable<java.lang.String,char[]> entities,
                         boolean skipLeadingWhitespace,
                         boolean fillBasicConversionTable,
                         boolean ignoreCase)

  Creates and initializes a new XML element.

  This constructor should only be called from `createAnotherElement` to create child elements.

  Parameters:
    `entities` - The entity conversion table.
    `skipLeadingWhitespace` - `true` if leading and trailing whitespace in PCDATA content has to be removed.
    `fillBasicConversionTable` - `true` if the basic entities need to be added to the entity list (client code calling this constructor).
    `ignoreCase` - `true` if the case of element and attribute names have to be ignored.
  Preconditions:
    - `entities != null`
    - if `fillBasicConversionTable == false` then `entities` contains at least the following entries: `amp`, `lt`, `gt`, `apos` and `quot`
  Postconditions:
    - countChildren() => 0
    - enumerateChildren() => empty enumeration
    - enumeratePropertyNames() => empty enumeration
    - getChildren() => empty vector
    - getContent() => ""
    - getLineNr() => 0
    - getName() => null

Method Detail

### addChild

    public void addChild(XMLElement child)

  Adds a child element.

  Parameters:
    `child` - The child element to add.
  Preconditions:
    - `child != null`
    - `child.getName() != null`
    - `child` does not have a parent element
  Postconditions:
    - countChildren() => old.countChildren() + 1
    - enumerateChildren() => old.enumerateChildren() + child
    - getChildren() => old.enumerateChildren() + child

### setAttribute

    public void setAttribute(java.lang.String name,
                             java.lang.Object value)

  Adds or modifies an attribute.

  Parameters:
    `name` - The name of the attribute.
    `value` - The value of the attribute.
  Preconditions:
    - `name != null`
    - `name` is a valid XML identifier
    - `value != null`
  Postconditions:
    - enumerateAttributeNames() => old.enumerateAttributeNames() + name
    - getAttribute(name) => value

### countChildren

    public int countChildren()

  Returns the number of child elements of the element.
  Postconditions:
    - `result >= 0`

### enumerateAttributeNames

    public java.util.Enumeration enumerateAttributeNames()

  Enumerates the attribute names.
  Postconditions:
    - `result != null`

### enumerateChildren

    public java.util.Enumeration enumerateChildren()

  Enumerates the child elements.
  Postconditions:
    - `result != null`

### getContent

    public java.lang.String getContent()

  Returns the PCDATA content of the object. If there is no such content, `null` is returned.

### getLineNr

    public int getLineNr()

  Returns the line nr in the source data on which the element is found. This method returns `0` there is no associated source data.
  Postconditions:
    - `result >= 0`

### getAttribute

    public java.lang.Object getAttribute(java.lang.String name)

  Returns an attribute of the element. If the attribute doesn't exist, `null` is returned.

  Parameters:
    `name` - The name of the attribute.
  Preconditions:
    - `name != null`
    - `name` is a valid XML identifier

### getName

    public java.lang.String getName()

  Returns the name of the element.

### parseFromReader

    public void parseFromReader(java.io.Reader reader)
                         throws java.io.IOException,
                                XMLParseException

  Reads one XML element from a java.io.Reader and parses it.

  Parameters:
    `reader` - The reader from which to retrieve the XML data.
  Preconditions:
    - `reader != null`
    - `reader` is not closed
  Postconditions:
    - the state of the receiver is updated to reflect the XML element parsed from the reader
    - the reader points to the first character following the last '>' character of the XML element
  Throws:
    `java.io.IOException` - If an error occured while reading the input.
    `XMLParseException` - If an error occured while parsing the read data.

### parseFromReader

    public void parseFromReader(java.io.Reader reader,
                                int startingLineNr)
                         throws java.io.IOException,
                                XMLParseException

  Reads one XML element from a java.io.Reader and parses it.

  Parameters:
    `reader` - The reader from which to retrieve the XML data.
    `startingLineNr` - The line number of the first line in the data.
  Preconditions:
    - `reader != null`
    - `reader` is not closed
  Postconditions:
    - the state of the receiver is updated to reflect the XML element parsed from the reader
    - the reader points to the first character following the last '>' character of the XML element
  Throws:
    `java.io.IOException` - If an error occured while reading the input.
    `XMLParseException` - If an error occured while parsing the read data.

### createAnotherElement

    protected XMLElement createAnotherElement()

  Creates a new similar XML element.

  You should override this method when subclassing XMLElement.

### setContent

    public void setContent(java.lang.String content)

  Changes the content string.

  Parameters:
    `content` - The new content string.

### setName

    public void setName(java.lang.String name)

  Changes the name of the element.

  Parameters:
    `name` - The new name.
  Preconditions:
    - `name != null`
    - `name` is a valid XML identifier

### scanIdentifier

    protected void scanIdentifier(java.lang.StringBuffer result)
                           throws java.io.IOException

  Scans an identifier from the current reader. The scanned identifier is appended to `result`.

  Parameters:
    `result` - The buffer in which the scanned identifier will be put.
  Preconditions:
    - `result != null`
    - The next character read from the reader is a valid first character of an XML identifier.
  Postconditions:
    - The next character read from the reader won't be an identifier character.
  Throws:
    `java.io.IOException`

### scanWhitespace

    protected char scanWhitespace()
                           throws java.io.IOException

  This method scans an identifier from the current reader.

  Returns:
    the next character following the whitespace.
  Throws:
    `java.io.IOException`

### scanWhitespace

    protected char scanWhitespace(java.lang.StringBuffer result)
                           throws java.io.IOException

  This method scans an identifier from the current reader. The scanned whitespace is appended to `result`.

  Returns:
    the next character following the whitespace.
  Preconditions:
    - `result != null`
Throws:
  `java.io.IOException`

### scanString

    protected void scanString(java.lang.StringBuffer string)
                       throws java.io.IOException

  This method scans a delimited string from the current reader. The scanned string without delimiters is appended to `string`.

Preconditions:
  - `string != null`
  - the next char read is the string delimiter

  Throws:
    `java.io.IOException`

### scanPCData

    protected void scanPCData(java.lang.StringBuffer data)
                       throws java.io.IOException

  Scans a #PCDATA element. CDATA sections and entities are resolved. The next < char is skipped. The scanned data is appended to `data`.

Preconditions:
  - `data != null`

  Throws:
    `java.io.IOException`

### checkCDATA

    protected boolean checkCDATA(java.lang.StringBuffer buf)
                          throws java.io.IOException

  Scans a special tag and if the tag is a CDATA section, append its content to `buf`.

Preconditions:
  - `buf != null`
  - The first < has already been read.

  Throws:
    `java.io.IOException`

### skipComment

    protected void skipComment()
                        throws java.io.IOException

  Skips a comment.

Preconditions:
  - The first <!-- has already been read.

  Throws:
    `java.io.IOException`

### skipSpecialTag

    protected void skipSpecialTag(int bracketLevel)
                           throws java.io.IOException

  Skips a special tag or comment.

  Parameters:
    `bracketLevel` - The number of open square brackets ([) that have already been read.
  Preconditions:
    - The first <! has already been read.
    - `bracketLevel >= 0`
Throws:
  `java.io.IOException`

### checkLiteral

    protected boolean checkLiteral(java.lang.String literal)
                            throws java.io.IOException

  Scans the data for literal text. Scanning stops when a character does not match or after the complete text has been checked, whichever comes first.

  Parameters:
    `literal` - the literal to check.
  Preconditions:
    - `literal != null`
Throws:
  `java.io.IOException`

### readChar

    protected char readChar()
                     throws java.io.IOException

  Reads a character from a reader.

  Throws:
    `java.io.IOException`

### scanElement

    protected void scanElement(XMLElement elt)
                        throws java.io.IOException

  Scans an XML element.

  Parameters:
    `elt` - The element that will contain the result.
  Preconditions:
    - The first < has already been read.
    - `elt != null`
Throws:
  `java.io.IOException`

### resolveEntity

    protected void resolveEntity(java.lang.StringBuffer buf)
                          throws java.io.IOException

  Resolves an entity. The name of the entity is read from the reader. The value of the entity is appended to `buf`.

  Parameters:
    `buf` - Where to put the entity value.
  Preconditions:
    - The first & has already been read.
    - `buf != null`
Throws:
  `java.io.IOException`

### unreadChar

    protected void unreadChar(char ch)

  Pushes a character back to the read-back buffer.

  Parameters:
    `ch` - The character to push back.
  Preconditions:
    - The read-back buffer is empty.
    - `ch != '\0'`

### invalidValueSet

    protected XMLParseException invalidValueSet(java.lang.String name)

  Creates a parse exception for when an invalid valueset is given to a method.

  Parameters:
    `name` - The name of the entity.
  Preconditions:
    - `name != null`

### invalidValue

    protected XMLParseException invalidValue(java.lang.String name,
                                             java.lang.String value)

  Creates a parse exception for when an invalid value is given to a method.

  Parameters:
    `name` - The name of the entity.
    `value` - The value of the entity.
  Preconditions:
    - `name != null`
    - `value != null`

### unexpectedEndOfData

    protected XMLParseException unexpectedEndOfData()

  Creates a parse exception for when the end of the data input has been reached.

### syntaxError

    protected XMLParseException syntaxError(java.lang.String context)

  Creates a parse exception for when a syntax error occured.

  Parameters:
    `context` - The context in which the error occured.
  Preconditions:
    - `context != null`
    - `context.length() > 0`

### expectedInput

    protected XMLParseException expectedInput(java.lang.String charSet)

  Creates a parse exception for when the next character read is not the character that was expected.

  Parameters:
    `charSet` - The set of characters (in human readable form) that was expected.
  Preconditions:
    - `charSet != null`
    - `charSet.length() > 0`

### expectedInput

    protected XMLParseException expectedInput(java.lang.String charSet,
                                              char ch)

  Creates a parse exception for when the next character read is not the character that was expected.

  Parameters:
    `charSet` - The set of characters (in human readable form) that was expected.
    `ch` - The character that was received instead.
  Preconditions:
    - `charSet != null`
    - `charSet.length() > 0`

### unknownEntity

    protected XMLParseException unknownEntity(java.lang.String name)

  Creates a parse exception for when an entity could not be resolved.

  Parameters:
    `name` - The name of the entity.
  Preconditions:
    - `name != null`
    - `name.length() > 0`

### sanitizeInput

    public void sanitizeInput(java.io.Reader isr,
                              java.io.OutputStream pout)

  Reads an xml file and removes the comments, leaving only relevant xml code.

  Parameters:
    `isr` - The reader of the InputStream containing the xml.
    `pout` - The PipedOutputStream that will be receiving the filtered xml file.

IcedTea-Web NetX

Submit a bug or feature