IP*Works!

ipworks
Class Xmlp

java.lang.Object
  |
  +--ipworks.Xmlp

public class Xmlp
extends java.lang.Object

The XMLp control implements a SAX2-compliant XML parser used to parse and verify the structure of XML documents.

The XMLp control parses XML documents and verifies that they are well-formed. The results are provided through a set of events complying with the SAX2 specification.

In addition, the document structure may be queried through an XPath mechanism that supports a subset of the XPath specification.

The parser is optimized for read applications, with a very fast engine that builds internal DOM structures with close to zero heap allocations.

The control takes pieces of XML code through the InputText property or the Input method, until Flush is called or FlushText is set to True. The document is parsed and fires events like StartElement , EndElement , Characters , IgnorableWhitespace , PI , etc. Entities are evaluated inside the EvalEntity event. If BuildDOM is set to True, an internal DOM structure is created, which in turn enables properties such as XPath , XElement , XText , etc.. which allow traversal of the document structure.

When XPath is set to a valid path, XElement points to the name of the element, with XParent , XNamespace , XPrefix , XChildren;, and XText providing other properties of the element. The attribute arrays ( AttrName , AttrValue , AttrNamespace , etc..) provide the attributes of the current element.

An additional "relaxed" mode allows for lexical parsing of non-XML documents (e.g. HTML). This is enabled by setting Validate to False. In this case, events will be fired as elements, entities, etc.. are encountered, but the structure of the document will not be checked for "well-formedness", and the internal DOM structure will not be built.


Constructor Summary
Xmlp()
           
 
Method Summary
 void addXmlpEventListener(XmlpEventListener l)
           
 java.lang.String attr(java.lang.String attrName)
          Returns the value of the specified attribute.
 void fireCharacters(byte[] text)
          Fired for plain text segments of the input stream.
 void fireComment(java.lang.String text)
          Fired when a comment section is encountered.
 void fireEndElement(java.lang.String namespace, java.lang.String element, java.lang.String QName, boolean isEmpty)
          Fired when an end-element tag is encountered.
 void fireEndPrefixMapping(java.lang.String prefix)
          Fired when leaving the scope of a namespace declaration.
 void fireError(int errorCode, java.lang.String description)
          Information about errors during data delivery.
 void fireEvalEntity(java.lang.String entity, java.lang.String value)
          Fired every time an entity needs to be evaluated.
 void fireIgnorableWhitespace(java.lang.String text)
          Fired when a section of ignorable whitespace is encountered.
 void fireMeta(java.lang.String text)
          Fired when a meta section is encountered.
 void firePI(java.lang.String text)
          Fired when a processing instruction section is encountered.
 void fireSpecialSection(java.lang.String sectionId, java.lang.String text)
          Fired when a special section is encountered.
 void fireStartElement(java.lang.String namespace, java.lang.String element, java.lang.String QName, boolean isEmpty)
          Fired when a begin-element tag is encountered in the document.
 void fireStartPrefixMapping(java.lang.String prefix, java.lang.String URI)
          Fired when entering the scope of a namespace declaration.
 void flush()
          Flushes the parser.
 int getAttrCount()
          Size of attribute values array for the current element.
 java.lang.String getAttrName(int attrIndex)
          Array of attribute names for the current element.
 java.lang.String getAttrNamespace(int attrIndex)
          Array of attribute namespaces for the current element.
 java.lang.String getAttrPrefix(int attrIndex)
          Array of attribute prefixes for the current element.
 java.lang.String getAttrValue(int attrIndex)
          Array of attribute values for the current element.
 int getElementCount()
          Number of elements in the current element stack.
 java.lang.String getElements(int elementIndex)
          The elements in the current element stack.
 java.lang.String getExtraNameChars()
          Extra characters for the parser to consider as name characters.
 java.lang.String getExtraSpaceChars()
          Extra characters for the parser to consider as white space.
 int getFlags()
          Flags controlling the behaviour of the parser.
 int getNamespaceCount()
          The number of namespaces in the current namespace stack.
 java.lang.String getNamespaces(int namespaceIndex)
          The namespaces in the current namespace stack.
 int getOffset()
          Current offset of the document being parsed.
 java.lang.String getPrefixes(int namespaceIndex)
          The namespace prefixes in the current namespace stack.
 int getXChildren()
          Number of children for the current element.
 java.lang.String getXElement()
          The name of the current element.
 java.lang.String getXNamespace()
          The namespace of the current element.
 java.lang.String getXParent()
          The parent of the current element.
 java.lang.String getXPath()
          Provides a way to point to a specific element in the document.
 java.lang.String getXPrefix()
          The prefix of the current element.
 java.lang.String getXText()
          The text of the current element.
 void input(java.lang.String text)
          Provides input to the parser.
 boolean isBuildDOM()
          When True, an internal object model of the XML document is created.
 boolean isFlushOnEOL()
          If set, the parser flushes its text buffer after every line of text.
 boolean isValidate()
          When True, the parser checks that the document consists of well-formed XML.
 void parseFile(java.lang.String fileName)
          Parses the file specified by FileName.
 void removeXmlpEventListener(XmlpEventListener l)
           
 void reset()
          Resets the parser.
 void setBuildDOM(boolean buildDOM)
          When True, an internal object model of the XML document is created.
 void setExtraNameChars(java.lang.String extraNameChars)
          Extra characters for the parser to consider as name characters.
 void setExtraSpaceChars(java.lang.String extraSpaceChars)
          Extra characters for the parser to consider as white space.
 void setFlags(int flags)
          Flags controlling the behaviour of the parser.
 void setFlushOnEOL(boolean flushOnEOL)
          If set, the parser flushes its text buffer after every line of text.
 void setFlushText(boolean flushText)
          When set, the parser flushes all text, and checks its end state.
 void setInputText(java.lang.String inputText)
          Provides input to the parser.
 void setResetText(boolean resetText)
          When set, the parser initializes itself to its default state.
 void setValidate(boolean validate)
          When True, the parser checks that the document consists of well-formed XML.
 void setXPath(java.lang.String XPath)
          Provides a way to point to a specific element in the document.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Xmlp

public Xmlp()
Method Detail

getAttrCount

public int getAttrCount()
Size of attribute values array for the current element. The AttrCount property provides the number of attributes for the current element.

The corresponding attribute names, prefixes, namespaces, and values are provided respectively via the AttrName , AttrPrefix , AttrNamespace , and AttrValue properties.


getAttrName

public java.lang.String getAttrName(int attrIndex)
                             throws IPWorksException
Array of attribute names for the current element. The AttrName property provides the local names (without prefixes) of the attributes for the current element.

The attribute values are indexed in the array in the same order that they were found in the document. The indexes start at 1 and end at the number of attributes (provided by the AttrCount property).

The corresponding attribute values, attribute prefixes, and namespaces are provided respectively via the AttrValue , AttrPrefix , and AttrNamespace properties.


getAttrNamespace

public java.lang.String getAttrNamespace(int attrIndex)
                                  throws IPWorksException
Array of attribute namespaces for the current element. The AttrNamespace property provides the namespaces of the attributes for the current element.

The attribute namespaces are indexed in the array in the same order that the attributes were found in the document. The indexes start at 1 and end at the number of attributes (provided by the AttrCount property).

The corresponding attribute names, attribute prefixes, and values are provided respectively via the AttrName , AttrPrefix , and AttrValue properties.


getAttrPrefix

public java.lang.String getAttrPrefix(int attrIndex)
                               throws IPWorksException
Array of attribute prefixes for the current element. The AttrName property provides the prefixes of the attributes for the current element.

The attribute prefixes are indexed in the array in the same order that they were found in the document. The indexes start at 1 and end at the number of attributes (provided by the AttrCount property). If an attribute does not have a prefix, this property is empty.

The corresponding attribute values, attribute names, and namespaces are provided respectively via the AttrValue , AttrName , and AttrNamespace properties.


getAttrValue

public java.lang.String getAttrValue(int attrIndex)
                              throws IPWorksException
Array of attribute values for the current element. The AttrValue property provides the values of the attributes for the current element.

The attribute values are indexed in the array in the same order that they were found in the document. The indexes start at 1 and end at the number of attributes (provided by the AttrCount property).

The corresponding attribute names are provided via the AttrName property.


isBuildDOM

public boolean isBuildDOM()
When True, an internal object model of the XML document is created. Set BuildDOM to True when you need to browse the current document through XPath .

Validate is automatically set to True when BuildDOM is set to True.


setBuildDOM

public void setBuildDOM(boolean buildDOM)
                 throws IPWorksException
When True, an internal object model of the XML document is created. Set BuildDOM to True when you need to browse the current document through XPath .

Validate is automatically set to True when BuildDOM is set to True.


getElementCount

public int getElementCount()
Number of elements in the current element stack. The Elements array contains the names of the elements.


getElements

public java.lang.String getElements(int elementIndex)
                             throws IPWorksException
The elements in the current element stack. The array indexes start at 1 and end at ElementCount .

The elements are inserted into the array in the same order they are found in the document.


getExtraNameChars

public java.lang.String getExtraNameChars()
Extra characters for the parser to consider as name characters. Normally, the parser considers only the following characters as part of an XML identifier: 'A' through 'Z', 'a' through 'z', '0' through '9', and '.', '-', '_', ':'.

If you would like any other characters to be considered as name characters, you may set them as a string into this property.


setExtraNameChars

public void setExtraNameChars(java.lang.String extraNameChars)
                       throws IPWorksException
Extra characters for the parser to consider as name characters. Normally, the parser considers only the following characters as part of an XML identifier: 'A' through 'Z', 'a' through 'z', '0' through '9', and '.', '-', '_', ':'.

If you would like any other characters to be considered as name characters, you may set them as a string into this property.


getExtraSpaceChars

public java.lang.String getExtraSpaceChars()
Extra characters for the parser to consider as white space. Normally, the parser considers only the following characters as white space: ' ' (space), '\\t' (tab), '\\n' (newline), '\\r' (carriage return), '\\f' (form feed), and '\\v' (vertical tab).

If you would like any other characters to be considered as white space, you may set them as a string into this property.


setExtraSpaceChars

public void setExtraSpaceChars(java.lang.String extraSpaceChars)
                        throws IPWorksException
Extra characters for the parser to consider as white space. Normally, the parser considers only the following characters as white space: ' ' (space), '\\t' (tab), '\\n' (newline), '\\r' (carriage return), '\\f' (form feed), and '\\v' (vertical tab).

If you would like any other characters to be considered as white space, you may set them as a string into this property.


getFlags

public int getFlags()
Flags controlling the behaviour of the parser. The following flags are currently defined:
0x0001
Ignore bad (unknown) attribute prefixes. Normally a trappable error is generated when an unknown attribute prefix is encountered. Setting this flag suppresses the error.
0x0002
Ignore bad (unknown) element prefixes. Normally a trappable error is generated when an unknown element prefix is encountered. Setting this flag suppresses the error.
More than one flag may be specified by OR-ing the values together.


setFlags

public void setFlags(int flags)
              throws IPWorksException
Flags controlling the behaviour of the parser. The following flags are currently defined:
0x0001
Ignore bad (unknown) attribute prefixes. Normally a trappable error is generated when an unknown attribute prefix is encountered. Setting this flag suppresses the error.
0x0002
Ignore bad (unknown) element prefixes. Normally a trappable error is generated when an unknown element prefix is encountered. Setting this flag suppresses the error.
More than one flag may be specified by OR-ing the values together.


isFlushOnEOL

public boolean isFlushOnEOL()
If set, the parser flushes its text buffer after every line of text. The FlushOnEOL property controls whether Characters events are fired for every line of the input text stream, or not. Normally, lines are buffered internally, and delivered in batches, but if the FlushOnEOL flag is set, then a Characters event is fired for each line.


setFlushOnEOL

public void setFlushOnEOL(boolean flushOnEOL)
                   throws IPWorksException
If set, the parser flushes its text buffer after every line of text. The FlushOnEOL property controls whether Characters events are fired for every line of the input text stream, or not. Normally, lines are buffered internally, and delivered in batches, but if the FlushOnEOL flag is set, then a Characters event is fired for each line.


setFlushText

public void setFlushText(boolean flushText)
                  throws IPWorksException
When set, the parser flushes all text, and checks its end state. FlushText is an action property. If set to True, the parser flushes all its buffers, firing events as neccessary, and then checks its end state. If Validate is true, the parser verifies that all open elements were closed, returning an error if not.


setInputText

public void setInputText(java.lang.String inputText)
                  throws IPWorksException
Provides input to the parser. Write-only property. The parser gets the text input via the InputText property. Any strings assigned to this property are sent to the parser's state machine and appropriate events are fired as a result of the parsing process.

The events are fired only when qualifying conditions (such as, for example, the beginning of a new element) are met. In the meantime, text may be buffered internally. When the parser is finally reset via the Reset method, all buffered text is flushed out through the Characters event.


getNamespaceCount

public int getNamespaceCount()
The number of namespaces in the current namespace stack. The Namespaces array contains the namespace names with the Prefixes array containing the corresponding prefixes.


getNamespaces

public java.lang.String getNamespaces(int namespaceIndex)
                               throws IPWorksException
The namespaces in the current namespace stack. The Prefixes array contains the corresponding prefixes. The array indexes start at 1 and end at NamespaceCount .

The array elements are inserted into the array in the same order they are found in the document.


getOffset

public int getOffset()
Current offset of the document being parsed. This property is useful for determining the location of possible XML errors in the document.

Offset values start at 1.


getPrefixes

public java.lang.String getPrefixes(int namespaceIndex)
                             throws IPWorksException
The namespace prefixes in the current namespace stack. The Namespaces array contains the corresponding namespace names. The array indexes start at 1 and end at NamespaceCount .

The array elements are inserted into the array in the same order they are found in the document.


setResetText

public void setResetText(boolean resetText)
                  throws IPWorksException
When set, the parser initializes itself to its default state. ResetText is an action property. If set to True, the parser flushes all its buffers, firing events as neccessary, and then initializes itself to its default state.

ResetText must also be used as signal to the parser that the current stream of text has terminated.


isValidate

public boolean isValidate()
When True, the parser checks that the document consists of well-formed XML. You can set Validate to True when you want to ignore XML format rules (e.g. while parsing HTML files).


setValidate

public void setValidate(boolean validate)
                 throws IPWorksException
When True, the parser checks that the document consists of well-formed XML. You can set Validate to True when you want to ignore XML format rules (e.g. while parsing HTML files).


getXChildren

public int getXChildren()
Number of children for the current element. The current element is specified via the XPath property.


getXElement

public java.lang.String getXElement()
The name of the current element. The current element is specified via the XPath property.


getXNamespace

public java.lang.String getXNamespace()
The namespace of the current element. The current element is specified via the XPath property.


getXParent

public java.lang.String getXParent()
The parent of the current element. The current element is specified via the XPath property.


getXPath

public java.lang.String getXPath()
Provides a way to point to a specific element in the document. XPath implements a subset of the XML XPath specification, allowing you to point to specific elements in the XML documents.

The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current XPath location.

The following are possible values for an element accessor:

'name'
A particular element name.
[i]
The i-th subelement of the current element.
..
the parent of the current element.
When XPath is set to a valid path, XElement points to the name of the element, with XParent , XNamespace , XPrefix , XChildren;, and XText providing other properties of the element. The attribute arrays ( AttrName , AttrValue , AttrNamespace , etc..) provide the attributes of the current element.

BuildDOM must be set to True prior to parsing the document for the XPath functionality to be available.


setXPath

public void setXPath(java.lang.String XPath)
              throws IPWorksException
Provides a way to point to a specific element in the document. XPath implements a subset of the XML XPath specification, allowing you to point to specific elements in the XML documents.

The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current XPath location.

The following are possible values for an element accessor:

'name'
A particular element name.
[i]
The i-th subelement of the current element.
..
the parent of the current element.
When XPath is set to a valid path, XElement points to the name of the element, with XParent , XNamespace , XPrefix , XChildren;, and XText providing other properties of the element. The attribute arrays ( AttrName , AttrValue , AttrNamespace , etc..) provide the attributes of the current element.

BuildDOM must be set to True prior to parsing the document for the XPath functionality to be available.


getXPrefix

public java.lang.String getXPrefix()
The prefix of the current element. The current element is specified via the XPath property.


getXText

public java.lang.String getXText()
The text of the current element. The current element is specified via the XPath property.


fireCharacters

public void fireCharacters(byte[] text)
Fired for plain text segments of the input stream. (Called internally to dispatch the event.)
See Also:
XmlpCharactersEvent

fireComment

public void fireComment(java.lang.String text)
Fired when a comment section is encountered. (Called internally to dispatch the event.)
See Also:
XmlpCommentEvent

fireEndElement

public void fireEndElement(java.lang.String namespace,
                           java.lang.String element,
                           java.lang.String QName,
                           boolean isEmpty)
Fired when an end-element tag is encountered. (Called internally to dispatch the event.)
See Also:
XmlpEndElementEvent

fireEndPrefixMapping

public void fireEndPrefixMapping(java.lang.String prefix)
Fired when leaving the scope of a namespace declaration. (Called internally to dispatch the event.)
See Also:
XmlpEndPrefixMappingEvent

fireError

public void fireError(int errorCode,
                      java.lang.String description)
Information about errors during data delivery. (Called internally to dispatch the event.)
See Also:
XmlpErrorEvent

fireEvalEntity

public void fireEvalEntity(java.lang.String entity,
                           java.lang.String value)
Fired every time an entity needs to be evaluated. (Called internally to dispatch the event.)
See Also:
XmlpEvalEntityEvent

fireIgnorableWhitespace

public void fireIgnorableWhitespace(java.lang.String text)
Fired when a section of ignorable whitespace is encountered. (Called internally to dispatch the event.)
See Also:
XmlpIgnorableWhitespaceEvent

fireMeta

public void fireMeta(java.lang.String text)
Fired when a meta section is encountered. (Called internally to dispatch the event.)
See Also:
XmlpMetaEvent

firePI

public void firePI(java.lang.String text)
Fired when a processing instruction section is encountered. (Called internally to dispatch the event.)
See Also:
XmlpPIEvent

fireSpecialSection

public void fireSpecialSection(java.lang.String sectionId,
                               java.lang.String text)
Fired when a special section is encountered. (Called internally to dispatch the event.)
See Also:
XmlpSpecialSectionEvent

fireStartElement

public void fireStartElement(java.lang.String namespace,
                             java.lang.String element,
                             java.lang.String QName,
                             boolean isEmpty)
Fired when a begin-element tag is encountered in the document. (Called internally to dispatch the event.)
See Also:
XmlpStartElementEvent

fireStartPrefixMapping

public void fireStartPrefixMapping(java.lang.String prefix,
                                   java.lang.String URI)
Fired when entering the scope of a namespace declaration. (Called internally to dispatch the event.)
See Also:
XmlpStartPrefixMappingEvent

attr

public java.lang.String attr(java.lang.String attrName)
                      throws IPWorksException
Returns the value of the specified attribute. If the attribute does not exist, a trappable error is generated.

Please refer to the AttrName and AttrValue properties for more information.


flush

public void flush()
           throws IPWorksException
Flushes the parser. Calling this method is equivalent to setting the FlushText property to True.


input

public void input(java.lang.String text)
           throws IPWorksException
Provides input to the parser. Calling this method is equivalent to setting the InputText property to Text .


parseFile

public void parseFile(java.lang.String fileName)
               throws IPWorksException
Parses the file specified by FileName. The parser is Reset prior to parsing the file.


reset

public void reset()
           throws IPWorksException
Resets the parser. Calling this method is equivalent to setting the ResetText property to True.


addXmlpEventListener

public void addXmlpEventListener(XmlpEventListener l)
                          throws java.util.TooManyListenersException

removeXmlpEventListener

public void removeXmlpEventListener(XmlpEventListener l)

IP*Works!

Copyright (c) 2001 /n software inc. - All rights reserved.