simple.xml
Interface Serializer

All Known Implementing Classes:
Persister

public interface Serializer

The Serializer interface is used to represent objects that can serialize and deserialize objects to an from XML. This exposes several read and write methods that can read from and write to various sources. Typically an object will be read from an XML file and written to some other file or stream.

An implementation of the Serializer interface is free to use any desired XML parsing framework. If a framework other than the Java streaming API for XML is required then it should be wrapped within the classes of the simple.xml.stream framework, which offers a framework neutral facade.

Author:
Niall Gallagher

Method Summary
<T> T
read(java.lang.Class<? extends T> type, java.io.File source)
          This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type.
<T> T
read(java.lang.Class<? extends T> type, java.io.InputStream source)
          This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type.
<T> T
read(java.lang.Class<? extends T> type, java.io.InputStream source, java.lang.String charset)
          This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type.
<T> T
read(java.lang.Class<? extends T> type, java.io.Reader source)
          This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type.
<T> T
read(java.lang.Class<? extends T> type, java.lang.String source)
          This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type.
 void write(java.lang.Object source, java.io.File out)
          This write method will traverse the provided object checking for field annotations in order to compose the XML data.
 void write(java.lang.Object source, java.io.OutputStream out)
          This write method will traverse the provided object checking for field annotations in order to compose the XML data.
 void write(java.lang.Object source, java.io.OutputStream out, java.lang.String charset)
          This write method will traverse the provided object checking for field annotations in order to compose the XML data.
 void write(java.lang.Object source, java.io.Writer out)
          This write method will traverse the provided object checking for field annotations in order to compose the XML data.
 

Method Detail

read

<T> T read(java.lang.Class<? extends T> type,
           java.lang.String source)
       throws java.lang.Exception
This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type. If the XML source cannot be deserialized or there is a problem building the object graph an exception is thrown. The instance deserialized is returned.

Parameters:
type - this is the class type to be deserialized from XML
source - this provides the source of the XML document
Returns:
the object deserialized from the XML document
Throws:
java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(java.lang.Class<? extends T> type,
           java.io.File source)
       throws java.lang.Exception
This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type. If the XML source cannot be deserialized or there is a problem building the object graph an exception is thrown. The instance deserialized is returned.

Parameters:
type - this is the class type to be deserialized from XML
source - this provides the source of the XML document
Returns:
the object deserialized from the XML document
Throws:
java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(java.lang.Class<? extends T> type,
           java.io.InputStream source)
       throws java.lang.Exception
This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type. If the XML source cannot be deserialized or there is a problem building the object graph an exception is thrown. The instance deserialized is returned.

Parameters:
type - this is the class type to be deserialized from XML
source - this provides the source of the XML document
Returns:
the object deserialized from the XML document
Throws:
java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(java.lang.Class<? extends T> type,
           java.io.InputStream source,
           java.lang.String charset)
       throws java.lang.Exception
This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type. If the XML source cannot be deserialized or there is a problem building the object graph an exception is thrown. The instance deserialized is returned.

Parameters:
type - this is the class type to be deserialized from XML
source - this provides the source of the XML document
charset - this is the character set to read the XML with
Returns:
the object deserialized from the XML document
Throws:
java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(java.lang.Class<? extends T> type,
           java.io.Reader source)
       throws java.lang.Exception
This read method will read the contents of the XML document from the provided source and convert it into an object of the specified type. If the XML source cannot be deserialized or there is a problem building the object graph an exception is thrown. The instance deserialized is returned.

Parameters:
type - this is the class type to be deserialized from XML
source - this provides the source of the XML document
Returns:
the object deserialized from the XML document
Throws:
java.lang.Exception - if the object cannot be fully deserialized

write

void write(java.lang.Object source,
           java.io.File out)
           throws java.lang.Exception
This write method will traverse the provided object checking for field annotations in order to compose the XML data. This uses the getClass method on the object to determine the class file that will be used to compose the schema. If there is no Root annotation for the class then this will throw an exception. The root annotation is the only annotation required for an object to be serialized.

Parameters:
source - this is the object that is to be serialized
out - this is where the serialized XML is written to
Throws:
java.lang.Exception - if the schema for the object is not valid

write

void write(java.lang.Object source,
           java.io.OutputStream out)
           throws java.lang.Exception
This write method will traverse the provided object checking for field annotations in order to compose the XML data. This uses the getClass method on the object to determine the class file that will be used to compose the schema. If there is no Root annotation for the class then this will throw an exception. The root annotation is the only annotation required for an object to be serialized.

Parameters:
source - this is the object that is to be serialized
out - this is where the serialized XML is written to
Throws:
java.lang.Exception - if the schema for the object is not valid

write

void write(java.lang.Object source,
           java.io.OutputStream out,
           java.lang.String charset)
           throws java.lang.Exception
This write method will traverse the provided object checking for field annotations in order to compose the XML data. This uses the getClass method on the object to determine the class file that will be used to compose the schema. If there is no Root annotation for the class then this will throw an exception. The root annotation is the only annotation required for an object to be serialized.

Parameters:
source - this is the object that is to be serialized
out - this is where the serialized XML is written to
charset - this is the character encoding to be used
Throws:
java.lang.Exception - if the schema for the object is not valid

write

void write(java.lang.Object source,
           java.io.Writer out)
           throws java.lang.Exception
This write method will traverse the provided object checking for field annotations in order to compose the XML data. This uses the getClass method on the object to determine the class file that will be used to compose the schema. If there is no Root annotation for the class then this will throw an exception. The root annotation is the only annotation required for an object to be serialized.

Parameters:
source - this is the object that is to be serialized
out - this is where the serialized XML is written to
Throws:
java.lang.Exception - if the schema for the object is not valid