Package org.simpleframework.xml.core

Class Traverser

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

  • Field Summary

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

  • Constructor Summary

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

  • Method Summary

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

    Methods inherited from class java.lang.Object

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

  • Field Details

    • context

      private final Context context
      This is the context object used for the traversal performed.

    • style

      private final Style style
      This is the style that is used to style the XML roots.

  • Constructor Details

    • Traverser

      public Traverser(Context context)
      Constructor for the Traverser object. This creates a traverser that can be used to perform serialization or or deserialization of an object. This requires a source object.
      Parameters:
      context - the context object used for the traversal

  • Method Details

    • getDecorator

      private Decorator getDecorator(Class type) throws Exception
      This will acquire the Decorator for the type. A decorator is an object that adds various details to the node without changing the overall structure of the node. For example comments and namespaces can be added to the node with a decorator as they do not affect the deserialization.
      Parameters:
      type - this is the type to acquire the decorator for
      Returns:
      this returns the decorator associated with this
      Throws:
      Exception

    • read

      public Object read(InputNode node, Class type) throws Exception
      This read method is used to deserialize an object from the provided XML element. The class provided acts as the XML schema definition used to control the deserialization. If the XML schema does not have a Root annotation this throws an exception. Also if the root annotation name is not the same as the XML element name an exception is thrown.
      Parameters:
      node - this is the node that is to be deserialized
      type - this is the XML schema class to be used
      Returns:
      an object deserialized from the XML element
      Throws:
      Exception - if the XML schema does not match the node

    • read

      public Object read(InputNode node, Object value) throws Exception
      This read method will read the contents of the XML document from the provided source and populate the object with the values deserialized. This is used as a means of injecting an object with values deserialized from an XML document. If the XML source cannot be deserialized or there is a problem building the object graph an exception is thrown.
      Parameters:
      node - this is the node that is to be deserialized
      value - this is the value that is to be deserialized
      Returns:
      an object deserialized from the XML element
      Throws:
      Exception - if the XML schema does not match the node

    • read

      private Object read(InputNode node, Class type, Object value) throws Exception
      This read method is used to deserialize an object from the provided XML element. The class provided acts as the XML schema definition used to control the deserialization. If the XML schema does not have a Root annotation this throws an exception. Also if the root annotation name is not the same as the XML element name an exception is thrown.
      Parameters:
      node - this is the node that is to be deserialized
      value - this is the XML schema object to be used
      Returns:
      an object deserialized from the XML element
      Throws:
      Exception - if the XML schema does not match the XML

    • validate

      public boolean validate(InputNode node, Class type) throws 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:
      node - this provides the source of the XML document
      type - this is the class type to be validated against XML
      Returns:
      true if the document matches the class XML schema
      Throws:
      Exception - if the class XML schema does not fully match

    • write

      public void write(OutputNode node, Object source) throws Exception
      This write method is used to convert the provided object to an XML element. This creates a child node from the given OutputNode object. Once this child element is created it is populated with the fields of the source object in accordance with the XML schema class.
      Parameters:
      source - this is the object to be serialized to XML
      Throws:
      Exception - thrown if there is a problem serializing

    • write

      public void write(OutputNode node, Object source, Class expect) throws Exception
      This write method is used to convert the provided object to an XML element. This creates a child node from the given OutputNode object. Once this child element is created it is populated with the fields of the source object in accordance with the XML schema class.
      Parameters:
      source - this is the object to be serialized to XML
      expect - this is the class that is expected to be written
      Throws:
      Exception - thrown if there is a problem serializing

    • write

      public void write(OutputNode node, Object source, Class expect, String name) throws Exception
      This write method is used to convert the provided object to an XML element. This creates a child node from the given OutputNode object. Once this child element is created it is populated with the fields of the source object in accordance with the XML schema class.
      Parameters:
      source - this is the object to be serialized to XML
      expect - this is the class that is expected to be written
      name - this is the name of the root annotation used
      Throws:
      Exception - thrown if there is a problem serializing

    • getComposite

      private Composite getComposite(Class expect) throws Exception
      This will create a Composite object using the XML schema class provided. This makes use of the source object that this traverser has been given to create a composite converter.
      Parameters:
      expect - this is the XML schema class to be used
      Returns:
      a converter for the specified XML schema class
      Throws:
      Exception

    • getType

      private Type getType(Class type)
      This is used to acquire a type for the provided class. This will wrap the class in a Type wrapper object. Wrapping the class allows it to be used within the framework.
      Parameters:
      type - this is the type that is to be wrapped for use
      Returns:
      this returns the type that wraps the specified class

    • getName

      protected String getName(Class type) throws Exception
      Extracts the Root annotation from the provided XML schema class. If no annotation exists in the provided class the super class is checked and so on until the Object is encountered, if no annotation is found this returns null.
      Parameters:
      type - this is the XML schema class to use
      Returns:
      this returns the root annotation for the XML schema
      Throws:
      Exception