|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectipworks.Xmlw
public class Xmlw
The XMLw bean provides an easy way to generate well-formed XML documents.
The XMLw bean creates XML documents while providing you control over every aspect of the document.
To use the bean first decide whether or not to write to file, a stream, or to OutputData
.
To write to file set OutputFile
. To write to a stream call SetOutputStream
.
If neither OutputFile
nor SetOutputStream
are used the document will be created in memory and will be available
from OutputData
.
To begin writing the XML document first call WriteXMLDeclaration
. While this is not required is it suggested
so that your XML document contains a traditional XML declaration at the beginning of the document.
Next begin adding elements to your document. Calling StartElement
will open an element with the specified name.
To create a nested structure continue calling StartElement
to open more child elements.
To write a value within an element call WriteString
. To close the element that was last opened call EndElement
.
Each time EndElement
is called the element at the current level is closed.
Alternatively, calling WriteElement
will write the element specified with the value specified and will also close the element.
To write an attribute of the current element, after calling StartElement
call WriteAttribute
. Call WriteAttribute
multiple times to add multiple attributes.
Writing comments or CDATA can be done at any time with the WriteComment
and WriteCData
methods.
To close your XML document call Close
. You can call Close
from any location and it will close any remaining open elements automatically.
Constructor Summary | |
---|---|
Xmlw()
Creates an instance of Xmlw Bean. |
|
Xmlw(java.lang.String runtimeLicense)
Creates an instance of Xmlw Bean with specified run-time license. |
Method Summary | |
---|---|
void |
addXmlwEventListener(XmlwEventListener l)
|
void |
close()
Closes the bean writing stream. |
java.lang.String |
config(java.lang.String configurationString)
Sets or retrieves a configuration setting. |
void |
endElement()
Writes the closing tag of an open XML element. |
java.lang.String |
getEOL()
The characters to use for separating lines. |
java.lang.String |
getIndent()
The characters to use for each indentation level. |
byte[] |
getOutputData()
The buffered XML output data. |
java.lang.String |
getOutputFile()
The path to a local file where the output will be written. |
void |
removeXmlwEventListener(XmlwEventListener l)
|
void |
reset()
Reset the bean. |
void |
setEOL(java.lang.String EOL)
The characters to use for separating lines. |
void |
setIndent(java.lang.String indent)
The characters to use for each indentation level. |
void |
setOutputFile(java.lang.String outputFile)
The path to a local file where the output will be written. |
void |
setOutputStream(java.io.OutputStream outputStream)
Sets the stream to which the XML will be written. |
void |
startElement(java.lang.String name,
java.lang.String namespaceURI)
Writes the opening tag of an XML element. |
void |
writeAttribute(java.lang.String name,
java.lang.String namespaceURI,
java.lang.String value)
Writes an XML attribute. |
void |
writeCData(java.lang.String text)
Writes an XML CDATA block. |
void |
writeComment(java.lang.String text)
Writes an XML comment block. |
void |
writeElement(java.lang.String name,
java.lang.String namespaceURI,
java.lang.String value)
Writes a simple XML element with a value. |
void |
writeRaw(java.lang.String text)
Writes a raw XML fragment. |
void |
writeString(java.lang.String text)
Writes text inside an XML element. |
void |
writeXMLDeclaration(java.lang.String version,
boolean includeEncoding,
boolean standalone)
Writes an XML declaration at the top of the document. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public Xmlw()
public Xmlw(java.lang.String runtimeLicense)
Method Detail |
---|
public java.lang.String getEOL()
If specified, the bean will format the output XML, using the specified characters to separate multiple lines for nested XML elements. The default value is CRLF ("\\r\\n") .
This option should be combined with Indent
for full effect.
public void setEOL(java.lang.String EOL) throws IPWorksException
If specified, the bean will format the output XML, using the specified characters to separate multiple lines for nested XML elements. The default value is CRLF ("\\r\\n") .
This option should be combined with Indent
for full effect.
IPWorksException
public java.lang.String getIndent()
If specified, the bean will format the output XML, using the specified characters to denote each indentation level for nested XML elements.
This option should be combined with EOL
for full effect.
public void setIndent(java.lang.String indent) throws IPWorksException
If specified, the bean will format the output XML, using the specified characters to denote each indentation level for nested XML elements.
This option should be combined with EOL
for full effect.
IPWorksException
public byte[] getOutputData()
This property can be used to retrieve the generated output from the bean when neither OutputFile
nor SetOutputStream
have been set.
public java.lang.String getOutputFile()
If specified, the output of the bean will be written to the OutputFile
.
As an alternative, you can specify an output stream through SetOutputStream
. If neither one
is set, the output will be buffered in memory and can be retrieved using OutputData
.
public void setOutputFile(java.lang.String outputFile) throws IPWorksException
If specified, the output of the bean will be written to the OutputFile
.
As an alternative, you can specify an output stream through SetOutputStream
. If neither one
is set, the output will be buffered in memory and can be retrieved using OutputData
.
IPWorksException
public void close() throws IPWorksException
This method will close any open XML elements, and then close the OutputFile
or output stream if necessary.
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.
WriteXMLDeclaration
is called. The default value is "utf-8".Close
is called. In order to keep the stream open, set this to false.
IPWorksException
public void endElement() throws IPWorksException
Writes the closing tag of the XML element most recently opened using StartElement
.
If no elements are opened, the call throws an exception
IPWorksException
public void reset() throws IPWorksException
This method will reset the bean properties to their default value when called.
IPWorksException
public void setOutputStream(java.io.OutputStream outputStream) throws IPWorksException
This method is used to set the stream to which the XML data will be written.
The bean will automatically close this stream if CloseStream
is true (default).
If the stream is closed, you will need to call SetOutputStream
again before writing again.
Note: SetOutputStream
and OutputFile
will reset the other.
IPWorksException
public void startElement(java.lang.String name, java.lang.String namespaceURI) throws IPWorksException
Writes the opening tag of a new XML element. If an XML element is already opened, then this element is written as a child.
If Name is a local name without a prefix, the bean will automatically introduce a new xmlns=" NamespaceURI " attribute if necessary.
If Name is in the form prefix:local, then bean will automatically introduce a new xmlns:prefix=" NamespaceURI " as necessary.
When calling WriteElement
or StartElement
, if a NamespaceURI is not specified an empty namespace
will be defined for the element. If a namespace should be associated with the element, a NamespaceURI value must be provided. When creating the XML, the bean will determine if the namespace already exists
to avoid duplicate definitions of the same namespace. For example, to create this XML:
<book xmlns='urn:loc.gov:books'
xmlns:isbn='urn:ISBN:0-395-36341-6'>
<title>Cheaper by the Dozen</title>
<isbn:number>1568491379</isbn:number>
</book>
Use the code: xmlw.StartElement("book", "urn:loc.gov:books");
xmlw.WriteAttribute("xmlns:isbn", "", "urn:ISBN:0-395-36341-6");
xmlw.WriteElement("title", "urn:loc.gov:books", "Cheaper by the Dozen");
xmlw.WriteElement("isbn:number", "urn:ISBN:0-395-36341-6", "1568491379");
xmlw.Close();
In the above example the "title" element uses the default namespace "urn:loc.gov:books" and the "number"
element uses the "urn:ISBN:0-395-36341-6" namespace as defined for the "isbn" prefix.
IPWorksException
public void writeAttribute(java.lang.String name, java.lang.String namespaceURI, java.lang.String value) throws IPWorksException
Writes an XML attribute on the currently opened XML element. It must be called
right after calling StartElement
and before any calls to WriteString
, WriteComment
or WriteRaw
.
If Name is a local name without a prefix, the bean will automatically introduce a new xmlns=" NamespaceURI " attribute if necessary.
If Name is in the form prefix:local, then bean will automatically introduce a new xmlns:prefix=" NamespaceURI " as necessary.
Certain attribute names will be handled in special ways by this method. If Name is "xmlns" or uses the "xmlns" prefix, the attribute will be interpreted as a namespace declaration, regardless of the value of NamespaceURI . Similarly, any attribute using the "xml" prefix will be interpreted as a special attribute (like "xml:lang") and NamespaceURI will be ignored.
IPWorksException
public void writeCData(java.lang.String text) throws IPWorksException
Writes a new XML CDATA block with the specified text inside the current element.
IPWorksException
public void writeComment(java.lang.String text) throws IPWorksException
Writes a new XML comment block with the specified text.
IPWorksException
public void writeElement(java.lang.String name, java.lang.String namespaceURI, java.lang.String value) throws IPWorksException
Writes a simple XML element with no attributes and the specified value between the opening and closing tags.
If Name is a local name without a prefix, the bean will automatically introduce a new xmlns=" NamespaceURI " attribute if necessary.
If Name is in the form prefix:local, then bean will automatically introduce a new xmlns:prefix=" NamespaceURI " as necessary.
When calling WriteElement
or StartElement
, if a NamespaceURI is not specified an empty namespace
will be defined for the element. If a namespace should be associated with the element, a NamespaceURI value must be provided. When creating the XML, the bean will determine if the namespace already exists
to avoid duplicate definitions of the same namespace. For example, to create this XML:
<book xmlns='urn:loc.gov:books'
xmlns:isbn='urn:ISBN:0-395-36341-6'>
<title>Cheaper by the Dozen</title>
<isbn:number>1568491379</isbn:number>
</book>
Use the code: xmlw.StartElement("book", "urn:loc.gov:books");
xmlw.WriteAttribute("xmlns:isbn", "", "urn:ISBN:0-395-36341-6");
xmlw.WriteElement("title", "urn:loc.gov:books", "Cheaper by the Dozen");
xmlw.WriteElement("isbn:number", "urn:ISBN:0-395-36341-6", "1568491379");
xmlw.Close();
In the above example the "title" element uses the default namespace "urn:loc.gov:books" and the "number"
element uses the "urn:ISBN:0-395-36341-6" namespace as defined for the "isbn" prefix.
IPWorksException
public void writeRaw(java.lang.String text) throws IPWorksException
Writes a raw XML fragment to the output, without escaping and without verification. If an XML element opening tag has been written, before the raw fragment, the fragment will be written as a child of the current element.
Use of this method should be carefully considered as it can easily lead to malformed XML content.
IPWorksException
public void writeString(java.lang.String text) throws IPWorksException
This method will XML escape the value provided and write the resulting escaped text between the opening and closing tags of an XML element.
IPWorksException
public void writeXMLDeclaration(java.lang.String version, boolean includeEncoding, boolean standalone) throws IPWorksException
This method should be call first to write a new XML declaration at the top of the document. Version specifies the XML version to use ('1.0').
If IncludeEncoding is true, an encoding attribute will be included based on the current charset
.
If Standalone is true, the standalone="true" attribute will be included on the declaration.
IPWorksException
public void addXmlwEventListener(XmlwEventListener l) throws java.util.TooManyListenersException
java.util.TooManyListenersException
public void removeXmlwEventListener(XmlwEventListener l)
|
IP*Works! V9 | |||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |