org.simpleframework.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 org.simpleframework.xml.stream API, 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.File source, boolean strict) 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, InputNode 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, InputNode source, boolean strict) 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, boolean strict) 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.io.Reader source, boolean strict) 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.
<T> T	read(java.lang.Class<? extends T> type, java.lang.String source, boolean strict) 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(T value, java.io.File source) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, java.io.File source, boolean strict) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, InputNode source) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, InputNode source, boolean strict) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, java.io.InputStream source) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, java.io.InputStream source, boolean strict) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, java.io.Reader source) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, java.io.Reader source, boolean strict) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, java.lang.String source) This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized.
<T> T	read(T value, java.lang.String source, boolean strict) 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(java.lang.Class type, java.io.File source) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, java.io.File source, boolean strict) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, InputNode source) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, InputNode source, boolean strict) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, java.io.InputStream source) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, java.io.InputStream source, boolean strict) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, java.io.Reader source) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, java.io.Reader source, boolean strict) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, java.lang.String source) This validate method will validate the contents of the XML document against the specified XML class schema.
boolean	validate(java.lang.Class type, java.lang.String source, boolean strict) This validate method will validate the contents of the XML document against the specified XML class schema.
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, OutputNode root) 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.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.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

read

<T> T read(java.lang.Class<? extends T> type,
           InputNode 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.lang.String source,
           boolean strict)
       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

strict - this determines whether to read in strict mode

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,
           boolean strict)
       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

strict - this determines whether to read in strict mode

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,
           boolean strict)
       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

strict - this determines whether to read in strict mode

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,
           boolean strict)
       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

strict - this determines whether to read in strict mode

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,
           InputNode source,
           boolean strict)
       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

strict - this determines whether to read in strict mode

Returns:

the object deserialized from the XML document

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           java.lang.String source)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           java.io.File source)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           java.io.InputStream source)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           java.io.Reader source)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           InputNode source)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           java.lang.String source,
           boolean strict)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           java.io.File source,
           boolean strict)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           java.io.InputStream source,
           boolean strict)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           java.io.Reader source,
           boolean strict)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

read

<T> T read(T value,
           InputNode source,
           boolean strict)
       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:

value - this is the object to deserialize the XML in to

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

the same instance provided is returned when finished

Throws:

java.lang.Exception - if the object cannot be fully deserialized

validate

boolean validate(java.lang.Class type,
                 java.lang.String source)
                 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

source - 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

validate

boolean validate(java.lang.Class type,
                 java.io.File source)
                 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

source - 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

validate

boolean validate(java.lang.Class type,
                 java.io.InputStream source)
                 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

source - 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

validate

boolean validate(java.lang.Class type,
                 java.io.Reader source)
                 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

source - 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

validate

boolean validate(java.lang.Class type,
                 InputNode source)
                 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

source - 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

validate

boolean validate(java.lang.Class type,
                 java.lang.String source,
                 boolean strict)
                 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

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

true if the document matches the class XML schema

Throws:

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

validate

boolean validate(java.lang.Class type,
                 java.io.File source,
                 boolean strict)
                 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

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

true if the document matches the class XML schema

Throws:

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

validate

boolean validate(java.lang.Class type,
                 java.io.InputStream source,
                 boolean strict)
                 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

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

true if the document matches the class XML schema

Throws:

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

validate

boolean validate(java.lang.Class type,
                 java.io.Reader source,
                 boolean strict)
                 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

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

true if the document matches the class XML schema

Throws:

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

validate

boolean validate(java.lang.Class type,
                 InputNode source,
                 boolean strict)
                 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

source - this provides the source of the XML document

strict - this determines whether to read in strict mode

Returns:

true if the document matches the class XML schema

Throws:

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

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.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

write

void write(java.lang.Object source,
           OutputNode root)
           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

root - this is where the serialized XML is written to

Throws:

java.lang.Exception - if the schema for the object is not valid