ecologylab.xml
Class ElementState

java.lang.Object
  ecologylab.generic.Debug
      ecologylab.xml.ElementState

All Implemented Interfaces:

OptimizationTypes, XMLTranslationExceptionTypes

Direct Known Subclasses:

AllPermissionsElement, AngularCoord, Argument, ArrayListState, AssetState, AssociationElement, AuthenticationList, AuthenticationListEntry, Author, Body, Book, Channel2, Choice, ClassTagged, Composed, Content, ContributorList, Coordinates, Credit, DateList, Dc, DcTag, Description, Description, DoubleSlot, Epilogue, Feedburner, FieldTagged, GeoCoordinate, GPSDatum, Group, HashMapState, HashSetState, Header, HomepageElement, Icon, InformationElement, IntState, Item, Itunes, JnlpState, Keyword, Kml, KmlObject, Line2DDoubleState, Logging, Media, MenuElement, MetaPref, OfflineAllowedElement, Opml, Param, Point2DDoubleState, Prologue, RangeFloatState, RangeIntState, RangeState, RDFState, Record, Record, RectangularShape, RelatedContentElement, ResourceElement, RestSearchResult, Result, ResultsInfo, RssState, SearchResults, Seed, ServiceMessage, ShortcutElement, StringState, SVData, SynchronizedHashMapState, TestFloats, TestScalarCollection, TestXml, TestXMLTag, Thumbnail, ThumbnailState, TitleList, Vector2d, VectorState, XmlState

public class ElementState
extends Debug
implements OptimizationTypes, XMLTranslationExceptionTypes

This class is the heart of the ecologylab.xml translation framework.

To use the framework, the programmer must define a tree of objects derived from this class. The public fields in each of these derived objects correspond to the XML DOM. The declarations of attribute fields must preceed thos for nested XML elements. Attributes are built directly from Strings, using classes derived from

Version:

2.9

Author:

Andruid Kerne, Madhur Khandelwal

Nested Class Summary

protected class	ElementState.ClassToCollectionMap Convenience for specifying what collection to put objects of a given type into, where there is a clear mapping based on type (class).
static class	ElementState.DeclarationStyle These are the styles for declaring fields as translated to XML.
static interface	ElementState.xml_attribute Metalanguage declaration that tells ecologylab.xml translators that each Field it is applied to as an annotation is a scalar-value, which should be represented in XML as an attribute.
static interface	ElementState.xml_class Supplementary metalanguage declaration that can be applied only to a field.
static interface	ElementState.xml_classes Supplementary metalanguage declaration that can be applied only to a field.
static interface	ElementState.xml_collection Metalanguage declaration that tells ecologylab.xml translators that each Field it is applied to as an annotation is of type Collection.
static interface	ElementState.xml_leaf Metalanguage declaration that tells ecologylab.xml translators that each Field it is applied to as an annotation is a scalar-value, which should be represented in XML as a leaf node: an XML element with a single text node child, which represents the value.
static interface	ElementState.xml_map Metalanguage declaration that tells ecologylab.xml translators that each Field it is applied to as an annotation is of type Map.
static interface	ElementState.xml_nested Metalanguage declaration that tells ecologylab.xml translators that each Field it is applied to as an annotation is represented in XML by a (non-leaf) nested child element.
static interface	ElementState.xml_tag Metalanguage declaration that can be applied either to field or to class declarations.

Field Summary

static int	CDATA Value for the leaf annotation that specifies translation to XML as CDATA.
protected static int	ESTIMATE_CHARS_PER_FIELD
static short	FLOATING_PRECISION_OFF Constant indicating that floating precision cutoff is disabled.
protected static java.lang.Class[]	MARSHALLING_PARAMS Used for argument marshalling with reflection to access a set method that takes a String as an argument.
static int	NORMAL Value for the leaf annotation that specifies translation to XML without CDATA.
static int	UTF16
static int	UTF16_LE
static int	UTF8
protected static java.lang.String	XML_FILE_HEADER xml header

Fields inherited from interface ecologylab.xml.OptimizationTypes

BAD_FIELD, COLLECTION_ELEMENT, COLLECTION_SCALAR, IGNORED_ATTRIBUTE, IGNORED_ELEMENT, LEAF_NODE_VALUE, MAP_ELEMENT, MAP_SCALAR, NAME_SPACE_ATTRIBUTE, NAME_SPACE_LEAF_NODE, NAME_SPACE_MASK, NAME_SPACE_NESTED_ELEMENT, NAMESPACE_IGNORED_ELEMENT, NAMESPACE_TRIAL_ELEMENT, OTHER_NESTED_ELEMENT, REGULAR_ATTRIBUTE, REGULAR_NESTED_ELEMENT, ROOT, UNSET_TYPE, XMLNS_ATTRIBUTE, XMLNS_IGNORED

Fields inherited from interface ecologylab.xml.XMLTranslationExceptionTypes

FILE_NOT_FOUND, IO_EXCEPTION, NULL_PURL, UNKNOWN

Constructor Summary

ElementState()
Construct.

Method Summary

protected void	addNestedElement(ElementState elementState) This is the hook that enables programmers to do something special when handling a nested XML element and its associate ElementState (subclass), by overriding this method and providing a custom implementation.
protected void	addNestedElement(ecologylab.xml.NodeToJavaOptimizations pte, org.w3c.dom.Node childNode) Old-school DOM approach.
protected void	appendTextNodeString(java.lang.String newText) Called during translateFromXML().
static org.w3c.dom.Document	buildDOM(java.io.File file) This method creates a DOM Document from the local XML file.
static org.w3c.dom.Document	buildDOM(java.io.InputStream inStream) This method creates a DOM Document from the XML file at a given URI, which could be a local file or a URL.
static org.w3c.dom.Document	buildDOM(ParsedURL purl)
static org.w3c.dom.Document	buildDOM(java.lang.String xmlFileOrURLName) This method creates a DOM Document from the XML file at a given URI, which could be a local file or a URL.
static org.w3c.dom.Document	buildDOM(java.net.URL url) This method creates a DOM Document from the XML file at a given URL.
static org.w3c.dom.Document	buildDOMFromXMLCharSequence(java.lang.CharSequence charSequence, int charsetType) This method creates a DOM Document from an XML-formatted String.
static org.w3c.dom.Document	buildDOMFromXMLString(java.lang.CharSequence charSequence) This method creates a DOM Document from an XML-formatted String, encoded as UTF8.
void	checkAnnotation()
protected boolean	convertNameStyles() Specifies automatic conversion from XML style names (e.g.
protected void	createChildHook(ElementState child) Perform custom processing on the newly created child node, just before it is added to this.
protected ecologylab.xml.FieldToXMLOptimizations	fieldToXMLOptimizations(java.lang.reflect.Field field, java.lang.Class<? extends ElementState> thatClass) Get a tag translation object that corresponds to the fieldName, with this class.
protected short	floatingPrecision() Returns the precision of floating point numbers associated with this instance of ElementState.
protected java.util.Collection<? extends ElementState>	getCollection(java.lang.Class thatClass) When translating from XML, if a tag is encountered with no matching field, perhaps it belongs in a Collection.
ElementState	getElementStateById(java.lang.String id) The DOM classic accessor method.
protected java.util.Map	getMap(java.lang.Class thatClass) When translating from XML, if a tag is encountered with no matching field, perhaps it belongs in a Collection.
ElementState	getNestedNameSpace(java.lang.String id) Either lookup an existing Nested Namespace object, or form a new one, map it, and return it.
java.lang.String	getTextNodeString()
protected java.lang.String[]	leafElementFieldNames() An array of Strings with the names of the leaf elements.
ElementState	lookupNestedNameSpace(java.lang.String id) Lookup an ElementState subclass representing the scope of the nested XML Namespace in this.
protected Optimizations	optimizations()
ElementState	parent()
protected void	postTranslationProcessingHook() Perform custom processing immediately after all translation from XML is completed.
protected void	preTranslationProcessingHook() Perform custom processing immediately before translating this to XML.
void	recycle() Clear data structures and references to enable garbage collecting of resources associated with this.
static void	setDeclarationStyle(ElementState.DeclarationStyle ds)
protected boolean	setFieldUsingTypeRegistry(java.lang.reflect.Field field, java.lang.String fieldValue) Set a field that is an extended primitive -- a non ElementState -- using the type registry.
void	setFloatingPrecision(short floatingPrecision)
void	setParent(ElementState parent) Set the parent of this, to create the tree structure.
static void	setUseDOMForTranslateTo(boolean value) Set to true to use the DOM parser by default for translateToXML().
static ElementState	translateFromXML(java.io.File xmlFile, TranslationSpace translationSpace) Translate a file from XML to a strongly typed tree of XML objects.
static ElementState	translateFromXML(java.io.InputStream xmlStream, TranslationSpace translationSpace) Translate an InputStream from XML to a strongly typed tree of XML objects.
static ElementState	translateFromXML(ParsedURL purl, TranslationSpace translationSpace) Translate data from a ParseURL from XML to a strongly typed tree of XML objects.
static ElementState	translateFromXML(java.lang.String fileName, TranslationSpace translationSpace) Translate a file XML to a strongly typed tree of XML objects.
static ElementState	translateFromXML(java.net.URL url, TranslationSpace translationSpace)
static ElementState	translateFromXMLCharSequence(java.lang.CharSequence xmlString, TranslationSpace translationSpace) Translate a String of XML to a strongly typed tree of XML objects.
static ElementState	translateFromXMLDOM(org.w3c.dom.Document doc, TranslationSpace translationSpace) Given the Document object for an XML DOM, builds a tree of equivalent ElementState objects.
static ElementState	translateFromXMLDOM(java.io.File xmlFile, TranslationSpace translationSpace) Translate a file from XML to a strongly typed tree of XML objects.
static ElementState	translateFromXMLDOM(java.io.InputStream xmlStream, TranslationSpace nameSpace) Given an XML-formatted String, builds a tree of equivalent ElementState objects.
static ElementState	translateFromXMLDOM(ParsedURL purl, TranslationSpace translationSpace) Given the URL of a valid XML document, reads the document and builds a tree of equivalent ElementState objects.
static ElementState	translateFromXMLDOM(java.lang.String fileName, TranslationSpace translationSpace) Given the name of a valid XML file, reads the file and builds a tree of equivalent ElementState objects.
static ElementState	translateFromXMLDOM(java.net.URL xmlDocumentURL, TranslationSpace translationSpace) Given the URL of a valid XML document, reads the document and builds a tree of equivalent ElementState objects.
static ElementState	translateFromXMLDOMCharSequence(java.lang.CharSequence charSequence, int charsetType, TranslationSpace translationSpace) Given an XML-formatted String, builds a tree of equivalent ElementState objects.
static ElementState	translateFromXMLDOMCharSequence(java.lang.CharSequence charSequence, TranslationSpace translationSpace) Given an XML-formatted String, uses charset type UTF-8 to create a stream, and build a tree of equivalent ElementState objects.
static ElementState	translateFromXMLRootNode(org.w3c.dom.Node xmlRootNode, TranslationSpace translationSpace) A recursive DOM-based translation translateFromXML(...).
static ElementState	translateFromXMLSAX(java.lang.CharSequence charSequence, TranslationSpace translationSpace) Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.
static ElementState	translateFromXMLSAX(java.io.File file, TranslationSpace translationSpace) Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.
static ElementState	translateFromXMLSAX(java.io.InputStream inputStream, TranslationSpace translationSpace) Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.
static ElementState	translateFromXMLSAX(ParsedURL purl, TranslationSpace translationSpace) Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.
static ElementState	translateFromXMLSAX(java.net.URL url, TranslationSpace translationSpace) Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.
org.w3c.dom.Document	translateToDOM() Create a W3C Document object from this.
java.lang.StringBuilder	translateToXML() Translates a tree of ElementState objects into an equivalent XML string.
void	translateToXML(java.lang.Appendable appendable) Translates a tree of ElementState objects, and writes the output to the Appendable passed in.
void	translateToXML(java.io.File outputFile) Translates a tree of ElementState objects, and writes the output to the File passed in.
java.lang.StringBuilder	translateToXML(java.lang.StringBuilder buffy) Translates a tree of ElementState objects into equivalent XML in a StringBuilder.
void	writePrettyXML(java.io.File xmlFile) Translate to XML, then write the result to a file.
void	writePrettyXML(java.io.OutputStream outputStream) Translate to XML, then write the result to a file.
void	writePrettyXML(java.lang.String xmlFileName) Translate to XML, then write the result to a file, while formatting nicely.

Methods inherited from class ecologylab.generic.Debug

classSimpleName, closeLoggingFile, debug, debug, debug, debug, debugA, debugA, debugA, debugI, debugI, debugI, error, error, getClassName, getClassName, getInteractive, getPackageName, getPackageName, getPackageName, initialize, level, level, level, logToFile, print, print, println, println, println, println, println, println, printlnA, printlnA, printlnA, printlnI, printlnI, printlnI, printlnI, setLoggingFile, show, show, superString, toggleInteractive, toString, toString, warning, warning, weird, weird

Methods inherited from class java.lang.Object

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

Field Detail

UTF16_LE

public static final int UTF16_LE

See Also:

Constant Field Values

UTF16

public static final int UTF16

See Also:

Constant Field Values

UTF8

public static final int UTF8

See Also:

Constant Field Values

XML_FILE_HEADER

protected static final java.lang.String XML_FILE_HEADER

xml header

See Also:

Constant Field Values

ESTIMATE_CHARS_PER_FIELD

protected static final int ESTIMATE_CHARS_PER_FIELD

See Also:

Constant Field Values

MARSHALLING_PARAMS

protected static java.lang.Class[] MARSHALLING_PARAMS

Used for argument marshalling with reflection to access a set method that takes a String as an argument.

FLOATING_PRECISION_OFF

public static final short FLOATING_PRECISION_OFF

Constant indicating that floating precision cutoff is disabled. If floatingPrecision is set to this value, then all available decimal places will be emitted.

See Also:

Constant Field Values

CDATA

public static final int CDATA

Value for the leaf annotation that specifies translation to XML as CDATA.

See Also:

Constant Field Values

NORMAL

public static final int NORMAL

Value for the leaf annotation that specifies translation to XML without CDATA.

See Also:

Constant Field Values

Constructor Detail

ElementState

public ElementState()

Construct. Create a link to a root optimizations object.

Method Detail

translateToXML

public java.lang.StringBuilder translateToXML()
                                       throws XMLTranslationException

Translates a tree of ElementState objects into an equivalent XML string. Uses Java reflection to iterate through the public fields of the object. When primitive types are found, they are translated into attributes. When objects derived from ElementState are found, they are recursively translated into nested elements.

Note: in the declaration of this, all nested elements must be after all attributes.

The result is a hierarchichal XML structure.

Note: to keep XML files from growing unduly large, there is a default value for each type. Attributes which are set to the default value (for that type), are not emitted.

Returns:

the generated xml string, in a Reusable SBtringBuilder

Throws:

XMLTranslationException - if there is a problem with the structure. Specifically, in each ElementState object, fields for attributes must be declared before all fields for nested elements (those derived from ElementState). If there is any public field which is not derived from ElementState declared after the declaration for 1 or more ElementState instance variables, this exception will be thrown.

translateToXML

public java.lang.StringBuilder translateToXML(java.lang.StringBuilder buffy)
                                       throws XMLTranslationException

Translates a tree of ElementState objects into equivalent XML in a StringBuilder. Uses Java reflection to iterate through the public fields of the object. When primitive types are found, they are translated into attributes. When objects derived from ElementState are found, they are recursively translated into nested elements -- if doRecursiveDescent is true).

Note: in the declaration of this, all nested elements must be after all attributes.

The result is a hierarchichal XML structure.

Note: to keep XML files from growing unduly large, there is a default value for each type. Attributes which are set to the default value (for that type), are not emitted.

Parameters:

buffy - StringBuilder to translate into, or null if you want one created for you.

Returns:

the generated xml string

Throws:

XMLTranslationException - if a problem arises during translation. Problems with Field access are possible, but very unlikely.

translateToXML

public void translateToXML(java.io.File outputFile)
                    throws XMLTranslationException,
                           java.io.IOException

Translates a tree of ElementState objects, and writes the output to the File passed in.

Uses Java reflection to iterate through the public fields of the object. When primitive types are found, they are translated into attributes. When objects derived from ElementState are found, they are recursively translated into nested elements.

The result is a hierarchichal XML structure.

Note: to keep XML files from growing unduly large, there is a default value for each type. Attributes which are set to the default value (for that type), are not emitted.

Makes directories if necessary.

Parameters:

outputFile - File to write the XML to.

Throws:

XMLTranslationException - if a problem arises during translation. Problems with Field access are possible, but very unlikely.

java.io.IOException - If there are problems with the file.

translateToXML

public void translateToXML(java.lang.Appendable appendable)
                    throws XMLTranslationException

Translates a tree of ElementState objects, and writes the output to the Appendable passed in.

Uses Java reflection to iterate through the public fields of the object. When primitive types are found, they are translated into attributes. When objects derived from ElementState are found, they are recursively translated into nested elements.

The result is a hierarchichal XML structure.

Note: to keep XML files from growing unduly large, there is a default value for each type. Attributes which are set to the default value (for that type), are not emitted.

Parameters:

appendable - Appendable to translate into. Must be non-null. Can be a Writer, OutputStream, ...

Throws:

XMLTranslationException - if a problem arises during translation. The most likely cause is an IOException.

Problems with Field access are possible, but very unlikely.

translateToDOM

public org.w3c.dom.Document translateToDOM()
                                    throws XMLTranslationException

Create a W3C Document object from this. That is, go back, from our nice, strongly typed tree, to an untyped one.

Returns:

Throws:

XMLTranslationException

floatingPrecision

protected short floatingPrecision()

Returns the precision of floating point numbers associated with this instance of ElementState. Subclasses may override this method, which is particularly useful if a class should have a certain floating point precision associated with it.

Returns:

the floating point precision to be used when translating this to XML.

translateFromXMLDOM

public static ElementState translateFromXMLDOM(ParsedURL purl,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Given the URL of a valid XML document, reads the document and builds a tree of equivalent ElementState objects.

That is, translates the XML into a tree of Java objects, each of which is an instance of a subclass of ElementState. The operation of the method is predicated on the existence of a tree of classes derived from ElementState, which corresponds to the structure of the XML DOM that needs to be parsed.

Before calling the version of this method with this signature, the programmer needs to create a DOM from the XML file. S/he passes it to this method to create a Java hierarchy equivalent to the DOM.

Recursively parses the XML nodes in DFS order and translates them into a tree of state-objects.

This method used to be called builtStateObject(...).

Parameters:

purl - ParsedURL for the XML document that needs to be translated.

translationSpace - NameSpace that provides basis for translation.

Returns:

Parent ElementState object of the corresponding Java tree.

Throws:

XMLTranslationException

translateFromXML

public static ElementState translateFromXML(ParsedURL purl,
                                            TranslationSpace translationSpace)
                                     throws XMLTranslationException

Translate data from a ParseURL from XML to a strongly typed tree of XML objects. Use SAX or DOM parsing depending on the value of useDOMForTranslateTo.

Parameters:

xmlStream - An InputStream to the XML that needs to be translated.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

Strongly typed tree of ElementState objects.

Throws:

XMLTranslationException

translateFromXMLDOM

public static ElementState translateFromXMLDOM(java.net.URL xmlDocumentURL,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Given the URL of a valid XML document, reads the document and builds a tree of equivalent ElementState objects.

That is, translates the XML into a tree of Java objects, each of which is an instance of a subclass of ElementState. The operation of the method is predicated on the existence of a tree of classes derived from ElementState, which corresponds to the structure of the XML DOM that needs to be parsed.

Before calling the version of this method with this signature, the programmer needs to create a DOM from the XML file. S/he passes it to this method to create a Java hierarchy equivalent to the DOM.

Recursively parses the XML nodes in DFS order and translates them into a tree of state-objects.

Uses the default globalNameSpace as the basis for translation.

This method used to be called builtStateObject(...).

Parameters:

xmlDocumentURL - URL for the XML document that needs to be translated.

translationSpace - NameSpace that provides basis for translation.

Returns:

Parent ElementState object of the corresponding Java tree.

Throws:

XMLTranslationException

translateFromXML

public static ElementState translateFromXML(java.net.URL url,
                                            TranslationSpace translationSpace)
                                     throws XMLTranslationException

Throws:

XMLTranslationException

translateFromXMLDOM

public static ElementState translateFromXMLDOM(java.io.File xmlFile,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Translate a file from XML to a strongly typed tree of XML objects. Use DOM parsing -- builds an intermediate DOM object.

Parameters:

xmlFile - XML source material.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

Strongly typed tree of ElementState objects.

Throws:

XMLTranslationException

translateFromXML

public static ElementState translateFromXML(java.io.File xmlFile,
                                            TranslationSpace translationSpace)
                                     throws XMLTranslationException

Translate a file from XML to a strongly typed tree of XML objects. Use SAX or DOM parsing depending on the value of useDOMForTranslateTo.

Parameters:

xmlFile - XML source material.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

Strongly typed tree of ElementState objects.

Throws:

XMLTranslationException

translateFromXMLDOM

public static ElementState translateFromXMLDOM(java.lang.String fileName,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Given the name of a valid XML file, reads the file and builds a tree of equivalent ElementState objects. That is, translates the XML into a tree of Java objects, each of which is an instance of a subclass of ElementState. The operation of the method is predicated on the existence of a tree of classes derived from ElementState, which corresponds to the structure of the XML DOM that needs to be parsed. Before calling the version of this method with this signature, the programmer needs to create a DOM from the XML file. S/he passes it to this method to create a Java hierarchy equivalent to the DOM. Recursively parses the XML nodes in DFS order and translates them into a tree of state-objects.

Parameters:

fileName - the name of the XML file that needs to be translated.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

the parent ElementState object of the corresponding Java tree.

Throws:

XMLTranslationException

translateFromXML

public static ElementState translateFromXML(java.lang.String fileName,
                                            TranslationSpace translationSpace)
                                     throws XMLTranslationException

Translate a file XML to a strongly typed tree of XML objects. Use SAX or DOM parsing depending on the value of useDOMForTranslateTo.

Parameters:

fileName - the name of the XML file that needs to be translated.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

Strongly typed tree of ElementState objects.

Throws:

XMLTranslationException

translateFromXMLDOM

public static ElementState translateFromXMLDOM(java.io.InputStream xmlStream,
                                               TranslationSpace nameSpace)
                                        throws XMLTranslationException

Given an XML-formatted String, builds a tree of equivalent ElementState objects.

That is, translates the XML into a tree of Java objects, each of which is an instance of a subclass of ElementState. The operation of the method is predicated on the existence of a tree of classes derived from ElementState, which corresponds to the structure of the XML DOM that needs to be parsed.

Build a DOM first. Then, recursively parses the XML nodes in DFS order and translates them into a tree of state-objects.

Parameters:

xmlStream - An InputStream to the XML that needs to be translated.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

the parent ElementState object of the corresponding Java tree.

Throws:

XMLTranslationException

translateFromXML

public static ElementState translateFromXML(java.io.InputStream xmlStream,
                                            TranslationSpace translationSpace)
                                     throws XMLTranslationException

Translate an InputStream from XML to a strongly typed tree of XML objects. Use SAX or DOM parsing depending on the value of useDOMForTranslateTo.

Parameters:

xmlStream - An InputStream to the XML that needs to be translated.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

Strongly typed tree of ElementState objects.

Throws:

XMLTranslationException

translateFromXMLDOMCharSequence

public static ElementState translateFromXMLDOMCharSequence(java.lang.CharSequence charSequence,
                                                           int charsetType,
                                                           TranslationSpace translationSpace)
                                                    throws XMLTranslationException

Given an XML-formatted String, builds a tree of equivalent ElementState objects. That is, translates the XML into a tree of Java objects, each of which is an instance of a subclass of ElementState. The operation of the method is predicated on the existence of a tree of classes derived from ElementState, which corresponds to the structure of the XML DOM that needs to be parsed. Before calling the version of this method with this signature, the programmer needs to create a DOM from the XML file. S/he passes it to this method to create a Java hierarchy equivalent to the DOM. Recursively parses the XML nodes in DFS order and translates them into a tree of state-objects. This method used to be called builtStateObject(...).

Parameters:

charSequence - the actual XML that needs to be translated.

charsetType - A constant from ecologylab.generic.StringInputStream. 0 for UTF16_LE. 1 for UTF16. 2 for UTF8.

Returns:

the parent ElementState object of the corresponding Java tree.

Throws:

XMLTranslationException

translateFromXMLDOMCharSequence

public static ElementState translateFromXMLDOMCharSequence(java.lang.CharSequence charSequence,
                                                           TranslationSpace translationSpace)
                                                    throws XMLTranslationException

Given an XML-formatted String, uses charset type UTF-8 to create a stream, and build a tree of equivalent ElementState objects. That is, translates the XML into a tree of Java objects, each of which is an instance of a subclass of ElementState. The operation of the method is predicated on the existence of a tree of classes derived from ElementState, which corresponds to the structure of the XML DOM that needs to be parsed. Before calling the version of this method with this signature, the programmer needs to create a DOM from the XML file. S/he passes it to this method to create a Java hierarchy equivalent to the DOM. Recursively parses the XML nodes in DFS order and translates them into a tree of state-objects. Uses the default UTF8 charset. This method used to be called builtStateObject(...).

Parameters:

charSequence - the actual XML that needs to be translated.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

Parent ElementState object of the corresponding Java tree.

Throws:

XMLTranslationException

translateFromXMLCharSequence

public static ElementState translateFromXMLCharSequence(java.lang.CharSequence xmlString,
                                                        TranslationSpace translationSpace)
                                                 throws XMLTranslationException

Translate a String of XML to a strongly typed tree of XML objects. Use SAX or DOM parsing depending on the value of useDOMForTranslateTo.

Parameters:

xmlString - the actual XML that needs to be translated.

translationSpace - Specifies mapping from XML nodes (elements and attributes) to Java types.

Returns:

Strongly typed tree of ElementState objects.

Throws:

XMLTranslationException

translateFromXMLDOM

public static ElementState translateFromXMLDOM(org.w3c.dom.Document doc,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Given the Document object for an XML DOM, builds a tree of equivalent ElementState objects.

That is, translates the XML into a tree of Java objects, each of which is an instance of a subclass of ElementState. The operation of the method is predicated on the existence of a tree of classes derived from ElementState, which corresponds to the structure of the XML DOM that needs to be parsed.

Before calling the version of this method with this signature, the programmer needs to create a DOM from the XML file. S/he passes it to this method to create a Java hierarchy equivalent to the DOM.

Recursively parses the XML nodes in DFS order and translates them into a tree of state-objects. This method used to be called builtStateObject(...).

Parameters:

doc - Document object for DOM tree that needs to be translated.

translationSpace - NameSpace that provides basis for translation.

Returns:

Parent ElementState object of the corresponding Java tree.

Throws:

XMLTranslationException

translateFromXMLRootNode

public static ElementState translateFromXMLRootNode(org.w3c.dom.Node xmlRootNode,
                                                    TranslationSpace translationSpace)
                                             throws XMLTranslationException

A recursive DOM-based translation translateFromXML(...). Entry point for the old DOM-based parsing.

Typically, this method is initially passed the root Node of an XML DOM, from which it builds a tree of equivalent ElementState objects. It does this by recursively calling itself for each node/subtree of ElementState objects. The method translates any tree of DOM into a tree of Java objects, each of which is an instance of a subclass of ElementState. The operation of the method is predicated on the existence of a tree of classes derived from ElementState, which corresponds to the structure of the XML DOM that needs to be parsed. Before calling the version of this method with this signature, the programmer needs to create a DOM from the XML file, and access the root Node. S/he passes it to this method to create a Java hierarchy equivalent to the DOM. Recursively parses the XML nodes in DFS order and translates them into a tree of state-objects. This method used to be called builtStateObject(...).

Parameters:

xmlRootNode - Root node of the DOM tree that needs to be translated.

translationSpace - NameSpace that provides basis for translation.

Returns:

Parent ElementState object of the corresponding Java tree.

Throws:

XMLTranslationException

translateFromXMLSAX

public static ElementState translateFromXMLSAX(java.lang.CharSequence charSequence,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.

Parameters:

charSequence -

translationSpace -

Returns:

Throws:

XMLTranslationException

translateFromXMLSAX

public static ElementState translateFromXMLSAX(ParsedURL purl,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.

Parameters:

purl -

translationSpace -

Returns:

Throws:

XMLTranslationException

translateFromXMLSAX

public static ElementState translateFromXMLSAX(java.net.URL url,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.

Parameters:

url -

translationSpace -

Returns:

Throws:

XMLTranslationException

translateFromXMLSAX

public static ElementState translateFromXMLSAX(java.io.File file,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.

Parameters:

file -

translationSpace -

Returns:

Throws:

XMLTranslationException

translateFromXMLSAX

public static ElementState translateFromXMLSAX(java.io.InputStream inputStream,
                                               TranslationSpace translationSpace)
                                        throws XMLTranslationException

Use the (faster!) SAX parser to form a strongly typed tree of ElementState objects from XML.

Parameters:

inputStream -

translationSpace -

Returns:

Throws:

XMLTranslationException

buildDOM

public static org.w3c.dom.Document buildDOM(java.net.URL url)

This method creates a DOM Document from the XML file at a given URL.

Parameters:

url - the URL to the XML from which the DOM is to be created

Returns:

the Document object

buildDOM

public static org.w3c.dom.Document buildDOM(ParsedURL purl)

buildDOM

public static org.w3c.dom.Document buildDOM(java.io.File file)

This method creates a DOM Document from the local XML file.

Parameters:

file - the XML file from which the DOM is to be created

Returns:

the Document object

buildDOM

public static org.w3c.dom.Document buildDOM(java.lang.String xmlFileOrURLName)

This method creates a DOM Document from the XML file at a given URI, which could be a local file or a URL.

Parameters:

xmlFileOrURLName - the path to the XML from which the DOM is to be created

Returns:

the Document object

buildDOM

public static org.w3c.dom.Document buildDOM(java.io.InputStream inStream)

This method creates a DOM Document from the XML file at a given URI, which could be a local file or a URL.

Parameters:

inStream - InputStream from which the DOM is to be created

Returns:

the Document object

buildDOMFromXMLCharSequence

public static org.w3c.dom.Document buildDOMFromXMLCharSequence(java.lang.CharSequence charSequence,
                                                               int charsetType)

This method creates a DOM Document from an XML-formatted String.

Parameters:

charSequence - the XML-formatted String from which the DOM is to be created

charsetType - A constant from ecologylab.generic.StringInputStream. 0 for UTF16_LE. 1 for UTF16. 2 for UTF8.

Returns:

the Document object

buildDOMFromXMLString

public static org.w3c.dom.Document buildDOMFromXMLString(java.lang.CharSequence charSequence)

This method creates a DOM Document from an XML-formatted String, encoded as UTF8.

Parameters:

charSequence - the XML-formatted String from which the DOM is to be created

Returns:

the Document object

writePrettyXML

public void writePrettyXML(java.lang.String xmlFileName)
                    throws XMLTranslationException

Translate to XML, then write the result to a file, while formatting nicely.

Throws:

XMLTranslationException

writePrettyXML

public void writePrettyXML(java.io.File xmlFile)
                    throws XMLTranslationException

Translate to XML, then write the result to a file.

Parameters:

xmlFile - the file in which the xml needs to be saved

Throws:

XMLTranslationException

writePrettyXML

public void writePrettyXML(java.io.OutputStream outputStream)
                    throws XMLTranslationException

Translate to XML, then write the result to a file.

Parameters:

xmlFile - the file in which the xml needs to be saved

Throws:

XMLTranslationException

fieldToXMLOptimizations

protected ecologylab.xml.FieldToXMLOptimizations fieldToXMLOptimizations(java.lang.reflect.Field field,
                                                                         java.lang.Class<? extends ElementState> thatClass)

Get a tag translation object that corresponds to the fieldName, with this class. If necessary, form that tag translation object, and cache it.

setFieldUsingTypeRegistry

protected boolean setFieldUsingTypeRegistry(java.lang.reflect.Field field,
                                            java.lang.String fieldValue)

Set a field that is an extended primitive -- a non ElementState -- using the type registry.

Parameters:

field -

fieldValue -

Returns:

true if the Field is set successfully.

addNestedElement

protected void addNestedElement(ecologylab.xml.NodeToJavaOptimizations pte,
                                org.w3c.dom.Node childNode)
                         throws XMLTranslationException

Old-school DOM approach. This base implementation provides a warning.

Parameters:

pte -

childNode -

Throws:

XMLTranslationException

addNestedElement

protected void addNestedElement(ElementState elementState)

This is the hook that enables programmers to do something special when handling a nested XML element and its associate ElementState (subclass), by overriding this method and providing a custom implementation.

The default implementation is a no-op. fields that get here are ignored.

Parameters:

elementState -

Throws:

XMLTranslationException

appendTextNodeString

protected void appendTextNodeString(java.lang.String newText)

Called during translateFromXML(). If the textNodeString is currently null, assign to. Otherwise, append to it.

Parameters:

newText - Text Node value just found parsing the XML.

getTextNodeString

public java.lang.String getTextNodeString()

getElementStateById

public ElementState getElementStateById(java.lang.String id)

The DOM classic accessor method.

Returns:

element in the tree rooted from this, whose id attrribute is as in the parameter.

getCollection

protected java.util.Collection<? extends ElementState> getCollection(java.lang.Class thatClass)

When translating from XML, if a tag is encountered with no matching field, perhaps it belongs in a Collection. This method tells us which collection object that would be.

Parameters:

thatClass - The class of the ElementState superclass that could be stored in a Collection.

Returns:

getMap

protected java.util.Map getMap(java.lang.Class thatClass)

When translating from XML, if a tag is encountered with no matching field, perhaps it belongs in a Collection. This method tells us which collection object that would be.

Parameters:

thatClass - The class of the ElementState superclass that could be stored in a Collection.

Returns:

leafElementFieldNames

protected java.lang.String[] leafElementFieldNames()

An array of Strings with the names of the leaf elements. Must be overridden to provide leaf elements as direct, typed field values.

Returns:

null in the default implementation.

convertNameStyles

protected boolean convertNameStyles()

Specifies automatic conversion from XML style names (e.g. composition_space) to Java style class names (e.g. CompositionSpace) or instance variable names (e.g. compositionSpace).

Returns:

The default implementation returns true.

parent

public ElementState parent()

Returns:

the parent

setParent

public void setParent(ElementState parent)

Set the parent of this, to create the tree structure.

Parameters:

parent -

setFloatingPrecision

public void setFloatingPrecision(short floatingPrecision)

setDeclarationStyle

public static void setDeclarationStyle(ElementState.DeclarationStyle ds)

checkAnnotation

public void checkAnnotation()
                     throws java.lang.NoSuchFieldException

Throws:

java.lang.NoSuchFieldException

optimizations

protected Optimizations optimizations()

Returns:

Returns the optimizations.

createChildHook

protected void createChildHook(ElementState child)

Perform custom processing on the newly created child node, just before it is added to this.

This is part of depth-first traversal during translateFromXML().

This, the default implementation, does nothing. Sub-classes may wish to override.

Parameters:

child -

preTranslationProcessingHook

protected void preTranslationProcessingHook()

Perform custom processing immediately before translating this to XML.

This, the default implementation, does nothing. Sub-classes may wish to override.

postTranslationProcessingHook

protected void postTranslationProcessingHook()

Perform custom processing immediately after all translation from XML is completed. This allows a newly-created ElementState object to perform any post processing with all the data it will have from XML.

This method is called by NodeToJavaOptimizations.createChildElement() or translateToXML depending on whether the element in question is a child or the top-level parent.

This, the default implementation, does nothing. Sub-classes may wish to override.

recycle

public void recycle()

Clear data structures and references to enable garbage collecting of resources associated with this.

getNestedNameSpace

public ElementState getNestedNameSpace(java.lang.String id)

Either lookup an existing Nested Namespace object, or form a new one, map it, and return it. This lazy evaluation type call is invoked either in translateFromXML(), or, when procedurally building an element with Namespace children.

Parameters:

id -

esClass -

Returns:

Namespace ElementState object associated with urn.

lookupNestedNameSpace

public ElementState lookupNestedNameSpace(java.lang.String id)

Lookup an ElementState subclass representing the scope of the nested XML Namespace in this.

Parameters:

id -

Returns:

The ElementState subclass associated with xmlns:id, if there is one. Otherwise, null.

setUseDOMForTranslateTo

public static void setUseDOMForTranslateTo(boolean value)

Set to true to use the DOM parser by default for translateToXML(). Otherwise, the SAX parser will be used.

Parameters:

value -