com.ricebridge.xmlman
Class XmlSpec

java.lang.Object
  com.ricebridge.xmlman.XmlSpec

public class XmlSpec

extends Object

Stores settings for reading and writing XML files.

This class describes the namespaces and formatting options of an XML file and is used by the XML parser to control the interpretation of the XML data.

When inputting XML, XmlSpec objects allow you to control the interpretation of your XML file in a number of ways:

• run the load process as a background thread - setBackground(boolean)
• ignore (semantically) bad records and continue processing - setIgnoreBadRecords(boolean)
• set the character encoding - setEncoding(java.lang.String)
• use namespaces - setNamespaceAware(boolean)
• validate the XML - setValidating(boolean)
• close InputStreams when finished - setCloseStream(boolean)

When outputting XML data, the following options are provided:

• run the save process as a background thread - setBackground(boolean)
• ignore (semantically) bad records and continue processing - setIgnoreBadRecords(boolean)
• set the character encoding - setEncoding(java.lang.String)
• indent XML output - setIndent(boolean)
• flush output as it is written - setFlush(boolean)
• set the XML header text - setHeader(java.lang.String)
• set the XML footer text - setFooter(java.lang.String)
• close OutputStreams when finished - setCloseStream(boolean)

The toString() method provides a human-readable description of the settings for debugging purposes.

You can also set SAX features, using the setSAXFeature(String,boolean) method.

See Also:

XmlManager, XmlManagerException

Field Summary

static String	DEFAULT_ENCODING Default encoding for XML files: UTF-8.
static String	PROP_background See setBackground(boolean).
static String	PROP_closestream See setCloseStream(boolean).
static String	PROP_encoding See setEncoding(java.lang.String).
static String	PROP_flush See setFlush(boolean).
static String	PROP_footer See setFooter(java.lang.String).
static String	PROP_header See setHeader(java.lang.String).
static String	PROP_ignorebadrecords See setIgnoreBadRecords(boolean).
static String	PROP_indent See setIndent(boolean).
static String	PROP_namespaceaware See setNamespaceAware(boolean).
static String	PROP_streamoutput See setStreamOutput(boolean).
static String	PROP_validating See setValidating(boolean).

Constructor Summary

XmlSpec()
Create a new default instance of XmlSpec, with default settings.

Method Summary

void	addFunction(String pPrefix, String pName, Function pFunction) Add a named function for use in XPath expressions.
void	addNamespace(String pPrefix, String pURI) Add a namespace to the current namespace mappings.
void	addVariable(String pLocalName, Object pValue) Add a variable for use in XPath expressions.
void	addVariable(String pLocalName, String pNamespaceURI, Object pValue) Add a variable for use in XPath expressions, qualified with a namespace.
void	applySAXFeatures(SAXParserFactory pSAXParserFactory) Apply the internal set of SAX features to a given SAXParserFactory, by calling the SAXParserFactory.setFeature(String,boolean) method for each feature.
XmlSpec	copy() Create a copy of this XmlSpec instance.
boolean	getBackground() Get the background setting.
boolean	getBooleanProperty(String pPropName) Get the value of a boolean property.
boolean	getCloseStream() Get the close stream setting.
String	getEncoding() Get the encoding setting.
boolean	getFlush() Get the flush setting.
String	getFooter() Get the footer setting.
Map	getFunctionMap() Get a copy of the function mappings.
String	getHeader() Get the header setting.
boolean	getIgnoreBadRecords() Get the ignore bad records setting.
boolean	getIndent() Get the indent setting.
boolean	getNamespaceAware() Get the namespace aware setting.
Map	getNamespaceMap() Get a copy of the namespace mappings.
String	getProperty(String pPropName) Get the value of a string property.
String	getRicebridgePrefix() Get the namespace prefix to use for XML Manager special functions.
boolean	getSAXFeature(String pFeatureURI) Get the value of a SAX parser feature.
boolean	getStreamOutput() Get the stream output setting.
boolean	getValidating() Get the validating setting.
Map	getVariableMap() Get a copy of the variable mappings.
void	setBackground(boolean pBackground) Run the loading or saving process in a separate background Thread (default: false).
void	setCloseStream(boolean pCloseStream) Close any input or output streams used by the load or save process (default: true).
void	setEncoding(String pEncoding) Specify the character encoding to use for input and output (default: UTF-8).
void	setFlush(boolean pFlush) Flush the XML OutputStream after each record (default: true).
void	setFooter(String pFooter) Set the XML output footer text (default: empty).
void	setHeader(String pHeader) Set the XML output header text (default: empty).
void	setIgnoreBadRecords(boolean pIgnoreBadRecords) Ignore any bad records that are encountered during load and save operations and continue processing (default: false).
void	setIndent(boolean pIndent) Indent the output XML for human readability (default: true).
void	setNamespaceAware(boolean pNamespaceAware) Enables namespace support when parsing XML documents (default: true).
void	setProperty(String pPropName, boolean pValue) Set the value of a boolean property.
void	setProperty(String pPropName, String pValue) Set the value of a string property.
void	setRicebridgePrefix(String pPrefix) Set the namespace prefix to use for XML Manager special functions.
void	setSAXFeature(String pFeatureURI, boolean pValue) Set a URI-defined SAX parser feature.
void	setStreamOutput(boolean pStreamOutput) Enables streaming of XML to an OutputStream (default: false).
void	setValidating(boolean pValidating) Enables validation when parsing XML documents (default: false).
String	toString() Produce a textual description of the XML input and output settings, suitable for debugging.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING

Default encoding for XML files: UTF-8.

See Also:

Constant Field Values

PROP_encoding

public static final String PROP_encoding

See setEncoding(java.lang.String).

See Also:

Constant Field Values

PROP_indent

public static final String PROP_indent

See setIndent(boolean).

See Also:

Constant Field Values

PROP_flush

public static final String PROP_flush

See setFlush(boolean).

See Also:

Constant Field Values

PROP_header

public static final String PROP_header

See setHeader(java.lang.String).

See Also:

Constant Field Values

PROP_footer

public static final String PROP_footer

See setFooter(java.lang.String).

See Also:

Constant Field Values

PROP_background

public static final String PROP_background

See setBackground(boolean).

See Also:

Constant Field Values

PROP_ignorebadrecords

public static final String PROP_ignorebadrecords

See setIgnoreBadRecords(boolean).

See Also:

Constant Field Values

PROP_closestream

public static final String PROP_closestream

See setCloseStream(boolean).

See Also:

Constant Field Values

PROP_namespaceaware

public static final String PROP_namespaceaware

See setNamespaceAware(boolean).

See Also:

Constant Field Values

PROP_validating

public static final String PROP_validating

See setValidating(boolean).

See Also:

Constant Field Values

PROP_streamoutput

public static final String PROP_streamoutput

See setStreamOutput(boolean).

See Also:

Constant Field Values

Constructor Detail

XmlSpec

public XmlSpec()

Create a new default instance of XmlSpec, with default settings.

Method Detail

copy

public XmlSpec copy()

Create a copy of this XmlSpec instance.

getNamespaceMap

public Map getNamespaceMap()

Get a copy of the namespace mappings.

addNamespace

public void addNamespace(String pPrefix,
                         String pURI)

Add a namespace to the current namespace mappings.

In order to process XML documents that use namespaces, you must specify each namespace using this method. This allows you to use the prefixes specified here in your XPath expression in the RecordSpec.

Note that although you must specify a unique set of prefixes via this method, in the XML document, prefixes need not be unique, and only URIs are compared. The prefixes specified here are only for use in XPath expressions, and therefore must be unique within a set of expressions.

It is probably a good idea to use the same prefix as is used in the XML document, but this is not a requirement - prefixes are only placeholders for URIs.

By default, XML parsing is namespace aware. You can change this with the setNamespaceAware(boolean) method.

Parameters:

pPrefix - prefix identifier for use in XPath

pURI - URI identifier of namespace

See Also:

setRicebridgePrefix(java.lang.String)

getVariableMap

public Map getVariableMap()

Get a copy of the variable mappings.

addVariable

public void addVariable(String pLocalName,
                        Object pValue)

Add a variable for use in XPath expressions.

The value of the variable is specified as an object. This object will be interpreted in context. For text values use String objects, for numbers use Integers, and so on.

Variables specified via this method do not require a namespace prefix, and can be used directly in XPath expressions using the format: $foo.

Parameters:

pLocalName - local name of the variable, without namespace prefix

pValue - value of the variable as an object

See Also:

addVariable(String,String,Object)

addVariable

public void addVariable(String pLocalName,
                        String pNamespaceURI,
                        Object pValue)

Add a variable for use in XPath expressions, qualified with a namespace.

Use this method to place the variable into a given namespace. The namespace is specified using the namespace URI. However, the variable is accessed using the namespace prefix (namespaces are specified using the addNamespace method).

Variables specified via this method require a namespace prefix, and can be used directly in XPath expressions using the format: $ns:foo.

Parameters:

pLocalName - local name of the variable, without namespace prefix

pNamespaceURI - namespace for this variable

pValue - value of the variable as an object

See Also:

addVariable(String,Object)

getFunctionMap

public Map getFunctionMap()

Get a copy of the function mappings.

addFunction

public void addFunction(String pPrefix,
                        String pName,
                        Function pFunction)

Add a named function for use in XPath expressions.

You can extend the capabilities of XPath expressions by adding your own functions via this method. New functions are created by implementing the Jaxen Function interface.

Review the source code for the TrimFunction to see an example function implementation.

XML Manager has a number of special functions which are available for use in XPath expressions. These functions are normally identified with the rb prefix (this can be remapped using setRicebridgePrefix(java.lang.String).

Parameters:

pPrefix - namespace prefix for this function

pName - name of function as used in XPath

pFunction - object implmenting function

See Also:

Function

setRicebridgePrefix

public void setRicebridgePrefix(String pPrefix)

Set the namespace prefix to use for XML Manager special functions.

Special functions provided by XML Manager such as the xml() and trim() are not included in the standard list of XPath functions. To avoid future name clashes, these functions are placed in the Ricebridge namespace, with the default prefix rb.

Since you may wish to use the prefix rb for a different namespace, this method is provided to allow you to change the prefix of the Ricebridge namespace. If your source document uses the namespace rb it is sometimes useful to do this, but not always necessary. Prefixes used in the XPath expressions do not have to be the same as the prefixes used in the XML source document, as they are simply placeholders for the full namespace URI.

Note: you should call this method before setting your own namespaces to avoid accidentally renaming them.

Parameters:

pPrefix - prefix for Ricebridge namespace

See Also:

getRicebridgePrefix()

getRicebridgePrefix

public String getRicebridgePrefix()

Get the namespace prefix to use for XML Manager special functions.

See Also:

setRicebridgePrefix(java.lang.String)

setEncoding

public void setEncoding(String pEncoding)

Specify the character encoding to use for input and output (default: UTF-8).

XML files can be encoded in a number of different formats. Normally, UTF-8 format is assumed, but you may have to handle XML files in UTF-16 and other variants. In this case, you need to specify the character encoding of the file.

The subject of character encodings is beyond the scope of this documentation. However Sun maintains a web page on Java internationalization which you will find very useful.

Parameters:

pEncoding - encoding setting

See Also:

getEncoding()

getEncoding

public String getEncoding()

Get the encoding setting.

See Also:

setEncoding(java.lang.String)

setIndent

public void setIndent(boolean pIndent)

Indent the output XML for human readability (default: true).

When true, XML is output with a 2 space indent and element opening tags are placed on a newline. However, tags that contain text are not indented when that would alter the textual content of the tag.

When false, XML is output in as compact a form as possible, with no additional whitespace.

Parameters:

pIndent - indent setting

getIndent

public boolean getIndent()

Get the indent setting.

See Also:

setIndent(boolean)

setFlush

public void setFlush(boolean pFlush)

Flush the XML OutputStream after each record (default: true).

In general, this setting ensures that data is written out as quickly as possible.

Parameters:

pFlush - flush each data record to output

getFlush

public boolean getFlush()

Get the flush setting.

See Also:

setFlush(boolean)

setHeader

public void setHeader(String pHeader)

Set the XML output header text (default: empty).

Xml Manager does not output any XML header by default. Although headers such as

  <?xml version='1.0' encoding='UTF-8'?>
  

are common, they are not used by every XML file and also not by the canonical XML form. Thus you are free to specify your own XML header using this method, if required.

Note: when you are generating a list of records, without any root element, then you can also use this setting to specify the root element XML, so that your output will be well-formed. For example:

new RecordSpec("li", new String[] {"."} );

For the data set [{"foo"},{"bar"},{"que"}] his will generate something like:

  <li>foo</li>
  <li>bar</li>
  <li>que</li>
  

To add the initial <ul> and final </ul>, use the setHeader and setFooter(java.lang.String) methods:

  xmlSpec.setHeader("<ul>");
  xmlSpec.setFooter("</ul>");
  

Parameters:

pHeader - XML header text

See Also:

setFooter(java.lang.String)

getHeader

public String getHeader()

Get the header setting.

See Also:

setHeader(java.lang.String)

setFooter

public void setFooter(String pFooter)

Set the XML output footer text (default: empty).

Normally, you do not need to use this setting, as XML Manager generates well-formed XML when using a record XPath expression with two or more elements. When the record XPath only has one element however, a list is generated, which is not well-formed. You can use the setHeader(java.lang.String) and setFooter methods to provide a prefix and suffix for the generated XML so that it is well-formed. See the setHeader(java.lang.String) method for an example.

Parameters:

pFooter - XML header text

See Also:

setHeader(java.lang.String)

getFooter

public String getFooter()

Get the footer setting.

See Also:

setFooter(java.lang.String)

setBackground

public void setBackground(boolean pBackground)

Run the loading or saving process in a separate background Thread (default: false).

If your dataset or file is large or if handling the data is time consuming, then it may make sense to run the loading or saving process into a separate Thread.

By default all processing occurs in the calling code Thread and your code must wait for the load or save operation to complete. If you set the run in background setting to true, then processing is performed in a daemon Thread.

Parameters:

pBackground - run process in background

See Also:

getBackground()

getBackground

public boolean getBackground()

Get the background setting.

See Also:

setBackground(boolean)

setIgnoreBadRecords

public void setIgnoreBadRecords(boolean pIgnoreBadRecords)

Ignore any bad records that are encountered during load and save operations and continue processing (default: false).

When true, any internal processing exceptions or bad semantic records are stored internally and processing continues.

When false, internal processing exceptions and bad semantic records cause processing to halt and an XmlManagerException is thrown.

This settings allows you to process an entire set of records, even if some fail. Note that syntactically incorrect XML will always halt processing and that this setting does not affect that behaviour as XML parsers are required to stop when a syntax error is encountered. This setting is meant for cases where the data in the record fields is semantically invalid, as defined by your application. Thus for example, a bad record occurs when loading data if it cannot be saved to the database because a data field is too long. Also note that in the case of an XML syntax error, no BadRecord is stored, as there is no data available. Similarly, Stats.getTotalBadRecords() does not include records that failed due to an XML syntax error.

The XmlManager method XmlManager.getBadRecords() returns a list of all the bad records encountered. See the BadRecord class documentation for more details.

The Stats object returned from XmlManager.getStats() provides the method Stats.getTotalBadRecords() that tells you how many bad records were encountered.

Parameters:

pIgnoreBadRecords - ignore bad records

See Also:

getIgnoreBadRecords(), BadRecord, Stats.getTotalBadRecords()

getIgnoreBadRecords

public boolean getIgnoreBadRecords()

Get the ignore bad records setting.

See Also:

setIgnoreBadRecords(boolean)

setCloseStream

public void setCloseStream(boolean pCloseStream)

Close any input or output streams used by the load or save process (default: true).

This setting makes sure that InputStreams and OutputStreams provided to the XmlManager object are closed after use. Streams are used by methods such as XmlManager.load(InputStream,RecordSpec) and XmlManager.save(OutputStream,RecordSpec,List).

If you set this to false, make sure that you close any streams yourself after XmlManager has finished using them, or you will have resource leak.

Note that SAXParsers that fail to close their own internal streams may still give you problems.

Parameters:

pCloseStream - close streams after use

See Also:

getCloseStream()

getCloseStream

public boolean getCloseStream()

Get the close stream setting.

See Also:

setCloseStream(boolean)

setNamespaceAware

public void setNamespaceAware(boolean pNamespaceAware)

Enables namespace support when parsing XML documents (default: true).

When true any namespaces declared in the source XML document are supported in the XPath expressions.

When false, all elements in the source XML document are named as exactly as they appear, including prefixes. You should use exactly the same names and prefixes in the XPath expressions. In effect, the prefix is considered to be merely additional characters in the name, with no semantic value.

This setting is used directly to call the SAXParserFactory.setNamespaceAware(boolean) method.

Parameters:

pNamespaceAware - recognise namespaces in source XML

getNamespaceAware

public boolean getNamespaceAware()

Get the namespace aware setting.

See Also:

setNamespaceAware(boolean)

setValidating

public void setValidating(boolean pValidating)

Enables validation when parsing XML documents (default: false).

When true the source XML document is validated against any defined DTD or schemas.

When false the source XML document must be well-formed, but is not validated.

This setting is used directly to call the SAXParserFactory.setValidating(boolean) method.

Parameters:

pValidating - validate source XML

getValidating

public boolean getValidating()

Get the validating setting.

See Also:

setValidating(boolean)

setStreamOutput

public void setStreamOutput(boolean pStreamOutput)

Enables streaming of XML to an OutputStream (default: false).

When true the closing elements of the XML document are not emitted after each save. Instead they must be manually output using the special XmlManager.finishSave() method.

When false, each save writes out a full XML document, with all closing tags.

This setting allows you to use an open OutputStream that appends XML to it's destination as a stream. Each time you call a save method on the open OutputStream, the record data is appended as additional XML elements. When all data has been output, you will then need to call the special XmlManager.finishSave() method to complete the XML document.

NOTE: if you set this setting to true, then setCloseStream(boolean) is set to false. The setCloseStream(boolean) setting must be false otherwise your open OutputStream will be automatically closed after the first save.

Parameters:

pStreamOutput - output XML as a stream

getStreamOutput

public boolean getStreamOutput()

Get the stream output setting.

See Also:

setStreamOutput(boolean)

setProperty

public void setProperty(String pPropName,
                        boolean pValue)

Set the value of a boolean property.

Parameters:

pPropName - boolean property name

pValue - boolean value

See Also:

setProperty(String,String)

setProperty

public void setProperty(String pPropName,
                        String pValue)

Set the value of a string property.

All settings are stored dynamically using a String value for the property name. This enables dynamic access to settings at runtime. The names of the predefined settings are encoded in the PROP_* declarations

Parameters:

pPropName - string property name

pValue - string value

getProperty

public String getProperty(String pPropName)

Get the value of a string property.

If property has not previously been defined, returns an empty string.

Parameters:

pPropName - of string property

getBooleanProperty

public boolean getBooleanProperty(String pPropName)

Get the value of a boolean property.

If property has not previously been defined, returns false.

Parameters:

pPropName - name of boolean property

setSAXFeature

public void setSAXFeature(String pFeatureURI,
                          boolean pValue)

Set a URI-defined SAX parser feature.

XML Manager uses a SAX parser for low-level event-based access to XML data streams. SAX parsers provide a feature set that can be controlled using special URI identifiers for the features. This method simply provides direct access to the SAXParserFactory.setFeature(String,boolean) method.

Parameters:

pFeatureURI - URI identifier of SAX feature

pValue - boolean flag

See Also:

SAXParserFactory

getSAXFeature

public boolean getSAXFeature(String pFeatureURI)

Get the value of a SAX parser feature.

Parameters:

pFeatureURI - URI identifier of SAX feature

See Also:

setSAXFeature(String,boolean), SAXParserFactory

applySAXFeatures

public void applySAXFeatures(SAXParserFactory pSAXParserFactory)

Apply the internal set of SAX features to a given SAXParserFactory, by calling the SAXParserFactory.setFeature(String,boolean) method for each feature.

Parameters:

pSAXParserFactory - SAXParserFactory instance

toString

public String toString()

Produce a textual description of the XML input and output settings, suitable for debugging.