Class Traverser


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

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

      Constructors 
      Constructor Description
      Traverser​(Context context)
      Constructor for the Traverser object.
    • Method Summary

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

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • context

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

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

      • Traverser

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

      • getDecorator

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

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

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

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

        public boolean validate​(InputNode node,
                                java.lang.Class type)
                         throws java.lang.Exception
        This validate method will validate the contents of the XML document against the specified XML class schema. This is used to perform a read traversal of the class schema such that the document can be tested against it. This is preferred to reading the document as it does not instantiate the objects or invoke any callback methods, thus making it a safe validation.
        Parameters:
        type - this is the class type to be validated against XML
        node - this provides the source of the XML document
        Returns:
        true if the document matches the class XML schema
        Throws:
        java.lang.Exception - if the class XML schema does not fully match
      • write

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

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

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

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

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

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