|
![]() |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--ipworks.Xmlp
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 |
public Xmlp()
Method Detail |
public int getAttrCount()
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.
public java.lang.String getAttrName(int attrIndex) throws IPWorksException
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.
public java.lang.String getAttrNamespace(int attrIndex) throws IPWorksException
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.
public java.lang.String getAttrPrefix(int attrIndex) throws IPWorksException
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.
public java.lang.String getAttrValue(int attrIndex) throws IPWorksException
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.
public boolean isBuildDOM()
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.
public void setBuildDOM(boolean buildDOM) throws IPWorksException
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.
public int getElementCount()
Elements
array contains the names of the elements.
public java.lang.String getElements(int elementIndex) throws IPWorksException
ElementCount
.
The elements are inserted into the array in the same order they are found in the document.
public java.lang.String getExtraNameChars()
If you would like any other characters to be considered as name characters, you may set them as a string into this property.
public void setExtraNameChars(java.lang.String extraNameChars) throws IPWorksException
If you would like any other characters to be considered as name characters, you may set them as a string into this property.
public java.lang.String getExtraSpaceChars()
If you would like any other characters to be considered as white space, you may set them as a string into this property.
public void setExtraSpaceChars(java.lang.String extraSpaceChars) throws IPWorksException
If you would like any other characters to be considered as white space, you may set them as a string into this property.
public int getFlags()
public void setFlags(int flags) throws IPWorksException
public boolean isFlushOnEOL()
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.
public void setFlushOnEOL(boolean flushOnEOL) throws IPWorksException
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.
public void setFlushText(boolean flushText) throws IPWorksException
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.
public void setInputText(java.lang.String inputText) throws IPWorksException
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.
public int getNamespaceCount()
Namespaces
array contains the namespace names with
the Prefixes
array containing the corresponding prefixes.
public java.lang.String getNamespaces(int namespaceIndex) throws IPWorksException
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.
public int getOffset()
Offset
values start at 1.
public java.lang.String getPrefixes(int namespaceIndex) throws IPWorksException
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.
public void setResetText(boolean resetText) throws IPWorksException
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.
public boolean isValidate()
Validate
to True when you want to ignore
XML format rules (e.g. while parsing HTML files).
public void setValidate(boolean validate) throws IPWorksException
Validate
to True when you want to ignore
XML format rules (e.g. while parsing HTML files).
public int getXChildren()
XPath
property.
public java.lang.String getXElement()
XPath
property.
public java.lang.String getXNamespace()
XPath
property.
public java.lang.String getXParent()
XPath
property.
public java.lang.String getXPath()
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:
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.
public void setXPath(java.lang.String XPath) throws IPWorksException
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:
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.
public java.lang.String getXPrefix()
XPath
property.
public java.lang.String getXText()
XPath
property.
public void fireCharacters(byte[] text)
XmlpCharactersEvent
public void fireComment(java.lang.String text)
XmlpCommentEvent
public void fireEndElement(java.lang.String namespace, java.lang.String element, java.lang.String QName, boolean isEmpty)
XmlpEndElementEvent
public void fireEndPrefixMapping(java.lang.String prefix)
XmlpEndPrefixMappingEvent
public void fireError(int errorCode, java.lang.String description)
XmlpErrorEvent
public void fireEvalEntity(java.lang.String entity, java.lang.String value)
XmlpEvalEntityEvent
public void fireIgnorableWhitespace(java.lang.String text)
XmlpIgnorableWhitespaceEvent
public void fireMeta(java.lang.String text)
XmlpMetaEvent
public void firePI(java.lang.String text)
XmlpPIEvent
public void fireSpecialSection(java.lang.String sectionId, java.lang.String text)
XmlpSpecialSectionEvent
public void fireStartElement(java.lang.String namespace, java.lang.String element, java.lang.String QName, boolean isEmpty)
XmlpStartElementEvent
public void fireStartPrefixMapping(java.lang.String prefix, java.lang.String URI)
XmlpStartPrefixMappingEvent
public java.lang.String attr(java.lang.String attrName) throws IPWorksException
Please refer to the AttrName
and AttrValue
properties
for more information.
public void flush() throws IPWorksException
FlushText
property
to True.
public void input(java.lang.String text) throws IPWorksException
InputText
property
to Text .
public void parseFile(java.lang.String fileName) throws IPWorksException
Reset
prior to parsing the file.
public void reset() throws IPWorksException
ResetText
property
to True.
public void addXmlpEventListener(XmlpEventListener l) throws java.util.TooManyListenersException
public void removeXmlpEventListener(XmlpEventListener l)
|
![]() |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |