## com.microstar.xml
Class XmlParser

    java.lang.Object
      com.microstar.xml.XmlParser

public class XmlParser
extends java.lang.Object

Parse XML documents and return parse events through call-backs.

You need to define a class implementing the `XmlHandler` interface: an object belonging to this class will receive the callbacks for the events. (As an alternative to implementing the full XmlHandler interface, you can simply extend the `HandlerBase` convenience class.)

Usage (assuming that `MyHandler` is your implementation of the `XmlHandler` interface):

     XmlHandler handler = new MyHandler();
     XmlParser parser = new XmlParser();
     parser.setHandler(handler);
     try {
       parser.parse("http://www.host.com/doc.xml", null);
     } catch (Exception e) {
       [do something interesting]
     }

Alternatively, you can use the standard SAX interfaces with the `SAXDriver` class as your entry point.

Version:
  1.1
Author:
  Copyright (c) 1997, 1998 by Microstar Software Ltd., Written by David Megginson <dmeggins@microstar.com>
See Also:
  `XmlHandler`, `HandlerBase`, `SAXDriver`

Field Summary
`static int` `ATTRIBUTE_CDATA` Constant: the attribute value is a string value.
`static int` `ATTRIBUTE_DEFAULT_FIXED` Constant: the attribute was declared #FIXED.
`static int` `ATTRIBUTE_DEFAULT_IMPLIED` Constant: the attribute was declared #IMPLIED.
`static int` `ATTRIBUTE_DEFAULT_REQUIRED` Constant: the attribute was declared #REQUIRED.
`static int` `ATTRIBUTE_DEFAULT_SPECIFIED` Constant: the attribute has a literal default value specified.
`static int` `ATTRIBUTE_DEFAULT_UNDECLARED` Constant: the attribute is not declared.
`static int` `ATTRIBUTE_ENTITIES` Constant: the attribute value is a list of entity names.
`static int` `ATTRIBUTE_ENTITY` Constant: the attribute value is the name of an entity.
`static int` `ATTRIBUTE_ENUMERATED` Constant: the attribute value is a token from an enumeration.
`static int` `ATTRIBUTE_ID` Constant: the attribute value is a unique identifier.
`static int` `ATTRIBUTE_IDREF` Constant: the attribute value is a reference to a unique identifier.
`static int` `ATTRIBUTE_IDREFS` Constant: the attribute value is a list of ID references.
`static int` `ATTRIBUTE_NMTOKEN` Constant: the attribute value is a name token.
`static int` `ATTRIBUTE_NMTOKENS` Constant: the attribute value is a list of name tokens.
`static int` `ATTRIBUTE_NOTATION` Constant: the attribute is the name of a notation.
`static int` `ATTRIBUTE_UNDECLARED` Constant: the attribute has not been declared for this element type.
`static int` `CONTENT_ANY` Constant: the element has a content model of ANY.
`static int` `CONTENT_ELEMENTS` Constant: the element has element content.
`static int` `CONTENT_EMPTY` Constant: the element has declared content of EMPTY.
`static int` `CONTENT_MIXED` Constant: the element has mixed content.
`static int` `CONTENT_UNDECLARED` Constant: an element has not been declared.
`static int` `ENTITY_INTERNAL` Constant: the entity is internal.
`static int` `ENTITY_NDATA` Constant: the entity is external, non-XML data.
`static int` `ENTITY_TEXT` Constant: the entity is external XML data.
`static int` `ENTITY_UNDECLARED` Constant: the entity has not been declared.

Constructor Summary
`XmlParser()` Construct a new parser with no associated handler.

Method Summary
`java.util.Enumeration` `declaredAttributes(java.lang.String elname)` Get the declared attributes for an element type.
`java.util.Enumeration` `declaredElements()` Get the declared elements for an XML document.
`java.util.Enumeration` `declaredEntities()` Get declared entities.
`java.util.Enumeration` `declaredNotations()` Get declared notations.
`java.lang.String` `getAttributeDefaultValue(java.lang.String name, java.lang.String aname)` Retrieve the default value of a declared attribute.
`int` `getAttributeDefaultValueType(java.lang.String name, java.lang.String aname)` Retrieve the default value type of a declared attribute.
`java.lang.String` `getAttributeEnumeration(java.lang.String name, java.lang.String aname)` Retrieve the allowed values for an enumerated attribute type.
`java.lang.String` `getAttributeExpandedValue(java.lang.String name, java.lang.String aname)` Retrieve the expanded value of a declared attribute.
`int` `getAttributeType(java.lang.String name, java.lang.String aname)` Retrieve the declared type of an attribute.
`int` `getColumnNumber()` Return the current column number.
`java.lang.String` `getElementContentModel(java.lang.String name)` Look up the content model of an element.
`int` `getElementContentType(java.lang.String name)` Look up the content type of an element.
`java.lang.String` `getEntityNotationName(java.lang.String eName)` Get the notation name associated with an NDATA entity.
`java.lang.String` `getEntityPublicId(java.lang.String ename)` Return an external entity's public identifier, if any.
`java.lang.String` `getEntitySystemId(java.lang.String ename)` Return an external entity's system identifier.
`int` `getEntityType(java.lang.String ename)` Find the type of an entity.
`java.lang.String` `getEntityValue(java.lang.String ename)` Return the value of an internal entity.
`int` `getLineNumber()` Return the current line number.
`java.lang.String` `getNotationPublicId(java.lang.String nname)` Look up the public identifier for a notation.
`java.lang.String` `getNotationSystemId(java.lang.String nname)` Look up the system identifier for a notation.
`java.lang.String` `intern(char[] ch, int start, int length)` Create an internalised string from a character array.
`java.lang.String` `intern(java.lang.String s)` Return an internalised version of a string.
`void` `parse(java.lang.String systemId, java.lang.String publicId, java.io.InputStream stream, java.lang.String encoding)` Parse an XML document from a byte stream.
`void` `parse(java.lang.String systemId, java.lang.String publicId, java.io.Reader reader)` Parse an XML document from a character stream.
`void` `parse(java.lang.String systemId, java.lang.String publicId, java.lang.String encoding)` Parse an XML document from a URI.
`void` `setHandler(XmlHandler handler)` Set the handler that will receive parsing events.

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

Field Detail

### CONTENT_UNDECLARED

    public static final int CONTENT_UNDECLARED

  Constant: an element has not been declared.

  See Also:
    `getElementContentType(java.lang.String)`, Constant Field Values

### CONTENT_ANY

    public static final int CONTENT_ANY

  Constant: the element has a content model of ANY.

  See Also:
    `getElementContentType(java.lang.String)`, Constant Field Values

### CONTENT_EMPTY

    public static final int CONTENT_EMPTY

  Constant: the element has declared content of EMPTY.

  See Also:
    `getElementContentType(java.lang.String)`, Constant Field Values

### CONTENT_MIXED

    public static final int CONTENT_MIXED

  Constant: the element has mixed content.

  See Also:
    `getElementContentType(java.lang.String)`, Constant Field Values

### CONTENT_ELEMENTS

    public static final int CONTENT_ELEMENTS

  Constant: the element has element content.

  See Also:
    `getElementContentType(java.lang.String)`, Constant Field Values

### ENTITY_UNDECLARED

    public static final int ENTITY_UNDECLARED

  Constant: the entity has not been declared.

  See Also:
    `getEntityType(java.lang.String)`, Constant Field Values

### ENTITY_INTERNAL

    public static final int ENTITY_INTERNAL

  Constant: the entity is internal.

  See Also:
    `getEntityType(java.lang.String)`, Constant Field Values

### ENTITY_NDATA

    public static final int ENTITY_NDATA

  Constant: the entity is external, non-XML data.

  See Also:
    `getEntityType(java.lang.String)`, Constant Field Values

### ENTITY_TEXT

    public static final int ENTITY_TEXT

  Constant: the entity is external XML data.

  See Also:
    `getEntityType(java.lang.String)`, Constant Field Values

### ATTRIBUTE_UNDECLARED

    public static final int ATTRIBUTE_UNDECLARED

  Constant: the attribute has not been declared for this element type.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_CDATA

    public static final int ATTRIBUTE_CDATA

  Constant: the attribute value is a string value.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_ID

    public static final int ATTRIBUTE_ID

  Constant: the attribute value is a unique identifier.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_IDREF

    public static final int ATTRIBUTE_IDREF

  Constant: the attribute value is a reference to a unique identifier.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_IDREFS

    public static final int ATTRIBUTE_IDREFS

  Constant: the attribute value is a list of ID references.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_ENTITY

    public static final int ATTRIBUTE_ENTITY

  Constant: the attribute value is the name of an entity.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_ENTITIES

    public static final int ATTRIBUTE_ENTITIES

  Constant: the attribute value is a list of entity names.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_NMTOKEN

    public static final int ATTRIBUTE_NMTOKEN

  Constant: the attribute value is a name token.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_NMTOKENS

    public static final int ATTRIBUTE_NMTOKENS

  Constant: the attribute value is a list of name tokens.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_ENUMERATED

    public static final int ATTRIBUTE_ENUMERATED

  Constant: the attribute value is a token from an enumeration.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_NOTATION

    public static final int ATTRIBUTE_NOTATION

  Constant: the attribute is the name of a notation.

  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_DEFAULT_UNDECLARED

    public static final int ATTRIBUTE_DEFAULT_UNDECLARED

  Constant: the attribute is not declared.

  See Also:
    `getAttributeDefaultValueType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_DEFAULT_SPECIFIED

    public static final int ATTRIBUTE_DEFAULT_SPECIFIED

  Constant: the attribute has a literal default value specified.

  See Also:
    `getAttributeDefaultValueType(java.lang.String, java.lang.String)`, `getAttributeDefaultValue(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_DEFAULT_IMPLIED

    public static final int ATTRIBUTE_DEFAULT_IMPLIED

  Constant: the attribute was declared #IMPLIED.

  See Also:
    `getAttributeDefaultValueType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_DEFAULT_REQUIRED

    public static final int ATTRIBUTE_DEFAULT_REQUIRED

  Constant: the attribute was declared #REQUIRED.

  See Also:
    `getAttributeDefaultValueType(java.lang.String, java.lang.String)`, Constant Field Values

### ATTRIBUTE_DEFAULT_FIXED

    public static final int ATTRIBUTE_DEFAULT_FIXED

  Constant: the attribute was declared #FIXED.

  See Also:
    `getAttributeDefaultValueType(java.lang.String, java.lang.String)`, `getAttributeDefaultValue(java.lang.String, java.lang.String)`, Constant Field Values

Constructor Detail

### XmlParser

    public XmlParser()

  Construct a new parser with no associated handler.

See Also:
  `setHandler(com.microstar.xml.XmlHandler)`, `parse(java.lang.String, java.lang.String, java.lang.String)`

Method Detail

### setHandler

    public void setHandler(XmlHandler handler)

  Set the handler that will receive parsing events.

  Parameters:
    `handler` - The handler to receive callback events.
  See Also:
    `parse(java.lang.String, java.lang.String, java.lang.String)`, `XmlHandler`

### parse

    public void parse(java.lang.String systemId,
                      java.lang.String publicId,
                      java.lang.String encoding)
               throws java.lang.Exception

  Parse an XML document from a URI.

  You may parse a document more than once, but only one thread may call this method for an object at one time.

  Parameters:
    `systemId` - The URI of the document.
    `publicId` - The public identifier of the document, or null.
    `encoding` - The suggested encoding, or null if unknown.
  Throws:
    `java.lang.Exception` - Any exception thrown by your own handlers, or any derivation of java.io.IOException thrown by the parser itself.

### parse

    public void parse(java.lang.String systemId,
                      java.lang.String publicId,
                      java.io.InputStream stream,
                      java.lang.String encoding)
               throws java.lang.Exception

  Parse an XML document from a byte stream.

  The URI that you supply will become the base URI for resolving relative links, but Ælfred will actually read the document from the supplied input stream.

  You may parse a document more than once, but only one thread may call this method for an object at one time.

  Parameters:
    `systemId` - The base URI of the document, or null if not known.
    `publicId` - The public identifier of the document, or null if not known.
    `stream` - A byte input stream.
    `encoding` - The suggested encoding, or null if unknown.
  Throws:
    `java.lang.Exception` - Any exception thrown by your own handlers, or any derivation of java.io.IOException thrown by the parser itself.

### parse

    public void parse(java.lang.String systemId,
                      java.lang.String publicId,
                      java.io.Reader reader)
               throws java.lang.Exception

  Parse an XML document from a character stream.

  The URI that you supply will become the base URI for resolving relative links, but Ælfred will actually read the document from the supplied input stream.

  You may parse a document more than once, but only one thread may call this method for an object at one time.

  Parameters:
    `systemId` - The base URI of the document, or null if not known.
    `publicId` - The public identifier of the document, or null if not known.
    `reader` - A character stream.
  Throws:
    `java.lang.Exception` - Any exception thrown by your own handlers, or any derivation of java.io.IOException thrown by the parser itself.

### intern

    public java.lang.String intern(java.lang.String s)

  Return an internalised version of a string.

  Ælfred uses this method to create an internalised version of all names and attribute values, so that it can test equality with `==` instead of `String.equals()`.

  If you want to be able to test for equality in the same way, you can use this method to internalise your own strings first:

       String PARA = handler.intern("PARA");

  Note that this will not return the same results as String.intern().

  Parameters:
    `s` - The string to internalise.
  Returns:
    An internalised version of the string.
  See Also:
    `intern(char[],int,int)`, `String.intern()`

### intern

    public java.lang.String intern(char[] ch,
                                   int start,
                                   int length)

  Create an internalised string from a character array.

  This is much more efficient than constructing a non-internalised string first, and then internalising it.

  Note that this will not return the same results as String.intern().

  Parameters:
    `ch` - an array of characters for building the string.
    `start` - the starting position in the array.
    `length` - the number of characters to place in the string.
  Returns:
    an internalised string.
  See Also:
    `intern(String)`, `String.intern()`

### declaredElements

    public java.util.Enumeration declaredElements()

  Get the declared elements for an XML document.

  The results will be valid only after the DTD (if any) has been parsed.

  Returns:
    An enumeration of all element types declared for this document (as Strings).
  See Also:
    `getElementContentType(java.lang.String)`, `getElementContentModel(java.lang.String)`

### getElementContentType

    public int getElementContentType(java.lang.String name)

  Look up the content type of an element.

  Parameters:
    `name` - The element type name.
  Returns:
    An integer constant representing the content type.
  See Also:
    `getElementContentModel(java.lang.String)`, `CONTENT_UNDECLARED`, `CONTENT_ANY`, `CONTENT_EMPTY`, `CONTENT_MIXED`, `CONTENT_ELEMENTS`

### getElementContentModel

    public java.lang.String getElementContentModel(java.lang.String name)

  Look up the content model of an element.

  The result will always be null unless the content type is CONTENT_ELEMENTS or CONTENT_MIXED.

  Parameters:
    `name` - The element type name.
  Returns:
    The normalised content model, as a string.
  See Also:
    `getElementContentType(java.lang.String)`

### declaredAttributes

    public java.util.Enumeration declaredAttributes(java.lang.String elname)

  Get the declared attributes for an element type.

  Parameters:
    `elname` - The name of the element type.
  Returns:
    An Enumeration of all the attributes declared for a specific element type. The results will be valid only after the DTD (if any) has been parsed.
  See Also:
    `getAttributeType(java.lang.String, java.lang.String)`, `getAttributeEnumeration(java.lang.String, java.lang.String)`, `getAttributeDefaultValueType(java.lang.String, java.lang.String)`, `getAttributeDefaultValue(java.lang.String, java.lang.String)`, `getAttributeExpandedValue(java.lang.String, java.lang.String)`

### getAttributeType

    public int getAttributeType(java.lang.String name,
                                java.lang.String aname)

  Retrieve the declared type of an attribute.

  Parameters:
    `name` - The name of the associated element.
    `aname` - The name of the attribute.
  Returns:
    An integer constant representing the attribute type.
  See Also:
    `ATTRIBUTE_UNDECLARED`, `ATTRIBUTE_CDATA`, `ATTRIBUTE_ID`, `ATTRIBUTE_IDREF`, `ATTRIBUTE_IDREFS`, `ATTRIBUTE_ENTITY`, `ATTRIBUTE_ENTITIES`, `ATTRIBUTE_NMTOKEN`, `ATTRIBUTE_NMTOKENS`, `ATTRIBUTE_ENUMERATED`, `ATTRIBUTE_NOTATION`

### getAttributeEnumeration

    public java.lang.String getAttributeEnumeration(java.lang.String name,
                                                    java.lang.String aname)

  Retrieve the allowed values for an enumerated attribute type.

  Parameters:
    `name` - The name of the associated element.
    `aname` - The name of the attribute.
  Returns:
    A string containing the token list.
  See Also:
    `ATTRIBUTE_ENUMERATED`, `ATTRIBUTE_NOTATION`

### getAttributeDefaultValue

    public java.lang.String getAttributeDefaultValue(java.lang.String name,
                                                     java.lang.String aname)

  Retrieve the default value of a declared attribute.

  Parameters:
    `name` - The name of the associated element.
    `aname` - The name of the attribute.
  Returns:
    The default value, or null if the attribute was #IMPLIED or simply undeclared and unspecified.
  See Also:
    `getAttributeExpandedValue(java.lang.String, java.lang.String)`

### getAttributeExpandedValue

    public java.lang.String getAttributeExpandedValue(java.lang.String name,
                                                      java.lang.String aname)

  Retrieve the expanded value of a declared attribute.

  All general entities will be expanded.

  Parameters:
    `name` - The name of the associated element.
    `aname` - The name of the attribute.
  Returns:
    The expanded default value, or null if the attribute was #IMPLIED or simply undeclared
  See Also:
    `getAttributeDefaultValue(java.lang.String, java.lang.String)`

### getAttributeDefaultValueType

    public int getAttributeDefaultValueType(java.lang.String name,
                                            java.lang.String aname)

  Retrieve the default value type of a declared attribute.

  See Also:
    `ATTRIBUTE_DEFAULT_SPECIFIED`, `ATTRIBUTE_DEFAULT_IMPLIED`, `ATTRIBUTE_DEFAULT_REQUIRED`, `ATTRIBUTE_DEFAULT_FIXED`

### declaredEntities

    public java.util.Enumeration declaredEntities()

  Get declared entities.

  Returns:
    An Enumeration of all the entities declared for this XML document. The results will be valid only after the DTD (if any) has been parsed.
  See Also:
    `getEntityType(java.lang.String)`, `getEntityPublicId(java.lang.String)`, `getEntitySystemId(java.lang.String)`, `getEntityValue(java.lang.String)`, `getEntityNotationName(java.lang.String)`

### getEntityType

    public int getEntityType(java.lang.String ename)

  Find the type of an entity.

  See Also:
    `ENTITY_UNDECLARED`, `ENTITY_INTERNAL`, `ENTITY_NDATA`, `ENTITY_TEXT`

### getEntityPublicId

    public java.lang.String getEntityPublicId(java.lang.String ename)

  Return an external entity's public identifier, if any.

  Parameters:
    `ename` - The name of the external entity.
  Returns:
    The entity's system identifier, or null if the entity was not declared, if it is not an external entity, or if no public identifier was provided.
  See Also:
    `getEntityType(java.lang.String)`

### getEntitySystemId

    public java.lang.String getEntitySystemId(java.lang.String ename)

  Return an external entity's system identifier.

  Parameters:
    `ename` - The name of the external entity.
  Returns:
    The entity's system identifier, or null if the entity was not declared, or if it is not an external entity.
  See Also:
    `getEntityType(java.lang.String)`

### getEntityValue

    public java.lang.String getEntityValue(java.lang.String ename)

  Return the value of an internal entity.

  Parameters:
    `ename` - The name of the internal entity.
  Returns:
    The entity's value, or null if the entity was not declared, or if it is not an internal entity.
  See Also:
    `getEntityType(java.lang.String)`

### getEntityNotationName

    public java.lang.String getEntityNotationName(java.lang.String eName)

  Get the notation name associated with an NDATA entity.

  Returns:
    The associated notation name, or null if the entity was not declared, or if it is not an NDATA entity.
  See Also:
    `getEntityType(java.lang.String)`

### declaredNotations

    public java.util.Enumeration declaredNotations()

  Get declared notations.

  Returns:
    An Enumeration of all the notations declared for this XML document. The results will be valid only after the DTD (if any) has been parsed.
  See Also:
    `getNotationPublicId(java.lang.String)`, `getNotationSystemId(java.lang.String)`

### getNotationPublicId

    public java.lang.String getNotationPublicId(java.lang.String nname)

  Look up the public identifier for a notation. You will normally use this method to look up a notation that was provided as an attribute value or for an NDATA entity.

  Parameters:
    `nname` - The name of the notation.
  Returns:
    A string containing the public identifier, or null if none was provided or if no such notation was declared.
  See Also:
    `getNotationSystemId(java.lang.String)`

### getNotationSystemId

    public java.lang.String getNotationSystemId(java.lang.String nname)

  Look up the system identifier for a notation. You will normally use this method to look up a notation that was provided as an attribute value or for an NDATA entity.

  Parameters:
    `nname` - The name of the notation.
  Returns:
    A string containing the system identifier, or null if no such notation was declared.
  See Also:
    `getNotationPublicId(java.lang.String)`

### getLineNumber

    public int getLineNumber()

  Return the current line number.

### getColumnNumber

    public int getColumnNumber()

  Return the current column number.