ix.util.xml
Class XMLTranslator

java.lang.Object
  ix.util.xml.XMLTranslator

All Implemented Interfaces:

Loader, Saver

Direct Known Subclasses:

CompactXMLTranslator, XMLTreeSendFrame.SubversiveTranslator

public class XMLTranslator
extends java.lang.Object
implements Loader, Saver

A class for translating between objects and XML. Note that a single XMLTranslator maps in both directions to make it easier to create mappings that are consistent.

See Also:

I-X XML syntax

Field Summary

protected ClassSyntax	classSyntax
protected java.lang.Class	defaultListClass
protected java.lang.Class	defaultMapClass
protected java.lang.Class	defaultSetClass
protected org.jdom.Namespace	homeNamespace The namespace used in elements that represent object classes and fields.
protected java.lang.String	homeNamespaceURI The URI for the home namespace.
protected java.lang.String	implAttributeName
protected org.jdom.Element	lastExaminedElement
protected LispPrinter	lispPrinter
protected java.lang.Class	listTextClass
protected java.lang.String	mapEntryName
protected org.jdom.Namespace	mostRecentHomeNamespace Size 1 cache for fast comparisons.
protected boolean	omitImplAttributes
protected org.jdom.output.XMLOutputter	outputter
protected Function1	postfilter
protected Function1	prefilter
protected boolean	requireNamespace Is an I-X namespace required in input XML?
protected boolean	writePrintableListsAsText

Constructor Summary

XMLTranslator()

XMLTranslator(ClassSyntax syntax)

Method Summary

protected java.util.Collection	collectionFromElement(java.lang.Class implClass, org.jdom.Element elt)
protected org.jdom.Element	collectionToElement(java.lang.Class iface, java.util.Collection obj)
java.lang.String	documentToXMLString(org.jdom.Document doc) Converts a JDOM Document to a string of XML.
protected LiteralDocument	embeddedXMLFromElement(java.lang.Class c, org.jdom.Element elt)
protected org.jdom.Element	embeddedXMLToElement(java.lang.Object obj)
ClassSyntax	getClassSyntax()
protected java.lang.Object	getFieldValue(org.jdom.Element fieldElt, FieldDescr fd)
java.lang.Object	getFieldValue(java.lang.Object obj, FieldDescr fd)
org.jdom.Namespace	getHomeNamespace() Returns the home namespace used by this XMLTranslator.
protected java.lang.String	getImplAttributeValue(org.jdom.Element elt)
protected java.lang.Class	getImplClass(org.jdom.Element elt, java.lang.Class c, java.lang.Class implDefault)
org.jdom.Element	getLastExaminedElement() Returns the JDOM Element most recently examined by the methods that convert XML to objects.
org.jdom.output.XMLOutputter	getOutputter()
(package private) void	handleUnknownFieldFromElement(java.lang.Object obj, java.lang.String fieldName, org.jdom.Element fieldElt)
boolean	isAttributeClass(java.lang.Class c)
protected boolean	isHomeNamespace(org.jdom.Namespace namespace)
protected boolean	isHomeNamespaceURI(java.lang.String uri)
protected java.util.List	listFromElement(java.lang.Class c, org.jdom.Element elt)
protected java.util.List	listFromElementText(java.lang.Class c, org.jdom.Element elt)
protected org.jdom.Element	listToElement(java.lang.Object obj)
boolean	looksLikeAnObjectDocument(org.jdom.Document doc)
protected java.lang.Object	makeInstance(java.lang.Class c) Makes an instance of a class using the 0-argument constructor.
protected LList	makeLListFromElement(org.jdom.Element elt)
protected java.util.Map	mapFromElement(java.lang.Class c, org.jdom.Element elt)
protected org.jdom.Element	mapToElement(java.lang.Object obj)
protected org.jdom.Element	nsElement(java.lang.String name) Utility that creates an element in the home namespace.
java.lang.Object	objectFromDocument(org.jdom.Document doc) Converts a JDOM Document to an object.
protected java.lang.Object	objectFromElement(java.lang.Class c, org.jdom.Element elt)
java.lang.Object	objectFromElement(org.jdom.Element elt) Converts a JDOM Element to an object.
java.lang.Object	objectFromXML(java.lang.String text) Converts a string of XML to an object.
org.jdom.Document	objectToDocument(java.lang.Object obj) Converts an object to a JDOM Document.
protected org.jdom.Element	objectToElement(java.lang.Object obj) Converts an object to a JDOM Element.
java.lang.String	objectToXMLString(java.lang.Object obj) Converts an object to a string of XML.
protected java.lang.Object	primitiveObjectFromElement(java.lang.Class c, org.jdom.Element elt)
protected java.lang.Object	primitiveObjectFromString(java.lang.Class c, java.lang.String s)
protected org.jdom.Element	primitiveObjectToElement(java.lang.Object obj)
protected void	processStructAttributes(java.lang.Object obj, ClassDescr cd, org.jdom.Element elt)
protected void	processStructSubelements(java.lang.Object obj, ClassDescr cd, org.jdom.Element elt)
java.lang.Object	readObject(java.net.URL url)
protected void	requireEltSize(int size, org.jdom.Element elt)
protected void	requireEltType(java.lang.String name, org.jdom.Element elt)
void	setFieldValue(java.lang.Object obj, FieldDescr fd, java.lang.Object fieldVal)
protected java.util.Set	setFromElement(java.lang.Class c, org.jdom.Element elt)
protected void	setImplAttribute(org.jdom.Element elt, java.lang.String className)
void	setOmitImplAttributes(boolean v) Controlls whether or not implClass attributes are added to List, Set, and Map elements when converting to XML.
void	setPostfilter(Function1 f)
void	setPrefilter(Function1 f)
void	setRequireNamespace(boolean v) Controls whether element names must be in the home namespace for the elements to be translatable to objects.
protected org.jdom.Element	setToElement(java.lang.Object obj)
protected java.lang.String	stringFromElement(java.lang.Class c, org.jdom.Element elt)
protected org.jdom.Element	stringToElement(java.lang.Object obj)
protected java.lang.Object	structFromElement(java.lang.Class c, org.jdom.Element elt)
protected org.jdom.Element	structToElement(java.lang.Object obj)
protected void	visitField(java.lang.Object obj, FieldDescr fd, org.jdom.Element objElt)
static java.lang.Class	wrapperClass(java.lang.Class pc) Returns the wrapper class for a primitive class, such as Long.class for long.class.
void	writeObject(java.lang.Object obj, java.io.File file)

Methods inherited from class java.lang.Object

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

Field Detail

classSyntax

protected ClassSyntax classSyntax

outputter

protected org.jdom.output.XMLOutputter outputter

lispPrinter

protected LispPrinter lispPrinter

prefilter

protected Function1 prefilter

postfilter

protected Function1 postfilter

implAttributeName

protected java.lang.String implAttributeName

mapEntryName

protected java.lang.String mapEntryName

omitImplAttributes

protected boolean omitImplAttributes

writePrintableListsAsText

protected boolean writePrintableListsAsText

lastExaminedElement

protected org.jdom.Element lastExaminedElement

defaultListClass

protected java.lang.Class defaultListClass

defaultSetClass

protected java.lang.Class defaultSetClass

defaultMapClass

protected java.lang.Class defaultMapClass

listTextClass

protected java.lang.Class listTextClass

requireNamespace

protected boolean requireNamespace

Is an I-X namespace required in input XML? Initially false.

homeNamespace

protected org.jdom.Namespace homeNamespace

The namespace used in elements that represent object classes and fields. It is defined without a prefix and so will be declared as the default namespace for the elements in which it's used. (That may sound odd from an XML point of view, but it's how it works in JDOM.)

homeNamespaceURI

protected java.lang.String homeNamespaceURI

The URI for the home namespace.

mostRecentHomeNamespace

protected org.jdom.Namespace mostRecentHomeNamespace

Size 1 cache for fast comparisons.

See Also:

isHomeNamespace(Namespace)

Constructor Detail

XMLTranslator

public XMLTranslator()

XMLTranslator

public XMLTranslator(ClassSyntax syntax)

Method Detail

getClassSyntax

public ClassSyntax getClassSyntax()

getOutputter

public org.jdom.output.XMLOutputter getOutputter()

setPrefilter

public void setPrefilter(Function1 f)

setPostfilter

public void setPostfilter(Function1 f)

setOmitImplAttributes

public void setOmitImplAttributes(boolean v)

Controlls whether or not implClass attributes are added to List, Set, and Map elements when converting to XML. Note that if it's set to true, the XML will not contain enough information to determine the original implementation classes and the translator will have to do its best to make reasonable choices based on field classes and the defaults.

getHomeNamespace

public org.jdom.Namespace getHomeNamespace()

Returns the home namespace used by this XMLTranslator.

nsElement

protected org.jdom.Element nsElement(java.lang.String name)

Utility that creates an element in the home namespace.

setRequireNamespace

public void setRequireNamespace(boolean v)

Controls whether element names must be in the home namespace for the elements to be translatable to objects.

See Also:

looksLikeAnObjectDocument(Document)

isHomeNamespace

protected boolean isHomeNamespace(org.jdom.Namespace namespace)

isHomeNamespaceURI

protected boolean isHomeNamespaceURI(java.lang.String uri)

writeObject

public void writeObject(java.lang.Object obj,
                        java.io.File file)
                 throws java.io.IOException

Specified by:

writeObject in interface Saver

Throws:

java.io.IOException

objectToXMLString

public java.lang.String objectToXMLString(java.lang.Object obj)

Converts an object to a string of XML. The object is converted to a JDOM Document by objectToDocument(Object) and then to a string by documentToXMLString(org.jdom.Document).

documentToXMLString

public java.lang.String documentToXMLString(org.jdom.Document doc)

Converts a JDOM Document to a string of XML.

objectToDocument

public org.jdom.Document objectToDocument(java.lang.Object obj)

Converts an object to a JDOM Document.

objectToElement

protected org.jdom.Element objectToElement(java.lang.Object obj)

Converts an object to a JDOM Element. This is the central recursion point for the conversion process; it determines which of the typeToElement(Object) methods to call.

If the prefilter is not null, it is called on the object before translation begins, and the result is used instead the original object. (Of course, the prefilter could just return the original object, but this enables it to supply a substitute.)

See Also:

setPrefilter(Function1)

primitiveObjectToElement

protected org.jdom.Element primitiveObjectToElement(java.lang.Object obj)

stringToElement

protected org.jdom.Element stringToElement(java.lang.Object obj)

embeddedXMLToElement

protected org.jdom.Element embeddedXMLToElement(java.lang.Object obj)

listToElement

protected org.jdom.Element listToElement(java.lang.Object obj)

setToElement

protected org.jdom.Element setToElement(java.lang.Object obj)

collectionToElement

protected org.jdom.Element collectionToElement(java.lang.Class iface,
                                               java.util.Collection obj)

mapToElement

protected org.jdom.Element mapToElement(java.lang.Object obj)

setImplAttribute

protected void setImplAttribute(org.jdom.Element elt,
                                java.lang.String className)

structToElement

protected org.jdom.Element structToElement(java.lang.Object obj)

visitField

protected void visitField(java.lang.Object obj,
                          FieldDescr fd,
                          org.jdom.Element objElt)

getFieldValue

public java.lang.Object getFieldValue(java.lang.Object obj,
                                      FieldDescr fd)

isAttributeClass

public boolean isAttributeClass(java.lang.Class c)

readObject

public java.lang.Object readObject(java.net.URL url)
                            throws java.io.IOException

Specified by:

readObject in interface Loader

Throws:

java.io.IOException

objectFromXML

public java.lang.Object objectFromXML(java.lang.String text)

Converts a string of XML to an object.

objectFromDocument

public java.lang.Object objectFromDocument(org.jdom.Document doc)

Converts a JDOM Document to an object. This method, or one that calls it, is what should normally be called from outside the translator - rather than calling objectFromElement(elt) directly.

looksLikeAnObjectDocument

public boolean looksLikeAnObjectDocument(org.jdom.Document doc)

getLastExaminedElement

public org.jdom.Element getLastExaminedElement()

Returns the JDOM Element most recently examined by the methods that convert XML to objects. This may be useful when handling or reporting an exception.

objectFromElement

public java.lang.Object objectFromElement(org.jdom.Element elt)

Converts a JDOM Element to an object. This is the central recursion point of the translation process; it determines which of the typeFromElement methods to call.

If the postfilter is not null, it is called on the object before it is returned, and the result of that call is returned instead.

Note that most of the work, and the calling of the postfiler, are actually done in the 2-argument version of this method and that some recursions may go directly to that method.

See Also:

objectFromElement(Class, Element), setPostfilter(Function1)

objectFromElement

protected java.lang.Object objectFromElement(java.lang.Class c,
                                             org.jdom.Element elt)

primitiveObjectFromElement

protected java.lang.Object primitiveObjectFromElement(java.lang.Class c,
                                                      org.jdom.Element elt)

primitiveObjectFromString

protected java.lang.Object primitiveObjectFromString(java.lang.Class c,
                                                     java.lang.String s)

stringFromElement

protected java.lang.String stringFromElement(java.lang.Class c,
                                             org.jdom.Element elt)

embeddedXMLFromElement

protected LiteralDocument embeddedXMLFromElement(java.lang.Class c,
                                                 org.jdom.Element elt)

listFromElementText

protected java.util.List listFromElementText(java.lang.Class c,
                                             org.jdom.Element elt)

listFromElement

protected java.util.List listFromElement(java.lang.Class c,
                                         org.jdom.Element elt)

setFromElement

protected java.util.Set setFromElement(java.lang.Class c,
                                       org.jdom.Element elt)

collectionFromElement

protected java.util.Collection collectionFromElement(java.lang.Class implClass,
                                                     org.jdom.Element elt)

makeLListFromElement

protected LList makeLListFromElement(org.jdom.Element elt)

getImplAttributeValue

protected java.lang.String getImplAttributeValue(org.jdom.Element elt)

getImplClass

protected java.lang.Class getImplClass(org.jdom.Element elt,
                                       java.lang.Class c,
                                       java.lang.Class implDefault)

mapFromElement

protected java.util.Map mapFromElement(java.lang.Class c,
                                       org.jdom.Element elt)

requireEltType

protected void requireEltType(java.lang.String name,
                              org.jdom.Element elt)

requireEltSize

protected void requireEltSize(int size,
                              org.jdom.Element elt)

structFromElement

protected java.lang.Object structFromElement(java.lang.Class c,
                                             org.jdom.Element elt)

processStructAttributes

protected void processStructAttributes(java.lang.Object obj,
                                       ClassDescr cd,
                                       org.jdom.Element elt)

processStructSubelements

protected void processStructSubelements(java.lang.Object obj,
                                        ClassDescr cd,
                                        org.jdom.Element elt)

setFieldValue

public void setFieldValue(java.lang.Object obj,
                          FieldDescr fd,
                          java.lang.Object fieldVal)

getFieldValue

protected java.lang.Object getFieldValue(org.jdom.Element fieldElt,
                                         FieldDescr fd)

handleUnknownFieldFromElement

void handleUnknownFieldFromElement(java.lang.Object obj,
                                   java.lang.String fieldName,
                                   org.jdom.Element fieldElt)

wrapperClass

public static final java.lang.Class wrapperClass(java.lang.Class pc)

Returns the wrapper class for a primitive class, such as Long.class for long.class.

makeInstance

protected java.lang.Object makeInstance(java.lang.Class c)

Makes an instance of a class using the 0-argument constructor.

Throws:

XMLException - if the attempt fails.