Package org.simpleframework.xml.core

Class Traverser

java.lang.Object

org.simpleframework.xml.core.Traverser

class Traverser
extends java.lang.Object

The Traverser object is used to traverse the XML class schema and either serialize or deserialize an object. This is the root of all serialization and deserialization operations. It uses the Root annotation to ensure that the XML schema matches the provided XML element. If no root element is defined the serialization and deserialization cannot be performed.

Field Summary

Fields

Modifier and Type	Field	Description
private Context	context	This is the context object used for the traversal performed.
private Style	style	This is the style that is used to style the XML roots.

Constructor Summary

Constructors

Constructor	Description
Traverser(Context context)	Constructor for the Traverser object.

Method Summary

Modifier and Type	Method	Description
private Composite	getComposite(java.lang.Class expect)	This will create a Composite object using the XML schema class provided.
private Decorator	getDecorator(java.lang.Class type)	This will acquire the Decorator for the type.
protected java.lang.String	getName(java.lang.Class type)	Extracts the Root annotation from the provided XML schema class.
private Type	getType(java.lang.Class type)	This is used to acquire a type for the provided class.
java.lang.Object	read(InputNode node, java.lang.Class type)	This read method is used to deserialize an object from the provided XML element.
private java.lang.Object	read(InputNode node, java.lang.Class type, java.lang.Object value)	This read method is used to deserialize an object from the provided XML element.
java.lang.Object	read(InputNode node, java.lang.Object value)	This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
boolean	validate(InputNode node, java.lang.Class type)	This validate method will validate the contents of the XML document against the specified XML class schema.
void	write(OutputNode node, java.lang.Object source)	This write method is used to convert the provided object to an XML element.
void	write(OutputNode node, java.lang.Object source, java.lang.Class expect)	This write method is used to convert the provided object to an XML element.
void	write(OutputNode node, java.lang.Object source, java.lang.Class expect, java.lang.String name)	This write method is used to convert the provided object to an XML element.

Methods inherited from class java.lang.Object

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

Field Detail

context

private final Context context

This is the context object used for the traversal performed.

style

private final Style style

This is the style that is used to style the XML roots.

Constructor Detail

Traverser

public Traverser(Context context)

Constructor for the Traverser object. This creates a traverser that can be used to perform serialization or or deserialization of an object. This requires a source object.

Parameters:

context - the context object used for the traversal

Method Detail

getDecorator

private Decorator getDecorator(java.lang.Class type)
                        throws java.lang.Exception

This will acquire the Decorator for the type. A decorator is an object that adds various details to the node without changing the overall structure of the node. For example comments and namespaces can be added to the node with a decorator as they do not affect the deserialization.

Parameters:

type - this is the type to acquire the decorator for

Returns:

this returns the decorator associated with this

Throws:

java.lang.Exception

read

public java.lang.Object read(InputNode node,
                             java.lang.Class type)
                      throws java.lang.Exception

This read method is used to deserialize an object from the provided XML element. The class provided acts as the XML schema definition used to control the deserialization. If the XML schema does not have a Root annotation this throws an exception. Also if the root annotation name is not the same as the XML element name an exception is thrown.

Parameters:

node - this is the node that is to be deserialized

type - this is the XML schema class to be used

Returns:

an object deserialized from the XML element

Throws:

java.lang.Exception - if the XML schema does not match the node

read

public java.lang.Object read(InputNode node,
                             java.lang.Object value)
                      throws java.lang.Exception

This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized. This is used as a means of injecting an object with values deserialized from an XML document. If the XML source cannot be deserialized or there is a problem building the object graph an exception is thrown.

Parameters:

node - this is the node that is to be deserialized

value - this is the value that is to be deserialized

Returns:

an object deserialized from the XML element

Throws:

java.lang.Exception - if the XML schema does not match the node

read

private java.lang.Object read(InputNode node,
                              java.lang.Class type,
                              java.lang.Object value)
                       throws java.lang.Exception

This read method is used to deserialize an object from the provided XML element. The class provided acts as the XML schema definition used to control the deserialization. If the XML schema does not have a Root annotation this throws an exception. Also if the root annotation name is not the same as the XML element name an exception is thrown.

Parameters:

node - this is the node that is to be deserialized

value - this is the XML schema object to be used

Returns:

an object deserialized from the XML element

Throws:

java.lang.Exception - if the XML schema does not match the XML

validate

public boolean validate(InputNode node,
                        java.lang.Class type)
                 throws java.lang.Exception

This validate method will validate the contents of the XML document against the specified XML class schema. This is used to perform a read traversal of the class schema such that the document can be tested against it. This is preferred to reading the document as it does not instantiate the objects or invoke any callback methods, thus making it a safe validation.

Parameters:

type - this is the class type to be validated against XML

node - this provides the source of the XML document

Returns:

true if the document matches the class XML schema

Throws:

java.lang.Exception - if the class XML schema does not fully match

write

public void write(OutputNode node,
                  java.lang.Object source)
           throws java.lang.Exception

This write method is used to convert the provided object to an XML element. This creates a child node from the given OutputNode object. Once this child element is created it is populated with the fields of the source object in accordance with the XML schema class.

Parameters:

source - this is the object to be serialized to XML

Throws:

java.lang.Exception - thrown if there is a problem serializing

write

public void write(OutputNode node,
                  java.lang.Object source,
                  java.lang.Class expect)
           throws java.lang.Exception

This write method is used to convert the provided object to an XML element. This creates a child node from the given OutputNode object. Once this child element is created it is populated with the fields of the source object in accordance with the XML schema class.

Parameters:

source - this is the object to be serialized to XML

expect - this is the class that is expected to be written

Throws:

java.lang.Exception - thrown if there is a problem serializing

write

public void write(OutputNode node,
                  java.lang.Object source,
                  java.lang.Class expect,
                  java.lang.String name)
           throws java.lang.Exception

This write method is used to convert the provided object to an XML element. This creates a child node from the given OutputNode object. Once this child element is created it is populated with the fields of the source object in accordance with the XML schema class.

Parameters:

source - this is the object to be serialized to XML

expect - this is the class that is expected to be written

name - this is the name of the root annotation used

Throws:

java.lang.Exception - thrown if there is a problem serializing

getComposite

private Composite getComposite(java.lang.Class expect)
                        throws java.lang.Exception

This will create a Composite object using the XML schema class provided. This makes use of the source object that this traverser has been given to create a composite converter.

Parameters:

expect - this is the XML schema class to be used

Returns:

a converter for the specified XML schema class

Throws:

java.lang.Exception

getType

private Type getType(java.lang.Class type)

This is used to acquire a type for the provided class. This will wrap the class in a Type wrapper object. Wrapping the class allows it to be used within the framework.

Parameters:

type - this is the type that is to be wrapped for use

Returns:

this returns the type that wraps the specified class

getName

protected java.lang.String getName(java.lang.Class type)
                            throws java.lang.Exception

Extracts the Root annotation from the provided XML schema class. If no annotation exists in the provided class the super class is checked and so on until the Object is encountered, if no annotation is found this returns null.

Parameters:

type - this is the XML schema class to use

Returns:

this returns the root annotation for the XML schema

Throws:

java.lang.Exception