|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectipworks.Xmlp
public class Xmlp
The XMLp bean implements a SAX2-compliant XML parser used to parse and verify the structure of XML documents.
The XMLp bean 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 bean takes pieces of XML code through the Input
method, until Flush
is called.
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 XAttributes
collection
provides 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()
Creates an instance of Xmlp Bean. |
|
Xmlp(java.lang.String runtimeLicense)
Creates an instance of Xmlp Bean with specified run-time license. |
Method Summary | |
---|---|
void |
addXmlpEventListener(XmlpEventListener l)
|
java.lang.String |
attr(java.lang.String attrName)
Returns the value of the specified attribute. |
java.lang.String |
config(java.lang.String configurationString)
Sets or retrieves a configuration setting. |
void |
flush()
Flushes the parser and checks its end state. |
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. |
XMLNamespaceList |
getNamespaces()
Collection of namespaces in the current namespace stack. |
int |
getOffset()
Current offset of the document being parsed. |
XMLAttributeList |
getXAttributes()
A collection of attributes of the current element. |
XMLElementList |
getXChildren()
Collection of child elements of 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 |
getXSubTree()
A snapshot of the current element in the document. |
java.lang.String |
getXText()
The text of the current element. |
boolean |
hasXPath(java.lang.String xpath)
Determines whether a specific element exists in the document. |
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 |
loadDOM(java.lang.String fileName)
Loads the DOM from a file. |
void |
parseFile(java.lang.String fileName)
Parses the file specified by FileName. |
void |
removeXmlpEventListener(XmlpEventListener l)
|
void |
reset()
Resets the parser. |
void |
saveDOM(java.lang.String fileName)
Saves the DOM to a file. |
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 |
setFlushOnEOL(boolean flushOnEOL)
If set, the parser flushes its text buffer after every line of text. |
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()
public Xmlp(java.lang.String runtimeLicense)
Method Detail |
---|
public boolean isBuildDOM()
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.
public void setBuildDOM(boolean buildDOM) throws IPWorksException
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.
IPWorksException
public java.lang.String getExtraNameChars()
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.
public void setExtraNameChars(java.lang.String extraNameChars) throws IPWorksException
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.
IPWorksException
public java.lang.String getExtraSpaceChars()
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.
public void setExtraSpaceChars(java.lang.String extraSpaceChars) throws IPWorksException
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.
IPWorksException
public boolean isFlushOnEOL()
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.
public void setFlushOnEOL(boolean flushOnEOL) throws IPWorksException
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.
IPWorksException
public XMLNamespaceList getNamespaces()
This property contains a collection of XML namespaces, which are standards for providing uniquely named elements and attributes in an XML instance.
This collection is indexed from 0 to size - 1.
public int getOffset()
This property is useful for determining the location of possible XML errors in the document.
Offset
values start at 1.
public boolean isValidate()
You can set Validate
to False when you want to ignore
XML format rules (e.g. while parsing HTML files).
public void setValidate(boolean validate) throws IPWorksException
You can set Validate
to False when you want to ignore
XML format rules (e.g. while parsing HTML files).
IPWorksException
public XMLAttributeList getXAttributes()
This collection consists of all attributes of
the current XML element. The component parses
each attribute into a collection of xmlattribute
types.
This collection is indexed from 0 to size - 1.
public XMLElementList getXChildren()
The elements are provided in the collection in the same order they are found in the document.
This collection is indexed from 0 to size - 1.
public java.lang.String getXElement()
The current element is specified via the XPath
property.
public java.lang.String getXNamespace()
The current element is specified via the XPath
property.
public java.lang.String getXParent()
The current element is specified via the 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 attributes of the current element are provided in the XAttributes
collection
.
BuildDOM
must be set to True prior to parsing the document
for the XPath
functionality to be available. Example (Setting XPath)
- Document root
- XMLpControl.XPath = "/"
- Specific Element
- XMLpControl.XPath = "/root/SubElement1/SubElement2/"
- i-th Child
- XMLpControl.XPath = "/root/SubElement1[i]"
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 attributes of the current element are provided in the XAttributes
collection
.
BuildDOM
must be set to True prior to parsing the document
for the XPath
functionality to be available. Example (Setting XPath)
- Document root
- XMLpControl.XPath = "/"
- Specific Element
- XMLpControl.XPath = "/root/SubElement1/SubElement2/"
- i-th Child
- XMLpControl.XPath = "/root/SubElement1[i]"
IPWorksException
public java.lang.String getXPrefix()
The current element is specified via the XPath
property.
public java.lang.String getXSubTree()
The current element is specified via the XPath
property. In order for this property to work you must have the CacheContent
set to true.
public java.lang.String getXText()
The current element is specified via the XPath
property.
public java.lang.String attr(java.lang.String attrName) throws IPWorksException
If the attribute does not exist, an empty string is returned if ErrorOnEmptyAttr
is set to false, otherwise an exception is thrown.
Please refer to the XAttributes
collection
for more information.
IPWorksException
public java.lang.String config(java.lang.String configurationString) throws IPWorksException
Config
is a generic method available in every bean.
It is used to set and retrieve configuration settings
for the
bean.
Configuration settings are similar in functionality to properties,
but they are rarely used. In order to avoid "polluting" the property
namespace of the bean, access to these internal properties is provided through the Config
method.
To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).
To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.
The bean accepts one or more of the following configuration settings .
Configuration settings are similar in functionality to properties,
but they are rarely used. In order to avoid "polluting" the property
namespace of the bean, access to these internal properties is provided through the Config
method.
Attr
method, the method will return with an
empty string if this is set to false, otherwise an exception is thrown.
IPWorksException
public void flush() throws IPWorksException
When Flush
is called, the parser
flushes all its buffers, firing events as necessary,
and then checks its end state. If Validate
is true, the
parser verifies that all open elements were closed, returning
an error if not.
IPWorksException
public boolean hasXPath(java.lang.String xpath) throws IPWorksException
You can use the HasXPath
method to determine if a particular XPath exists before setting it with XPath
.
The XPath
property implements a subset of the XML XPath specification, allowing you to point to specific
elements in the document.
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.
Setting the XPath
property to an XPath that does not exist will cause an error.
IPWorksException
public void input(java.lang.String text) throws IPWorksException
The parser gets the text input via the Text parameter. The Text is 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 will be buffered internally.
When the parser is finally reset via the Reset
method, all buffered text is
flushed out through the Characters
event.
Since XMLp can be used to parse XML fragments, the internal buffer will not be cleared until Reset
is called.
If you plan to use this method to parse multiple complete XML documents be sure to call Reset
between calls.
Example (Parse an XML File)
XMLpControl.Input("xmldata")
IPWorksException
public void loadDOM(java.lang.String fileName) throws IPWorksException
The LoadDOM
method loads a DOM structure previously saved
by SaveDOM
from the file specified in FileName .
Please refer to the SaveDOM
method for more information.
IPWorksException
public void parseFile(java.lang.String fileName) throws IPWorksException
The parser is Reset
prior to parsing the file. If Validate
is true,
the parser checks that the document consists of well-formed XML.
When ParseFile
is called, the appropriate events are fired as a result of the parsing process.
Also, the XPath
can be traversed in order to access specific parts of the document.
Example (Parse an XML File)
XMLpControl.ParseFile("C:\\filename.xml")
IPWorksException
public void reset() throws IPWorksException
When called, the parser flushes all its buffers, firing events as necessary, and then initializes itself to its default state.
Reset
must also be used as signal to the parser that the current
stream of text has terminated.
IPWorksException
public void saveDOM(java.lang.String fileName) throws IPWorksException
The SaveDOM
method saves the current DOM structure to the file
specified in FileName . This enables the component to later
load the DOM without incurring any parsing overhead.
Please refer to the LoadDOM
method for more information.
IPWorksException
public void addXmlpEventListener(XmlpEventListener l) throws java.util.TooManyListenersException
java.util.TooManyListenersException
public void removeXmlpEventListener(XmlpEventListener l)
|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |