IP*Works! V9

ipworks
Class Xmlp

java.lang.Object
  extended by ipworks.Xmlp

public class Xmlp
extends java.lang.Object

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

Xmlp

public Xmlp()
Creates an instance of Xmlp Bean.


Xmlp

public Xmlp(java.lang.String runtimeLicense)
Creates an instance of Xmlp Bean with specified run-time license.

Method Detail

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.

Throws:
IPWorksException

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.

Throws:
IPWorksException

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.

Throws:
IPWorksException

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.

Throws:
IPWorksException

getNamespaces

public XMLNamespaceList getNamespaces()
Collection of namespaces in the current namespace stack.

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.


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.


isValidate

public boolean isValidate()
When True, the parser checks that the document consists of well-formed XML.

You can set Validate to False 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 False when you want to ignore XML format rules (e.g. while parsing HTML files).

Throws:
IPWorksException

getXAttributes

public XMLAttributeList getXAttributes()
A collection of attributes of the current element.

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.


getXChildren

public XMLElementList getXChildren()
Collection of child elements of the current element.

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.


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
name[i]
The i-th subelement of the current element with the given name
[i]
The i-th subelement of the current element
[last()]
The last subelement of the current element
[last()-i]
The subelement located at the last location minus i in the current element
name[@attrname="attrvalue"]
The subelement containing a particular value for a given attribute (supports single AND double quotes)
..
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 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]"


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
name[i]
The i-th subelement of the current element with the given name
[i]
The i-th subelement of the current element
[last()]
The last subelement of the current element
[last()-i]
The subelement located at the last location minus i in the current element
name[@attrname="attrvalue"]
The subelement containing a particular value for a given attribute (supports single AND double quotes)
..
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 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]"

Throws:
IPWorksException

getXPrefix

public java.lang.String getXPrefix()
The prefix of the current element.

The current element is specified via the XPath property.


getXSubTree

public java.lang.String getXSubTree()
A snapshot of the current element in the document.

The current element is specified via the XPath property. In order for this property to work you must have the CacheContent set to true.


getXText

public java.lang.String getXText()
The text of the current element.

The current element is specified via the XPath property.


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, 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.

Throws:
IPWorksException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksException
Sets or retrieves a configuration setting.

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.

XMLp Configuration Settings

IgnoreBadAttributePrefixes
If true, bad (unknown) attribute prefixes are ignored
Normally a trappable error is generated when an unknown attribute prefix is encountered. This setting suppresses the error. The default value is True.
IgnoreBadElementPrefixes
If true, bad (unknown) element prefixes are ignored
Normally a trappable error is generated when an unknown element prefix is encountered. This setting suppresses the error. The default value is True.
CacheContent
If true, the original XML is saved in a buffer
This config controls whether or not the component retains the entire original XML in a buffer. This is used to retain the original XML as opposed to returning generated XML after parsing. The default value is true.
ErrorOnEmptyAttr
If true, passing an invalid attribute to the Attr method will throw an exception
If an invalid attribute name is passed into the Attr method, the method will return with an empty string if this is set to false, otherwise an exception is thrown.
PreserveWhitespace
If true, leading and trailing whitespace in element text is preserved
Normally the leading and trailing whitespace from an element's text is trimmed. When this property is set to true, this leading and trailing whitespace is preserved. The default value is false.

Base Configuration Settings

GUIAvailable
Tells the bean whether or not a message loop is available for processing events
In a GUI-based application, long-running blocking operations may cause the application to stop responding to input until the operation returns. The bean will attempt to discover whether or not the application has a message loop and, if one is discovered, it will process events in that message loop during any such blocking operation.In some non-GUI applications an invalid message loop may be discovered that will result in errant behavior. In these cases, setting GuiAvailable to false will ensure that the bean does not attempt to process external events.

Throws:
IPWorksException

flush

public void flush()
           throws IPWorksException
Flushes the parser and checks its end state.

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.

Throws:
IPWorksException

hasXPath

public boolean hasXPath(java.lang.String xpath)
                 throws IPWorksException
Determines whether a specific element exists in the document.

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.

Throws:
IPWorksException

input

public void input(java.lang.String text)
           throws IPWorksException
Provides input to the parser.

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") 

Throws:
IPWorksException

loadDOM

public void loadDOM(java.lang.String fileName)
             throws IPWorksException
Loads the DOM from a file.

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.

Throws:
IPWorksException

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. 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") 

Throws:
IPWorksException

reset

public void reset()
           throws IPWorksException
Resets the parser.

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.

Throws:
IPWorksException

saveDOM

public void saveDOM(java.lang.String fileName)
             throws IPWorksException
Saves the DOM to a file.

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.

Throws:
IPWorksException

addXmlpEventListener

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

removeXmlpEventListener

public void removeXmlpEventListener(XmlpEventListener l)

IP*Works! V9

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