de.fu_berlin.ties.io
Class ObjectElement

java.lang.Object
  extended by org.dom4j.tree.AbstractNode
      extended by org.dom4j.tree.AbstractBranch
          extended by org.dom4j.tree.AbstractElement
              extended by org.dom4j.tree.DefaultElement
                  extended by de.fu_berlin.ties.io.ObjectElement
All Implemented Interfaces:
Serializable, Cloneable, Branch, Element, Node

public class ObjectElement
extends DefaultElement

An XML element that is targeted at storing an Java object.

Version:
$Revision: 1.12 $, $Date: 2006/10/21 16:04:22 $, $Author: siefkes $
Author:
Christian Siefkes
See Also:
Serialized Form

Field Summary
static String JAVA_CLASS_ATTRIBUTE
          The name of the attribute used to store the Java class of an object: "java".
 
Fields inherited from class org.dom4j.tree.AbstractElement
EMPTY_ITERATOR, EMPTY_LIST, USE_STRINGVALUE_SEPARATOR, VERBOSE_TOSTRING
 
Fields inherited from class org.dom4j.tree.AbstractBranch
DEFAULT_CONTENT_LIST_SIZE
 
Fields inherited from class org.dom4j.tree.AbstractNode
NODE_TYPE_NAMES
 
Fields inherited from interface org.dom4j.Node
ANY_NODE, ATTRIBUTE_NODE, CDATA_SECTION_NODE, COMMENT_NODE, DOCUMENT_NODE, DOCUMENT_TYPE_NODE, ELEMENT_NODE, ENTITY_REFERENCE_NODE, MAX_NODE_TYPE, NAMESPACE_NODE, PROCESSING_INSTRUCTION_NODE, TEXT_NODE, UNKNOWN_NODE
 
Constructor Summary
ObjectElement(QName qname, Class javaClass)
          Creates a new instance.
ObjectElement(String name, Class javaClass)
          Creates a new instance.
ObjectElement(String name, Namespace namespace, Class javaClass)
          Creates a new instance.
 
Method Summary
static Object createNextObject(Iterator iter)
          Uses the next element returned by an iterator to initialize an object.
 Object createObject()
          Creates (deserializes) an object of a specified type by calling a constructor of the class that accepts an XML element as single argument and passing itself as parameter.
static Object createObject(Document document)
          Convenience method that delegates to createObject(Element), using the root element of a given document.
static Object createObject(Element element)
          Creates (deserializes) an object of a specified type by calling a constructor of the class that accepts an XML element as single argument and passing itself as parameter.
static Object createObject(Element element, Class type)
          Creates (deserializes) an object of a specified type by calling a constructor of the class that accepts an XML element as single argument and passing itself as parameter.
static Object createObject(File file)
          Convenience method that delegates to createObject(Document), reading from a file.
 Class javaClass()
          Returns the Class of the stored object.
static Class javaClass(Element element)
          Looks up and returns the Class of a Java object stored in an element.
 String javaClassName()
          Returns the name of the Class of the stored object.
static String javaClassName(Element element)
          Looks up and returns the name of the Class of Java object stored in an element.
static String recommendedExtension()
          Returns the file extension recommended for serializing Java code.
 void store(File file, TiesConfiguration conf)
          Writes this object element document to a file, consulting a given configuration about whether to use compression.
 void store(OutputStream out)
          Writes this object element document to an output stream.
 ObjectElement unsetJavaClass()
          Unsets the attribute representing the Class of the stored object.
 
Methods inherited from class org.dom4j.tree.DefaultElement
add, additionalNamespaces, additionalNamespaces, addNewNode, attribute, attribute, attribute, attribute, attributeCount, attributeIterator, attributeList, attributeList, attributes, clearContent, clone, contentList, declaredNamespaces, element, element, element, getDocument, getDocumentFactory, getNamespaceForPrefix, getNamespaceForURI, getParent, getQName, getStringValue, getText, indexOf, node, nodeCount, nodeIterator, processingInstruction, processingInstructions, processingInstructions, remove, removeNode, removeProcessingInstruction, setAttributeList, setAttributes, setContent, setDocument, setParent, setQName, supportsParent
 
Methods inherited from class org.dom4j.tree.AbstractElement
accept, add, add, add, add, add, add, add, add, addAttribute, addAttribute, addCDATA, addComment, addElement, addEntity, addNamespace, addNewNode, addNode, addNode, addProcessingInstruction, addProcessingInstruction, addText, appendAttributes, asXML, attributeValue, attributeValue, attributeValue, attributeValue, childAdded, childRemoved, createAttributeList, createAttributeList, createCopy, createCopy, createCopy, createElement, createElement, createSingleIterator, elementIterator, elementIterator, elementIterator, elementIterator, elements, elements, elements, elements, elementText, elementText, elementTextTrim, elementTextTrim, ensureAttributesCapacity, getData, getName, getNamespace, getNamespacePrefix, getNamespacesForURI, getNamespaceURI, getNodeType, getPath, getQName, getQualifiedName, getUniquePath, getXPathNameStep, getXPathResult, hasMixedContent, isRootElement, isTextOnly, normalize, remove, remove, remove, remove, remove, remove, remove, remove, setAttributes, setAttributeValue, setAttributeValue, setData, setName, setNamespace, setText, toString, write
 
Methods inherited from class org.dom4j.tree.AbstractBranch
addElement, addElement, addElement, appendContent, content, contentRemoved, createContentList, createContentList, createEmptyList, createResultList, createSingleResultList, elementByID, elementID, getContentAsStringValue, getContentAsText, getTextTrim, hasContent, invalidNodeTypeAddException, isReadOnly, setProcessingInstructions
 
Methods inherited from class org.dom4j.tree.AbstractNode
asXPathResult, createPattern, createXPath, createXPathFilter, createXPathResult, detach, getNodeTypeName, getPath, getUniquePath, matches, numberValueOf, selectNodes, selectNodes, selectNodes, selectObject, selectSingleNode, valueOf
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.dom4j.Element
getTextTrim
 
Methods inherited from interface org.dom4j.Branch
addElement, addElement, appendContent, content, elementByID, setProcessingInstructions
 
Methods inherited from interface org.dom4j.Node
asXPathResult, createXPath, detach, getNodeTypeName, getPath, getUniquePath, hasContent, isReadOnly, matches, numberValueOf, selectNodes, selectNodes, selectNodes, selectObject, selectSingleNode, valueOf
 

Field Detail

JAVA_CLASS_ATTRIBUTE

public static final String JAVA_CLASS_ATTRIBUTE
The name of the attribute used to store the Java class of an object: "java".

See Also:
Constant Field Values
Constructor Detail

ObjectElement

public ObjectElement(String name,
                     Class javaClass)
Creates a new instance.

Parameters:
name - the name of the element
javaClass - the class of the object to store; or null if no class should be stored

ObjectElement

public ObjectElement(QName qname,
                     Class javaClass)
Creates a new instance.

Parameters:
qname - the qualified name of the element
javaClass - the class of the object to store; or null if no class should be stored

ObjectElement

public ObjectElement(String name,
                     Namespace namespace,
                     Class javaClass)
Creates a new instance.

Parameters:
name - the local name of the element
namespace - the namespace of the element
javaClass - the class of the object to store; or null if no class should be stored
Method Detail

createNextObject

public static final Object createNextObject(Iterator iter)
                                     throws InstantiationException,
                                            SecurityException,
                                            ClassCastException,
                                            NullPointerException
Uses the next element returned by an iterator to initialize an object. If the iterator does not have any more elements, null is returned.

Parameters:
iter - an iterator over Elements to use
Returns:
the created by calling createObject(Element) on the next element returned by the iterator; or null if Iterator.hasNext() is false
Throws:
InstantiationException - if instantiation failed
SecurityException - if access to the required reflection information is denied
ClassCastException - if the object returned by calling Iterator.next() does not implement the Element interface
NullPointerException - if no java class attribute is present

createObject

public static final Object createObject(File file)
                                 throws IOException,
                                        InstantiationException,
                                        SecurityException,
                                        NullPointerException
Convenience method that delegates to createObject(Document), reading from a file.

Parameters:
file - the file to read
Returns:
the created object
Throws:
IOException - if an I/O error occurs while reading the data
InstantiationException - if instantiation failed or if the class specified in the JAVA_CLASS_ATTRIBUTE of the root element is not available on this system
SecurityException - if access to the required reflection information is denied
NullPointerException - if no java class attribute is present

createObject

public static final Object createObject(Document document)
                                 throws InstantiationException,
                                        SecurityException,
                                        NullPointerException
Convenience method that delegates to createObject(Element), using the root element of a given document.

Parameters:
document - the document to use
Returns:
the created object
Throws:
InstantiationException - if instantiation failed or if the class specified in the JAVA_CLASS_ATTRIBUTE of the root element is not available on this system
SecurityException - if access to the required reflection information is denied
NullPointerException - if no java class attribute is present

createObject

public static final Object createObject(Element element)
                                 throws InstantiationException,
                                        SecurityException,
                                        NullPointerException
Creates (deserializes) an object of a specified type by calling a constructor of the class that accepts an XML element as single argument and passing itself as parameter. Only classes that provide a suitable constructor can be instantiated this way.

Parameters:
element - the element to use
Returns:
the created object; the returned object will be an instance of the specified class
Throws:
InstantiationException - if instantiation failed or if the class specified in the JAVA_CLASS_ATTRIBUTE is not available on this system
SecurityException - if access to the required reflection information is denied
NullPointerException - if no java class attribute is present

createObject

public static final Object createObject(Element element,
                                        Class type)
                                 throws InstantiationException,
                                        SecurityException
Creates (deserializes) an object of a specified type by calling a constructor of the class that accepts an XML element as single argument and passing itself as parameter. Only classes that provide a suitable constructor can be instantiated this way.

Parameters:
element - the element to use
type - the class of the object to create; must have a constructor whose only argument is an Element
Returns:
the created object; the returned object will be an instance of the specified class
Throws:
InstantiationException - if instantiation failed
SecurityException - if access to the required reflection information is denied

javaClassName

public static String javaClassName(Element element)
Looks up and returns the name of the Class of Java object stored in an element.

Parameters:
element - the element to use
Returns:
the class name of the stored object; or null if no JAVA_CLASS_ATTRIBUTE is present

javaClass

public static Class javaClass(Element element)
                       throws ClassNotFoundException
Looks up and returns the Class of a Java object stored in an element.

Parameters:
element - the element to use
Returns:
the class of the stored object; or null if no JAVA_CLASS_ATTRIBUTE is present
Throws:
ClassNotFoundException - if the class cannot be located

recommendedExtension

public static String recommendedExtension()
Returns the file extension recommended for serializing Java code.

Returns:
the recommended extension: "xsj" (XML-serialized Java)

createObject

public final Object createObject()
                          throws InstantiationException,
                                 SecurityException,
                                 ClassNotFoundException,
                                 NullPointerException
Creates (deserializes) an object of a specified type by calling a constructor of the class that accepts an XML element as single argument and passing itself as parameter. Only classes that provide a suitable constructor can be instantiated this way.

Returns:
the created object
Throws:
InstantiationException - if instantiation failed
SecurityException - if access to the required reflection information is denied
ClassNotFoundException - if the class specified in the JAVA_CLASS_ATTRIBUTE is not available on this system
NullPointerException - if the java class attribute has been removed (by calling unsetJavaClass()

javaClassName

public String javaClassName()
Returns the name of the Class of the stored object.

Returns:
the class name of the stored object; or null if unsetJavaClass() has been called before

javaClass

public Class javaClass()
                throws ClassNotFoundException
Returns the Class of the stored object.

Returns:
the class of the stored object; or null if unsetJavaClass() has been called before
Throws:
ClassNotFoundException - if the class cannot be located

store

public void store(File file,
                  TiesConfiguration conf)
           throws IOException
Writes this object element document to a file, consulting a given configuration about whether to use compression. For this purpose, the recommendedExtension is used as suffix.

Parameters:
file - the file to write to
conf - used to decide whether to use compression
Throws:
IOException - if an I/O error occurs while writing

store

public void store(OutputStream out)
           throws IOException
Writes this object element document to an output stream.

Parameters:
out - the output stream to write to; not closed by this method
Throws:
IOException - if an I/O error occurs while writing

unsetJavaClass

public ObjectElement unsetJavaClass()
Unsets the attribute representing the Class of the stored object.

Returns:
a pointer to this object (to allow method chaining)


Copyright © 2003-2007 Christian Siefkes. All Rights Reserved.