# Persister
Date: 2013-02-18

## org.simpleframework.xml.core
Class Persister

    java.lang.Object
      org.simpleframework.xml.core.Persister

All Implemented Interfaces:
  Serializer

    public class Persister

extends java.lang.Object
implements Serializer

The `Persister` object is used to provide an implementation of a serializer. This implements the `Serializer` interface and enables objects to be persisted and loaded from various sources. This implementation makes use of `Filter` objects to replace template variables within the source XML document. It is fully thread safe and can be shared by multiple threads without concerns.

Deserialization is performed by passing an XML schema class into one of the `read` methods along with the source of an XML stream. The read method then reads the contents of the XML stream and builds the object using annotations within the XML schema class.

Serialization is performed by passing an object and an XML stream into one of the `write` methods. The serialization process will use the class of the provided object as the schema class. The object is traversed and all fields are marshalled to the result stream.

Author:
  Niall Gallagher
See Also:
  `Serializer`

Constructor Summary
`Persister()` Constructor for the `Persister` object.
`Persister(Filter filter)` Constructor for the `Persister` object.
`Persister(Filter filter, Format format)` Constructor for the `Persister` object.
`Persister(Filter filter, Matcher matcher)` Constructor for the `Persister` object.
`Persister(Filter filter, Matcher matcher, Format format)` Constructor for the `Persister` object.
`Persister(Format format)` Constructor for the `Persister` object.
`Persister(java.util.Map filter)` Constructor for the `Persister` object.
`Persister(java.util.Map filter, Format format)` Constructor for the `Persister` object.
`Persister(Matcher matcher)` Constructor for the `Persister` object.
`Persister(Matcher matcher, Format format)` Constructor for the `Persister` object.
`Persister(Strategy strategy)` Constructor for the `Persister` object.
`Persister(Strategy strategy, Filter filter)` Constructor for the `Persister` object.
`Persister(Strategy strategy, Filter filter, Format format)` Constructor for the `Persister` object.
`Persister(Strategy strategy, Filter filter, Matcher matcher)` Constructor for the `Persister` object.
`Persister(Strategy strategy, Filter filter, Matcher matcher, Format format)` Constructor for the `Persister` object.
`Persister(Strategy strategy, Format format)` Constructor for the `Persister` object.
`Persister(Strategy strategy, java.util.Map data)` Constructor for the `Persister` object.
`Persister(Strategy strategy, java.util.Map data, Format format)` Constructor for the `Persister` object.
`Persister(Strategy strategy, Matcher matcher)` Constructor for the `Persister` object.
`Persister(Strategy strategy, Matcher matcher, Format format)` Constructor for the `Persister` object.

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

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### Persister

    public Persister()

  Constructor for the `Persister` object. This is used to create a serializer object that will use an empty filter. This means that template variables will remain unchanged within the XML document parsed when an object is deserialized.

### Persister

    public Persister(Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided format instructions. The persister uses the `Format` object to structure the generated XML. It determines the indent size of the document and whether it should contain a prolog.

  Parameters:
    `format` - this is used to structure the generated XML

### Persister

    public Persister(java.util.Map filter)

  Constructor for the `Persister` object. This is used to create a serializer object that will use a platform filter object using the overrides within the provided map. This means that template variables will be replaced firstly with mappings from within the provided map, followed by system properties.

  Parameters:
    `filter` - this is the map that contains the overrides

### Persister

    public Persister(java.util.Map filter,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use a platform filter object using the overrides within the provided map. This means that template variables will be replaced firstly with mappings from within the provided map, followed by system properties.

  Parameters:
    `filter` - this is the map that contains the overrides
    `format` - this is the format used to format the documents

### Persister

    public Persister(Filter filter)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided filter. This persister will replace all variables encountered when deserializing an object with mappings found in the filter.

  Parameters:
    `filter` - the filter used to replace template variables

### Persister

    public Persister(Filter filter,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided filter. This persister will replace all variables encountered when deserializing an object with mappings found in the filter.

  Parameters:
    `filter` - the filter used to replace template variables
    `format` - this is used to structure the generated XML

### Persister

    public Persister(Matcher matcher)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided matcher for customizable transformations. The `Matcher` will enable the persister to determine the correct way to transform the types that are not annotated and considered primitives.

  Parameters:
    `matcher` - this is used to customize the transformations

### Persister

    public Persister(Matcher matcher,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided matcher for customizable transformations. The `Matcher` will enable the persister to determine the correct way to transform the types that are not annotated and considered primitives.

  Parameters:
    `matcher` - this is used to customize the transformations
    `format` - this is used to structure the generated XML

### Persister

    public Persister(Strategy strategy)

  Constructor for the `Persister` object. This is used to create a serializer object that will use a strategy object. This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes

### Persister

    public Persister(Strategy strategy,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use a strategy object. This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `format` - this is used to structure the generated XML

### Persister

    public Persister(Filter filter,
                     Matcher matcher)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided filter. This persister will replace all variables encountered when deserializing an object with mappings found in the filter.

  Parameters:
    `filter` - the filter used to replace template variables
    `matcher` - this is used to customize the transformations

### Persister

    public Persister(Filter filter,
                     Matcher matcher,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided filter. This persister will replace all variables encountered when deserializing an object with mappings found in the filter.

  Parameters:
    `filter` - the filter used to replace template variables
    `matcher` - this is used to customize the transformations
    `format` - this is used to structure the generated XML

### Persister

    public Persister(Strategy strategy,
                     java.util.Map data)

  Constructor for the `Persister` object. This is used to create a serializer object that will use a platform filter object using the overrides within the provided map. This means that template variables will be replaced firstly with mappings from within the provided map, followed by system properties.

  This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `data` - this is the map that contains the overrides

### Persister

    public Persister(Strategy strategy,
                     java.util.Map data,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided filter. This persister will replace all variables encountered when deserializing an object with mappings found in the filter.

  This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `data` - the filter data used to replace template variables
    `format` - this is used to format the generated XML document

### Persister

    public Persister(Strategy strategy,
                     Filter filter)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided filter. This persister will replace all variables encountered when deserializing an object with mappings found in the filter.

  This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `filter` - the filter used to replace template variables

### Persister

    public Persister(Strategy strategy,
                     Filter filter,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided filter. This persister will replace all variables encountered when deserializing an object with mappings found in the filter.

  This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `filter` - the filter used to replace template variables
    `format` - this is used to format the generated XML document

### Persister

    public Persister(Strategy strategy,
                     Matcher matcher)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided matcher for customizable transformations. The `Matcher` will enable the persister to determine the correct way to transform the types that are not annotated and considered primitives.

  This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `matcher` - this is used to customize the transformations

### Persister

    public Persister(Strategy strategy,
                     Matcher matcher,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided matcher for customizable transformations. The `Matcher` will enable the persister to determine the correct way to transform the types that are not annotated and considered primitives.

  This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `matcher` - this is used to customize the transformations
    `format` - this is used to format the generated XML document

### Persister

    public Persister(Strategy strategy,
                     Filter filter,
                     Matcher matcher)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided matcher for customizable transformations. The `Matcher` will enable the persister to determine the correct way to transform the types that are not annotated and considered primitives.

  This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `matcher` - this is used to customize the transformations
    `filter` - the filter used to replace template variables

### Persister

    public Persister(Strategy strategy,
                     Filter filter,
                     Matcher matcher,
                     Format format)

  Constructor for the `Persister` object. This is used to create a serializer object that will use the provided matcher for customizable transformations. The `Matcher` will enable the persister to determine the correct way to transform the types that are not annotated and considered primitives.

  This persister will use the provided `Strategy` to intercept the XML elements in order to read and write persistent data, such as the class name or version of the document.

  Parameters:
    `strategy` - this is the strategy used to resolve classes
    `matcher` - this is used to customize the transformations
    `filter` - the filter used to replace template variables

Method Detail

### read

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

    public <T> T read(java.lang.Class<? extends T> type,
                      InputNode node,
                      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.

  Specified by:
    `read` in interface `Serializer`
  Parameters:
    `type` - this is the class type to be deserialized from XML
    `node` - 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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

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

  Specified by:
    `read` in interface `Serializer`
  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

    public <T> T read(T value,
                      InputNode node,
                      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.

  Specified by:
    `read` in interface `Serializer`
  Parameters:
    `value` - this is the object to deserialize the XML in to
    `node` - 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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  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

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

  Specified by:
    `validate` in interface `Serializer`
  Parameters:
    `type` - this is the class type to be validated against XML
    `node` - 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

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

  Specified by:
    `write` in interface `Serializer`
  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

### write

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

  Specified by:
    `write` in interface `Serializer`
  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

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

  Specified by:
    `write` in interface `Serializer`
  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

    public 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

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

  Specified by:
    `write` in interface `Serializer`
  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