uk.ac.ebi.intact.util
Class XmlBuilder

java.lang.Object
  |
  +--uk.ac.ebi.intact.util.XmlBuilder

All Implemented Interfaces:

java.io.Serializable

public class XmlBuilder

extends java.lang.Object

implements java.io.Serializable

This utility class provides operations for generating XML, typically in the form of Document or Element objects. The main purpose of having XML genration as a seperate facility is to allow generation of "partial" XML documents which are only completed when necessary. Tools such as Castor only provide the means to generate a complete XML document, which can become very memory-intensive for large data sets.

Author:

Chris Lewington

See Also:

Serialized Form

Field Summary

static int	CONTRACT_NODES identifies a contract request
static int	EXPAND_NODES Identifies an expand request

Constructor Summary

XmlBuilder()
Note that this default constructor will build a default IntactHelper object with default configuration settings.

XmlBuilder(IntactHelper helper)
Sets up an XML builder with suitable persistent store access.

Method Summary

org.w3c.dom.Element	buildCompactElem(java.lang.Object item) Provides a 'compact' expansion of an object.
org.w3c.dom.Element	buildFullElem(java.lang.Object obj) Provides a 'complete' expansion of an object.
org.w3c.dom.Element	buildPartialElem(java.lang.Object obj, java.util.Collection fieldsToIgnore) Provides a 'partial' expansion of an object.
org.w3c.dom.Document	buildXml(java.util.Collection items) This method builds an XML Document for a Collection of objects.
org.w3c.dom.Document	buildXml(java.lang.Object obj) Convenience method to build a Document for one object only.
org.w3c.dom.Document	modifyDoc(org.w3c.dom.Document dc, java.util.Collection ids, int mode) This method allows for modification of a given Document.

Methods inherited from class java.lang.Object

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

Field Detail

EXPAND_NODES

public static final int EXPAND_NODES

Identifies an expand request

See Also:

Constant Field Values

CONTRACT_NODES

public static final int CONTRACT_NODES

identifies a contract request

See Also:

Constant Field Values

Constructor Detail

XmlBuilder

public XmlBuilder(IntactHelper helper)
           throws IntactException

Sets up an XML builder with suitable persistent store access. Currently this requires a suitable IntactHelper object to ensure the caller's connection details can be reused (persistent storage access is required here since sometimes details of objects referenced from elsewhere by eg AC only may not yet be materialised). Note that if the builder is to be used in a web application, this is the correct constructor to be used.

Parameters:

helper - The intact helper instance used by the caller - this allows the builder to use the same data store access configurations.

Throws:

IntactException - thrown if no helper object was supplied

XmlBuilder

public XmlBuilder()
           throws IntactException

Note that this default constructor will build a default IntactHelper object with default configuration settings. This is fine for 'standalone' usage but can cause problems in a web environment where connection profiles are more important. For use by web applications it is recommended that the constructor taking a IntactHlper instance is used.

Throws:

IntactException - thrown if even a default helper object could not be created.

Method Detail

buildXml

public org.w3c.dom.Document buildXml(java.lang.Object obj)
                              throws javax.xml.parsers.ParserConfigurationException

Convenience method to build a Document for one object only.

Parameters:

obj - The object for which we want a Document built

Returns:

Document The object as an Element within a Document

Throws:

javax.xml.parsers.ParserConfigurationException - thrown if t6here was a problem parsing

buildXml

public org.w3c.dom.Document buildXml(java.util.Collection items)
                              throws javax.xml.parsers.ParserConfigurationException

This method builds an XML Document for a Collection of objects. The Document produced is at the "first level" of the object tree, ie only the String and primitive attributes are generated. A deeper level of document generation (expanding object references and Collections) can be obtained from the modifyDoc method. It is assumed that all objects passed as parameters will have a non-null AC attribute set to allow for cacheing.

Parameters:

items - The group of objects for which an XML format is required

Returns:

Document The generated XML in Document format (empty if nothing generated)

Throws:

javax.xml.parsers.ParserConfigurationException - thrown if it was not possible to create a document builder

modifyDoc

public org.w3c.dom.Document modifyDoc(org.w3c.dom.Document dc,
                                      java.util.Collection ids,
                                      int mode)
                               throws javax.xml.parsers.ParserConfigurationException

This method allows for modification of a given Document. Specifically, the Document tree has specific nodes changed as determined by the set of ACs provided as a parameter and also the operation mode. Note that if a particular AC occurs more than once in the DOM tree then *all* DOM Elements found with that AC will be amodified with the same specified mode.

Parameters:

dc - The Document to be expanded

ids - A Collection of the items (identified by AC) to be expanded

mode - The mode of operation to be carried out (eg expand, contract etc)

Returns:

Document the expanded XML Document or the original Document if no changes were performed. If no Document object was supplied as an argument, null is returned

Throws:

javax.xml.parsers.ParserConfigurationException - thrown if a document builder could not be created

buildCompactElem

public org.w3c.dom.Element buildCompactElem(java.lang.Object item)
                                     throws javax.xml.parsers.ParserConfigurationException

Provides a 'compact' expansion of an object. That is, only the String, primitive and any Timestamp attributes are generated. Although Timestamps are strictly speaking reference types they are usually (like Strings) included as attributes rather than Elements in their own right.

NB the 'Timestamp' considered here is the java.sql.Timestamp class - this may, therefore, be intact-specific.

Parameters:

item - The object to expand

Returns:

Element The DOM Element representing the expanded object (empty if nothing is done)

Throws:

javax.xml.parsers.ParserConfigurationException - thrown if a document builder could not be created

java.lang.NullPointerException - if a null object parameter is supplied

buildFullElem

public org.w3c.dom.Element buildFullElem(java.lang.Object obj)
                                  throws javax.xml.parsers.ParserConfigurationException

Provides a 'complete' expansion of an object. That is, all references (other than Strings and java.sql.Timestamps) and Collections are expanded (but each only to a 'compact' level).

Parameters:

obj - The object to expand

Returns:

Element The DOM Element representing the expanded object (at least compact)

Throws:

javax.xml.parsers.ParserConfigurationException - thrown if a document builder could not be created

java.lang.NullPointerException - If the argument object is null

buildPartialElem

public org.w3c.dom.Element buildPartialElem(java.lang.Object obj,
                                            java.util.Collection fieldsToIgnore)
                                     throws javax.xml.parsers.ParserConfigurationException

Provides a 'partial' expansion of an object. References and Collections whose fields are not in the set of ones to ingore are expanded. Note that attributes of the object (ie Strings, primitives etc) will always be defined - so a compact element will be created.

Parameters:

obj - The object to expand

fieldsToIgnore - The object fields which should not be expanded. Expected to be Strings.

Returns:

Element The DOM Element representing the expanded object (at least compact)

Throws:

javax.xml.parsers.ParserConfigurationException - thron if a document builder could not be created

java.lang.NullPointerException - If the argument object is null