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.

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.