All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.microstar.xml.XmlParser

java.lang.Object
   |
   +----com.microstar.xml.XmlParser

public class XmlParser
extends 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

Variable Index

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

Constructor Index

 o XmlParser()
Construct a new parser with no associated handler.

Method Index

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

Variables

 o CONTENT_UNDECLARED
 public static final int CONTENT_UNDECLARED
Constant: an element has not been declared.

See Also:
getElementContentType
 o CONTENT_ANY
 public static final int CONTENT_ANY
Constant: the element has a content model of ANY.

See Also:
getElementContentType
 o CONTENT_EMPTY
 public static final int CONTENT_EMPTY
Constant: the element has declared content of EMPTY.

See Also:
getElementContentType
 o CONTENT_MIXED
 public static final int CONTENT_MIXED
Constant: the element has mixed content.

See Also:
getElementContentType
 o CONTENT_ELEMENTS
 public static final int CONTENT_ELEMENTS
Constant: the element has element content.

See Also:
getElementContentType
 o ENTITY_UNDECLARED
 public static final int ENTITY_UNDECLARED
Constant: the entity has not been declared.

See Also:
getEntityType
 o ENTITY_INTERNAL
 public static final int ENTITY_INTERNAL
Constant: the entity is internal.

See Also:
getEntityType
 o ENTITY_NDATA
 public static final int ENTITY_NDATA
Constant: the entity is external, non-XML data.

See Also:
getEntityType
 o ENTITY_TEXT
 public static final int ENTITY_TEXT
Constant: the entity is external XML data.

See Also:
getEntityType
 o ATTRIBUTE_UNDECLARED
 public static final int ATTRIBUTE_UNDECLARED
Constant: the attribute has not been declared for this element type.

See Also:
getAttributeType
 o ATTRIBUTE_CDATA
 public static final int ATTRIBUTE_CDATA
Constant: the attribute value is a string value.

See Also:
getAttributeType
 o ATTRIBUTE_ID
 public static final int ATTRIBUTE_ID
Constant: the attribute value is a unique identifier.

See Also:
getAttributeType
 o ATTRIBUTE_IDREF
 public static final int ATTRIBUTE_IDREF
Constant: the attribute value is a reference to a unique identifier.

See Also:
getAttributeType
 o ATTRIBUTE_IDREFS
 public static final int ATTRIBUTE_IDREFS
Constant: the attribute value is a list of ID references.

See Also:
getAttributeType
 o ATTRIBUTE_ENTITY
 public static final int ATTRIBUTE_ENTITY
Constant: the attribute value is the name of an entity.

See Also:
getAttributeType
 o ATTRIBUTE_ENTITIES
 public static final int ATTRIBUTE_ENTITIES
Constant: the attribute value is a list of entity names.

See Also:
getAttributeType
 o ATTRIBUTE_NMTOKEN
 public static final int ATTRIBUTE_NMTOKEN
Constant: the attribute value is a name token.

See Also:
getAttributeType
 o ATTRIBUTE_NMTOKENS
 public static final int ATTRIBUTE_NMTOKENS
Constant: the attribute value is a list of name tokens.

See Also:
getAttributeType
 o ATTRIBUTE_ENUMERATED
 public static final int ATTRIBUTE_ENUMERATED
Constant: the attribute value is a token from an enumeration.

See Also:
getAttributeType
 o ATTRIBUTE_NOTATION
 public static final int ATTRIBUTE_NOTATION
Constant: the attribute is the name of a notation.

See Also:
getAttributeType
 o ATTRIBUTE_DEFAULT_UNDECLARED
 public static final int ATTRIBUTE_DEFAULT_UNDECLARED
Constant: the attribute is not declared.

See Also:
getAttributeDefaultValueType
 o ATTRIBUTE_DEFAULT_SPECIFIED
 public static final int ATTRIBUTE_DEFAULT_SPECIFIED
Constant: the attribute has a literal default value specified.

See Also:
getAttributeDefaultValueType, getAttributeDefaultValue
 o ATTRIBUTE_DEFAULT_IMPLIED
 public static final int ATTRIBUTE_DEFAULT_IMPLIED
Constant: the attribute was declared #IMPLIED.

See Also:
getAttributeDefaultValueType
 o ATTRIBUTE_DEFAULT_REQUIRED
 public static final int ATTRIBUTE_DEFAULT_REQUIRED
Constant: the attribute was declared #REQUIRED.

See Also:
getAttributeDefaultValueType
 o ATTRIBUTE_DEFAULT_FIXED
 public static final int ATTRIBUTE_DEFAULT_FIXED
Constant: the attribute was declared #FIXED.

See Also:
getAttributeDefaultValueType, getAttributeDefaultValue

Constructors

 o XmlParser
 public XmlParser()
Construct a new parser with no associated handler.

See Also:
setHandler, parse

Methods

 o 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, XmlHandler
 o parse
 public void parse(String systemId,
                   String publicId,
                   String encoding) throws 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: Exception
Any exception thrown by your own handlers, or any derivation of java.io.IOException thrown by the parser itself.
 o parse
 public void parse(String systemId,
                   String publicId,
                   InputStream stream,
                   String encoding) throws 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: Exception
Any exception thrown by your own handlers, or any derivation of java.io.IOException thrown by the parser itself.
 o parse
 public void parse(String systemId,
                   String publicId,
                   Reader reader) throws 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: Exception
Any exception thrown by your own handlers, or any derivation of java.io.IOException thrown by the parser itself.
 o intern
 public String intern(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, intern
 o intern
 public 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, intern
 o declaredElements
 public 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, getElementContentModel
 o getElementContentType
 public int getElementContentType(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, CONTENT_UNDECLARED, CONTENT_ANY, CONTENT_EMPTY, CONTENT_MIXED, CONTENT_ELEMENTS
 o getElementContentModel
 public String getElementContentModel(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
 o declaredAttributes
 public Enumeration declaredAttributes(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, getAttributeEnumeration, getAttributeDefaultValueType, getAttributeDefaultValue, getAttributeExpandedValue
 o getAttributeType
 public int getAttributeType(String name,
                             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
 o getAttributeEnumeration
 public String getAttributeEnumeration(String name,
                                       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
 o getAttributeDefaultValue
 public String getAttributeDefaultValue(String name,
                                        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
 o getAttributeExpandedValue
 public String getAttributeExpandedValue(String name,
                                         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
 o getAttributeDefaultValueType
 public int getAttributeDefaultValueType(String name,
                                         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
 o declaredEntities
 public 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, getEntityPublicId, getEntitySystemId, getEntityValue, getEntityNotationName
 o getEntityType
 public int getEntityType(String ename)
Find the type of an entity.

Returns:
s An integer constant representing the entity type.
See Also:
ENTITY_UNDECLARED, ENTITY_INTERNAL, ENTITY_NDATA, ENTITY_TEXT
 o getEntityPublicId
 public String getEntityPublicId(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
 o getEntitySystemId
 public String getEntitySystemId(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
 o getEntityValue
 public String getEntityValue(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
 o getEntityNotationName
 public String getEntityNotationName(String eName)
Get the notation name associated with an NDATA entity.

Parameters:
ename - The NDATA entity name.
Returns:
The associated notation name, or null if the entity was not declared, or if it is not an NDATA entity.
See Also:
getEntityType
 o declaredNotations
 public 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, getNotationSystemId
 o getNotationPublicId
 public String getNotationPublicId(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
 o getNotationSystemId
 public String getNotationSystemId(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
 o getLineNumber
 public int getLineNumber()
Return the current line number.

 o getColumnNumber
 public int getColumnNumber()
Return the current column number.


All Packages  Class Hierarchy  This Package  Previous  Next  Index