Class 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

      Constructors 
      Modifier Constructor Description
        XMLElement()
      Creates and initializes a new XML element.
      protected XMLElement​(java.util.Map<java.lang.String,​char[]> entities, boolean skipLeadingWhitespace, boolean fillBasicConversionTable, boolean ignoreCase)
      Creates and initializes a new XML element.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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()  
      protected XMLElement createAnotherElement()
      Creates a new similar XML element.
      java.util.Enumeration<java.lang.String> enumerateAttributeNames()  
      java.util.Enumeration<XMLElement> enumerateChildren()  
      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)  
      java.lang.String getContent()  
      int getLineNr()  
      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.
      boolean isBOM()  
      void parseFromReader​(java.io.Reader reader)
      Reads one XML element from a 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​(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 HashMap(), false, true)
        Postconditions:
      • XMLElement

        protected XMLElement​(java.util.Map<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:
    • 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:
      • 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:
      • countChildren

        public int countChildren()
        Returns:
        the number of child elements of the element.
        Postconditions:
        • result >= 0
      • enumerateAttributeNames

        public java.util.Enumeration<java.lang.String> enumerateAttributeNames()
        Returns:
        Enumeration of the attribute names.
        Postconditions:
        • result != null
      • enumerateChildren

        public java.util.Enumeration<XMLElement> enumerateChildren()
        Returns:
        Enumeration 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)
        Parameters:
        name - The name of the attribute.
        Preconditions:
        • name != null
        • name is a valid XML identifier
        Returns:
        an attribute of the element.

        If the attribute doesn't exist, null is returned.

      • getName

        public java.lang.String getName()
        Returns the name of the element.
        Returns:
        this XMLElement object's name
      • parseFromReader

        public void parseFromReader​(java.io.Reader reader)
                             throws java.io.IOException,
                                    XMLParseException
        Reads one XML element from a 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 '&gt;' 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 '&gt;' 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.

        Returns:
        next element in tree based on global settings
      • 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 - if something goes wrong
      • 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.

        Parameters:
        result - where to append scanned text
        Returns:
        the next character following the whitespace.
        Preconditions:
        • result != null
        Throws:
        java.io.IOException - if something goes wrong
      • 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
        Parameters:
        string - where to append the result
        Throws:
        java.io.IOException - if something goes wrong
      • 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
        Parameters:
        data - where to append data
        Throws:
        java.io.IOException - if something goes wrong
      • 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.
        Parameters:
        buf - buffer where to append data
        Returns:
        whether the CDATA were ok
        Throws:
        java.io.IOException - if something goes wrong
      • skipComment

        protected void skipComment()
                            throws java.io.IOException
        Skips a comment.
        Preconditions:
        • The first <!-- has already been read.
        Throws:
        java.io.IOException - if something goes wrong
      • 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 &gt;= 0
        Throws:
        java.io.IOException - if something goes wrong
      • 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
        Returns:
        true if literal was ok
        Throws:
        java.io.IOException - if something goes wrong
      • readChar

        protected char readChar()
                         throws java.io.IOException
        Reads a character from a reader.
        Returns:
        the read char
        Throws:
        java.io.IOException - if something goes wrong
      • 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 - if something goes wrong
      • 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 - if something goes wrong
      • 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
        Returns:
        exception to be thrown
      • 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
        Returns:
        exception to be used
      • unexpectedEndOfData

        protected XMLParseException unexpectedEndOfData()
        Creates a parse exception for when the end of the data input has been reached.
        Returns:
        exception to be used
      • 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() &gt; 0
        Returns:
        exception to be used
      • 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() &gt; 0
        Returns:
        exception to be used
      • 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() &gt; 0
        Returns:
        exception to be used
      • 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.
        Returns:
        exception to be used
        Preconditions:
        • name != null
        • name.length() &gt; 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.
      • isBOM

        public boolean isBOM()