IP*Works! V9

ipworks
Class Xmlw

java.lang.Object
  extended by ipworks.Xmlw

public class Xmlw
extends java.lang.Object

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

Xmlw

public Xmlw()
Creates an instance of Xmlw Bean.


Xmlw

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

Method Detail

getEOL

public java.lang.String getEOL()
The characters to use for separating lines.

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.


setEOL

public void setEOL(java.lang.String EOL)
            throws IPWorksException
The characters to use for separating lines.

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.

Throws:
IPWorksException

getIndent

public java.lang.String getIndent()
The characters to use for each indentation level.

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.


setIndent

public void setIndent(java.lang.String indent)
               throws IPWorksException
The characters to use for each indentation level.

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.

Throws:
IPWorksException

getOutputData

public byte[] getOutputData()
The buffered XML output data.

This property can be used to retrieve the generated output from the bean when neither OutputFile nor SetOutputStream have been set.


getOutputFile

public java.lang.String getOutputFile()
The path to a local file where the output will be written. If the file exists, it is overwritten.

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 .


setOutputFile

public void setOutputFile(java.lang.String outputFile)
                   throws IPWorksException
The path to a local file where the output will be written. If the file exists, it is overwritten.

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 .

Throws:
IPWorksException

close

public void close()
           throws IPWorksException
Closes the bean writing stream.

This method will close any open XML elements, and then close the OutputFile or output stream if necessary.

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.

XMLw Configuration Settings

Charset
Specifies the charset used when encoding data
Set this value to specify the charset that is used when encoding data, as well as the encoding attribute in set when WriteXMLDeclaration is called. The default value is "utf-8".
CloseStream
If true, the bean will close the output stream
This setting is true by default. Therefore, by default, the output stream will be closed when Close is called. In order to keep the stream open, set this to false.
QuoteChar
Quote character to use for attribute values
By default, the bean will use double quotes around attribute values. This property can be used to specify a different character such as a single quote.

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

endElement

public void endElement()
                throws IPWorksException
Writes the closing tag of an open XML element.

Writes the closing tag of the XML element most recently opened using StartElement .

If no elements are opened, the call throws an exception

Throws:
IPWorksException

reset

public void reset()
           throws IPWorksException
Reset the bean.

This method will reset the bean properties to their default value when called.

Throws:
IPWorksException

setOutputStream

public void setOutputStream(java.io.OutputStream outputStream)
                     throws IPWorksException
Sets the stream to which the XML will be written.

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.

Throws:
IPWorksException

startElement

public void startElement(java.lang.String name,
                         java.lang.String namespaceURI)
                  throws IPWorksException
Writes the opening tag of an XML element.

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.

Throws:
IPWorksException

writeAttribute

public void writeAttribute(java.lang.String name,
                           java.lang.String namespaceURI,
                           java.lang.String value)
                    throws IPWorksException
Writes an XML attribute.

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.

Throws:
IPWorksException

writeCData

public void writeCData(java.lang.String text)
                throws IPWorksException
Writes an XML CDATA block.

Writes a new XML CDATA block with the specified text inside the current element.

Throws:
IPWorksException

writeComment

public void writeComment(java.lang.String text)
                  throws IPWorksException
Writes an XML comment block.

Writes a new XML comment block with the specified text.

Throws:
IPWorksException

writeElement

public void writeElement(java.lang.String name,
                         java.lang.String namespaceURI,
                         java.lang.String value)
                  throws IPWorksException
Writes a simple XML element with a value.

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.

Throws:
IPWorksException

writeRaw

public void writeRaw(java.lang.String text)
              throws IPWorksException
Writes a raw XML fragment.

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.

Throws:
IPWorksException

writeString

public void writeString(java.lang.String text)
                 throws IPWorksException
Writes text inside an XML element.

This method will XML escape the value provided and write the resulting escaped text between the opening and closing tags of an XML element.

Throws:
IPWorksException

writeXMLDeclaration

public void writeXMLDeclaration(java.lang.String version,
                                boolean includeEncoding,
                                boolean standalone)
                         throws IPWorksException
Writes an XML declaration at the top of the document.

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.

Throws:
IPWorksException

addXmlwEventListener

public void addXmlwEventListener(XmlwEventListener l)
                          throws java.util.TooManyListenersException
Throws:
java.util.TooManyListenersException

removeXmlwEventListener

public void removeXmlwEventListener(XmlwEventListener l)

IP*Works! V9

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