Package org.simpleframework.xml.core

Class Composite

  • All Implemented Interfaces:
    Converter
    class Composite
extends java.lang.Object
implements Converter
    The Composite object is used to perform serialization of objects that contain XML annotations. Composite objects are objects that are not primitive and contain references to serializable fields. This Converter will visit each field within the object and deserialize or serialize that field depending on the requested action. If a required field is not present when deserializing from an XML element this terminates and deserialization reports the error. 
     
    <element name="test" class="some.package.Type">
       <text>string value</text>
       <integer>1234</integer>
    </element>
    To deserialize the above XML source this will attempt to match the attribute name with an Attribute annotation from the XML schema class, which is specified as "some.package.Type". This type must also contain Element annotations for the "text" and "integer" elements.

    Serialization requires that contacts marked as required must have values that are not null. This ensures that the serialized object can be deserialized at a later stage using the same class schema. If a required value is null the serialization terminates and an exception is thrown.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      private static class  Composite.Builder
      This takes the approach that the object is instantiated first and then the annotated fields and methods are deserialized from the XML elements and attributes.
      private class  Composite.Injector
      This takes the approach that the objects are deserialized first then the instance is created using a constructor.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private Context context
      This is the source object for the instance of serialization.
      private Criteria criteria
      This is used to store objects so that they can be read again.
      private ObjectFactory factory
      This factory creates instances of the deserialized object.
      private Primitive primitive
      This is used to convert any primitive values that are needed.
      private Revision revision
      This is the current revision of this composite converter.
      private Type type
      This is the type that this composite produces instances of.

    • Constructor Summary

      Constructors 
      Constructor Description
      Composite​(Context context, Type type)
      Constructor for the Composite object.
      Composite​(Context context, Type type, java.lang.Class override)
      Constructor for the Composite object.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private boolean isOverridden​(OutputNode node, java.lang.Object value, Type type)
      This is used to determine whether the specified value has been overridden by the strategy.
      private Composite.Builder read​(Schema schema, Instance value)
      This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element.
      java.lang.Object read​(InputNode node)
      This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element.
      java.lang.Object read​(InputNode node, java.lang.Object source)
      This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element.
      private void read​(InputNode node, java.lang.Object source, Schema schema)
      This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element.
      private java.lang.Object read​(InputNode node, Instance value, java.lang.Class real)
      This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element.
      private void readAttribute​(InputNode node, java.lang.Object source, Section section, LabelMap map)
      This readAttribute method is used for deserialization of the provided node object using a delegate converter.
      private void readAttributes​(InputNode node, java.lang.Object source, Section section)
      This readAttributes method reads the attributes from the provided XML element.
      private void readElement​(InputNode node, java.lang.Object source, Section section, LabelMap map)
      This readElement method is used for deserialization of the provided node object using a delegate converter.
      private void readElements​(InputNode node, java.lang.Object source, Section section)
      This readElements method reads the elements from the provided XML element.
      private java.lang.Object readInstance​(InputNode node, java.lang.Object source, Label label)
      This read method is used to perform deserialization of the provided node object using a delegate converter.
      private java.lang.Object readPrimitive​(InputNode node, Instance value)
      This readPrimitive method will extract the text value from the node and replace any template variables before converting it to a primitive value.
      private java.lang.Object readResolve​(InputNode node, java.lang.Object source, Caller caller)
      The readResolve method is used to determine if there is a resolution method which can be used to substitute the object deserialized.
      private void readSection​(InputNode node, java.lang.Object source, Section section)
      This readSection method performs deserialization of a schema class type by traversing the contacts and instantiating them using details from the provided XML element.
      private void readText​(InputNode node, java.lang.Object source, Section section)
      This readText method is used to read the text value from the XML element node specified.
      private void readUnion​(InputNode node, java.lang.Object source, LabelMap map, Label label)
      The readUnion method is determine the unions for a particular label and set the value of that union to the same value as the label.
      private java.lang.Object readVariable​(InputNode node, java.lang.Object source, Label label)
      This readObject method is used to perform the deserialization of the XML in to any original value.
      private void readVersion​(InputNode node, java.lang.Object source, Label label)
      This method is used to read the version from the provided input node.
      private void readVersion​(InputNode node, java.lang.Object source, Schema schema)
      This method is used to read the version from the provided input node.
      boolean validate​(InputNode node)
      This validate method performs validation of the XML schema class type by traversing the contacts and validating them using details from the provided XML element.
      private boolean validate​(InputNode node, java.lang.Class type)
      This validate method performs validation of the XML schema class type by traversing the contacts and validating them using details from the provided XML element.
      private void validate​(InputNode node, Label label)
      This validate method is used to perform validation of the provided node object using a delegate converter.
      private void validate​(InputNode node, LabelMap map)
      This method checks to see if there are any Label objects remaining in the provided map that are required.
      private void validate​(InputNode node, LabelMap map, java.lang.Object source)
      This method checks to see if there are any Label objects remaining in the provided map that are required.
      private void validateAttribute​(InputNode node, Section section, LabelMap map)
      This validateAttribute method performs a validation of the provided node object using a delegate converter.
      private void validateAttributes​(InputNode node, Section section)
      This validateAttributes method validates the attributes from the provided XML element.
      private void validateElement​(InputNode node, Section section, LabelMap map)
      This validateElement method performs a validation of the provided node object using a delegate converter.
      private void validateElements​(InputNode node, Section section)
      This validateElements method validates the elements from the provided XML element.
      private void validateSection​(InputNode node, Section section)
      This validateSection method performs validation of a schema class type by traversing the contacts and validating them using details from the provided XML element.
      private void validateText​(InputNode node, Schema schema)
      This validateText method validates the text value from the XML element node specified.
      private void validateUnion​(InputNode node, LabelMap map, Label label)
      The validateUnion method is determine the unions for a particular label and set the value of that union to the same value as the label.
      void write​(OutputNode node, java.lang.Object source)
      This write method is used to perform serialization of the given source object.
      private void write​(OutputNode node, java.lang.Object source, Schema schema)
      This write method is used to perform serialization of the given source object.
      private void writeAttribute​(OutputNode node, java.lang.Object value, Label label)
      This write method is used to set the value of the provided object as an attribute to the XML element.
      private void writeAttributes​(OutputNode node, java.lang.Object source, Section section)
      This write method is used to write all the attribute contacts from the provided source object to the XML element.
      private void writeElement​(OutputNode node, java.lang.Object value, Converter convert)
      This is used write the element specified using the specified converter.
      private void writeElement​(OutputNode node, java.lang.Object value, Label label)
      This write method is used to append the provided object as an element to the given XML element object.
      private void writeElements​(OutputNode node, java.lang.Object source, Section section)
      This write method is used to write all the element contacts from the provided source object to the XML element.
      private void writeNamespaces​(OutputNode node, Type type, Label label)
      This is used to apply Decorator objects to the provided node before it is written.
      private java.lang.Object writeReplace​(java.lang.Object source)
      The writeReplace method is used to replace an object before it is serialized.
      private void writeSection​(OutputNode node, java.lang.Object source, Section section)
      This writeSection method is used to perform serialization of the given source object.
      private void writeText​(OutputNode node, java.lang.Object value, Label label)
      This write method is used to set the value of the provided object as the text for the XML element.
      private void writeText​(OutputNode node, java.lang.Object source, Section section)
      This write method is used to write the text contact from the provided source object to the XML element.
      private void writeUnion​(OutputNode node, java.lang.Object source, Section section, Label label)
      The writeUnion method is determine the unions for a particular label and set the value of that union to the same value as the label.
      private void writeVersion​(OutputNode node, java.lang.Object source, Schema schema)
      This method is used to write the version attribute.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • factory

        private final ObjectFactory factory
        This factory creates instances of the deserialized object.

      • primitive

        private final Primitive primitive
        This is used to convert any primitive values that are needed.

      • criteria

        private final Criteria criteria
        This is used to store objects so that they can be read again.

      • revision

        private final Revision revision
        This is the current revision of this composite converter.

      • context

        private final Context context
        This is the source object for the instance of serialization.

      • type

        private final Type type
        This is the type that this composite produces instances of.

    • Constructor Detail

      • Composite

        public Composite​(Context context,
                 Type type)
        Constructor for the Composite object. This creates a converter object capable of serializing and deserializing root objects labeled with XML annotations. The XML schema class must be given to the instance in order to perform deserialization.
        Parameters:
        context - the source object used to perform serialization
        type - this is the XML schema type to use for this

      • Composite

        public Composite​(Context context,
                 Type type,
                 java.lang.Class override)
        Constructor for the Composite object. This creates a converter object capable of serializing and deserializing root objects labeled with XML annotations. The XML schema class must be given to the instance in order to perform deserialization.
        Parameters:
        context - the source object used to perform serialization
        type - this is the XML schema type to use for this
        override - this is the override type declared for this

    • Method Detail

      • read

        public java.lang.Object read​(InputNode node)
                      throws java.lang.Exception
        This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element. Because this will convert a non-primitive value it delegates to other converters to perform deserialization of lists and primitives.

        If any of the required contacts are not present within the provided XML element this will terminate deserialization and throw an exception. The annotation missing is reported in the exception.

        Specified by:
        read in interface Converter
        Parameters:
        node - the XML element contact values are deserialized from
        Returns:
        this returns the fully deserialized object graph
        Throws:
        java.lang.Exception - if a deserialized type cannot be instantiated

      • read

        public java.lang.Object read​(InputNode node,
                             java.lang.Object source)
                      throws java.lang.Exception
        This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element. Because this will convert a non-primitive value it delegates to other converters to perform deserialization of lists and primitives.

        If any of the required contacts are not present within the provided XML element this will terminate deserialization and throw an exception. The annotation missing is reported in the exception.

        Specified by:
        read in interface Converter
        Parameters:
        node - the XML element contact values are deserialized from
        source - the object whose contacts are to be deserialized
        Returns:
        this returns the fully deserialized object graph
        Throws:
        java.lang.Exception - if a deserialized type cannot be instantiated

      • read

        private java.lang.Object read​(InputNode node,
                              Instance value,
                              java.lang.Class real)
                       throws java.lang.Exception
        This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element. Because this will convert a non-primitive value it delegates to other converters to perform deserialization of lists and primitives.

        If any of the required contacts are not present within the provided XML element this will terminate deserialization and throw an exception. The annotation missing is reported in the exception.

        Parameters:
        node - the XML element contact values are deserialized from
        value - this is the instance for the object within the graph
        real - this is the real type that is to be evaluated
        Returns:
        this returns the fully deserialized object graph
        Throws:
        java.lang.Exception

      • read

        private Composite.Builder read​(Schema schema,
                               Instance value)
                        throws java.lang.Exception
        This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element. Because this will convert a non-primitive value it delegates to other converters to perform deserialization of lists and primitives.

        If any of the required contacts are not present within the provided XML element this will terminate deserialization and throw an exception. The annotation missing is reported in the exception.

        Parameters:
        node - the XML element contact values are deserialized from
        schema - this is the schema for the class to be deserialized
        value - this is the value used for the deserialization
        Returns:
        this returns the fully deserialized object graph
        Throws:
        java.lang.Exception

      • readPrimitive

        private java.lang.Object readPrimitive​(InputNode node,
                                       Instance value)
                                throws java.lang.Exception
        This readPrimitive method will extract the text value from the node and replace any template variables before converting it to a primitive value. This uses a Primitive object to convert the node text to the resulting string. This will also respect all references on the node so cycle can be followed.
        Parameters:
        node - this is the node to be converted to a primitive
        value - this is the type for the object within the graph
        Returns:
        this returns the primitive that has been deserialized
        Throws:
        java.lang.Exception

      • readResolve

        private java.lang.Object readResolve​(InputNode node,
                                     java.lang.Object source,
                                     Caller caller)
                              throws java.lang.Exception
        The readResolve method is used to determine if there is a resolution method which can be used to substitute the object deserialized. The resolve method is used when an object wishes to provide a substitute within the deserialized object graph. This acts as an equivalent to the Java Object Serialization readResolve method for the object deserialization.
        Parameters:
        node - the XML element object provided as a replacement
        source - the type of the object that is being deserialized
        caller - this is used to invoke the callback methods
        Returns:
        this returns a replacement for the deserialized object
        Throws:
        java.lang.Exception

      • read

        private void read​(InputNode node,
                  java.lang.Object source,
                  Schema schema)
           throws java.lang.Exception
        This read method performs deserialization of the XML schema class type by traversing the contacts and instantiating them using details from the provided XML element. Because this will convert a non-primitive value it delegates to other converters to perform deserialization of lists and primitives.

        If any of the required contacts are not present within the provided XML element this will terminate deserialization and throw an exception. The annotation missing is reported in the exception.

        Parameters:
        node - the XML element contact values are deserialized from
        source - this type of the object that is to be deserialized
        schema - this object visits the objects contacts
        Throws:
        java.lang.Exception

      • readSection

        private void readSection​(InputNode node,
                         java.lang.Object source,
                         Section section)
                  throws java.lang.Exception
        This readSection method performs deserialization of a schema class type by traversing the contacts and instantiating them using details from the provided XML element. Because this will convert a non-primitive value it delegates to other converters to perform deserialization of lists and primitives.

        If any of the required contacts are not present within the provided XML element this will terminate deserialization and throw an exception. The annotation missing is reported in the exception.

        Parameters:
        node - the XML element contact values are deserialized from
        source - this type of the object that is to be deserialized
        section - this is the XML section that contains the structure
        Throws:
        java.lang.Exception

      • readVersion

        private void readVersion​(InputNode node,
                         java.lang.Object source,
                         Schema schema)
                  throws java.lang.Exception
        This method is used to read the version from the provided input node. Once the version has been read it is used to determine how to deserialize the object. If the version is not the initial version then it is read in a manner that ignores excessive XML elements and attributes. Also none of the annotated fields or methods are required if the version is not the initial version.
        Parameters:
        node - the XML element contact values are deserialized from
        source - this object whose contacts are to be deserialized
        schema - this object visits the objects contacts
        Throws:
        java.lang.Exception

      • readVersion

        private void readVersion​(InputNode node,
                         java.lang.Object source,
                         Label label)
                  throws java.lang.Exception
        This method is used to read the version from the provided input node. Once the version has been read it is used to determine how to deserialize the object. If the version is not the initial version then it is read in a manner that ignores excessive XML elements and attributes. Also none of the annotated fields or methods are required if the version is not the initial version.
        Parameters:
        node - the XML element contact values are deserialized from
        source - the type of the object that is being deserialized
        label - this is the label used to read the version attribute
        Throws:
        java.lang.Exception

      • readAttributes

        private void readAttributes​(InputNode node,
                            java.lang.Object source,
                            Section section)
                     throws java.lang.Exception
        This readAttributes method reads the attributes from the provided XML element. This will iterate over all attributes within the element and convert those attributes as primitives to contact values within the source object.

        Once all attributes within the XML element have been evaluated the Schema is checked to ensure that there are no required contacts annotated with the Attribute that remain. If any required attribute remains an exception is thrown.

        Parameters:
        node - this is the XML element to be evaluated
        source - the type of the object that is being deserialized
        section - this is the XML section that contains the structure
        Throws:
        java.lang.Exception

      • readElements

        private void readElements​(InputNode node,
                          java.lang.Object source,
                          Section section)
                   throws java.lang.Exception
        This readElements method reads the elements from the provided XML element. This will iterate over all elements within the element and convert those elements to primitives or composite objects depending on the contact annotation.

        Once all elements within the XML element have been evaluated the Schema is checked to ensure that there are no required contacts annotated with the Element that remain. If any required element remains an exception is thrown.

        Parameters:
        node - this is the XML element to be evaluated
        source - the type of the object that is being deserialized
        section - the XML section that contains the structure
        Throws:
        java.lang.Exception

      • readText

        private void readText​(InputNode node,
                      java.lang.Object source,
                      Section section)
               throws java.lang.Exception
        This readText method is used to read the text value from the XML element node specified. This will check the class schema to determine if a Text annotation was specified. If one was specified then the text within the XML element input node is used to populate the contact value.
        Parameters:
        node - this is the XML element to acquire the text from
        source - the type of the object that is being deserialized
        section - this is used to visit the element contacts
        Throws:
        java.lang.Exception

      • readAttribute

        private void readAttribute​(InputNode node,
                           java.lang.Object source,
                           Section section,
                           LabelMap map)
                    throws java.lang.Exception
        This readAttribute method is used for deserialization of the provided node object using a delegate converter. This is typically another Composite converter, or if the node is an attribute a Primitive converter. When the delegate converter has completed the deserialized value is assigned to the contact.
        Parameters:
        node - this is the node that contains the contact value
        source - the type of the object that is being deserialized
        section - this is the section to read the attribute from
        map - this is the map that contains the label objects
        Throws:
        java.lang.Exception

      • readElement

        private void readElement​(InputNode node,
                         java.lang.Object source,
                         Section section,
                         LabelMap map)
                  throws java.lang.Exception
        This readElement method is used for deserialization of the provided node object using a delegate converter. This is typically another Composite converter, or if the node is an attribute a Primitive converter. When the delegate converter has completed the deserialized value is assigned to the contact.
        Parameters:
        node - this is the node that contains the contact value
        source - the type of the object that is being deserialized
        section - this is the section to read the element from
        map - this is the map that contains the label objects
        Throws:
        java.lang.Exception

      • readUnion

        private void readUnion​(InputNode node,
                       java.lang.Object source,
                       LabelMap map,
                       Label label)
                throws java.lang.Exception
        The readUnion method is determine the unions for a particular label and set the value of that union to the same value as the label. This helps the deserialization process by ensuring once a union is read it is not replaced. This is also required when reading inline lists.
        Parameters:
        node - this is the XML element to read the elements from
        source - this is the instance to read the unions from
        map - this is the label map associated with the label
        label - this is the label used to define the XML element
        Throws:
        java.lang.Exception

      • readInstance

        private java.lang.Object readInstance​(InputNode node,
                                      java.lang.Object source,
                                      Label label)
                               throws java.lang.Exception
        This read method is used to perform deserialization of the provided node object using a delegate converter. This is typically another Composite converter, or if the node is an attribute a Primitive converter. When the delegate converter has completed the deserialized value is assigned to the contact.
        Parameters:
        node - this is the node that contains the contact value
        source - the type of the object that is being deserialized
        label - this is the label used to create the converter
        Throws:
        java.lang.Exception

      • readVariable

        private java.lang.Object readVariable​(InputNode node,
                                      java.lang.Object source,
                                      Label label)
                               throws java.lang.Exception
        This readObject method is used to perform the deserialization of the XML in to any original value. If there is no original value then this will do a read and instantiate a new value to deserialize in to. Reading in to the original ensures that existing lists or maps can be read in to.
        Parameters:
        node - this is the node that contains the contact value
        source - the source object to assign the contact value to
        label - this is the label used to create the converter
        Returns:
        this returns the original value deserialized in to
        Throws:
        java.lang.Exception

      • validate

        private void validate​(InputNode node,
                      LabelMap map,
                      java.lang.Object source)
               throws java.lang.Exception
        This method checks to see if there are any Label objects remaining in the provided map that are required. This is used when deserialization is performed to ensure the the XML element deserialized contains sufficient details to satisfy the XML schema class annotations. If there is a required label that remains it is reported within the exception thrown.
        Parameters:
        node - this is the node that contains the contact value
        map - this is the map to check for remaining labels
        source - this is the object that has been deserialized
        Throws:
        java.lang.Exception

      • validate

        public boolean validate​(InputNode node)
                 throws java.lang.Exception
        This validate method performs validation of the XML schema class type by traversing the contacts and validating them using details from the provided XML element. Because this will validate a non-primitive value it delegates to other converters to perform validation of lists, maps, and primitives.

        If any of the required contacts are not present within the given XML element this will terminate validation and throw an exception The annotation missing is reported in the exception.

        Specified by:
        validate in interface Converter
        Parameters:
        node - the XML element contact values are validated from
        Returns:
        true if the XML element matches the XML schema class given
        Throws:
        java.lang.Exception - if the class XML schema does not fully match

      • validate

        private boolean validate​(InputNode node,
                         java.lang.Class type)
                  throws java.lang.Exception
        This validate method performs validation of the XML schema class type by traversing the contacts and validating them using details from the provided XML element. Because this will validate a non-primitive value it delegates to other converters to perform validation of lists, maps, and primitives.

        If any of the required contacts are not present within the given XML element this will terminate validation and throw an exception The annotation missing is reported in the exception.

        Parameters:
        node - the XML element contact values are validated from
        type - this is the type to validate against the input node
        Throws:
        java.lang.Exception

      • validateSection

        private void validateSection​(InputNode node,
                             Section section)
                      throws java.lang.Exception
        This validateSection method performs validation of a schema class type by traversing the contacts and validating them using details from the provided XML element. Because this will validate a non-primitive value it delegates to other converters to perform validation of lists, maps, and primitives.

        If any of the required contacts are not present within the given XML element this will terminate validation and throw an exception The annotation missing is reported in the exception.

        Parameters:
        node - the XML element contact values are validated from
        section - this is the section that defines the XML structure
        Throws:
        java.lang.Exception

      • validateAttributes

        private void validateAttributes​(InputNode node,
                                Section section)
                         throws java.lang.Exception
        This validateAttributes method validates the attributes from the provided XML element. This will iterate over all attributes within the element and validate those attributes as primitives to contact values within the source object.

        Once all attributes within the XML element have been evaluated the Schema is checked to ensure that there are no required contacts annotated with the Attribute that remain. If any required attribute remains an exception is thrown.

        Parameters:
        node - this is the XML element to be validated
        section - this is the section that defines the XML structure
        Throws:
        java.lang.Exception

      • validateElements

        private void validateElements​(InputNode node,
                              Section section)
                       throws java.lang.Exception
        This validateElements method validates the elements from the provided XML element. This will iterate over all elements within the element and validate those elements as primitives or composite objects depending on the contact annotation.

        Once all elements within the XML element have been evaluated the Schema is checked to ensure that there are no required contacts annotated with the Element that remain. If any required element remains an exception is thrown.

        Parameters:
        node - this is the XML element to be evaluated
        section - this is the section that defines the XML structure
        Throws:
        java.lang.Exception

      • validateText

        private void validateText​(InputNode node,
                          Schema schema)
                   throws java.lang.Exception
        This validateText method validates the text value from the XML element node specified. This will check the class schema to determine if a Text annotation was used. If one was specified then the text within the XML element input node is checked to determine if it is a valid entry.
        Parameters:
        node - this is the XML element to acquire the text from
        schema - this is used to visit the element contacts
        Throws:
        java.lang.Exception

      • validateAttribute

        private void validateAttribute​(InputNode node,
                               Section section,
                               LabelMap map)
                        throws java.lang.Exception
        This validateAttribute method performs a validation of the provided node object using a delegate converter. This is typically another Composite converter, or if the node is an attribute a Primitive converter. If this fails validation then an exception is thrown to report the issue.
        Parameters:
        node - this is the node that contains the contact value
        section - this is the section to validate this attribute in
        map - this is the map that contains the label objects
        Throws:
        java.lang.Exception

      • validateElement

        private void validateElement​(InputNode node,
                             Section section,
                             LabelMap map)
                      throws java.lang.Exception
        This validateElement method performs a validation of the provided node object using a delegate converter. This is typically another Composite converter, or if the node is an attribute a Primitive converter. If this fails validation then an exception is thrown to report the issue.
        Parameters:
        node - this is the node that contains the contact value
        section - this is the section to validate this element in
        map - this is the map that contains the label objects
        Throws:
        java.lang.Exception

      • validateUnion

        private void validateUnion​(InputNode node,
                           LabelMap map,
                           Label label)
                    throws java.lang.Exception
        The validateUnion method is determine the unions for a particular label and set the value of that union to the same value as the label. This helps the deserialization process by ensuring once a union is validated it is not replaced. This is also required when validating inline lists.
        Parameters:
        node - this is the XML element to read the elements from
        map - this is the label map associated with the label
        label - this is the label used to define the XML element
        Throws:
        java.lang.Exception

      • validate

        private void validate​(InputNode node,
                      Label label)
               throws java.lang.Exception
        This validate method is used to perform validation of the provided node object using a delegate converter. This is typically another Composite converter, or if the node is an attribute a Primitive converter. If this fails validation then an exception is thrown to report the issue.
        Parameters:
        node - this is the node that contains the contact value
        label - this is the label used to create the converter
        Throws:
        java.lang.Exception

      • validate

        private void validate​(InputNode node,
                      LabelMap map)
               throws java.lang.Exception
        This method checks to see if there are any Label objects remaining in the provided map that are required. This is used when validation is performed to ensure the the XML element validated contains sufficient details to satisfy the XML schema class annotations. If there is a required label that remains it is reported within the exception thrown.
        Parameters:
        node - this is the node that contains the composite data
        map - this contains the converters to perform validation
        Throws:
        java.lang.Exception

      • write

        public void write​(OutputNode node,
                  java.lang.Object source)
           throws java.lang.Exception
        This write method is used to perform serialization of the given source object. Serialization is performed by appending elements and attributes from the source object to the provided XML element object. How the objects contacts are serialized is determined by the XML schema class that the source object is an instance of. If a required contact is null an exception is thrown.
        Specified by:
        write in interface Converter
        Parameters:
        source - this is the source object to be serialized
        node - the XML element the object is to be serialized to
        Throws:
        java.lang.Exception - throw if the object cannot be serialized

      • write

        private void write​(OutputNode node,
                   java.lang.Object source,
                   Schema schema)
            throws java.lang.Exception
        This write method is used to perform serialization of the given source object. Serialization is performed by appending elements and attributes from the source object to the provided XML element object. How the objects contacts are serialized is determined by the XML schema class that the source object is an instance of. If a required contact is null an exception is thrown.
        Parameters:
        source - this is the source object to be serialized
        node - the XML element the object is to be serialized to
        schema - this is used to track the referenced contacts
        Throws:
        java.lang.Exception

      • writeSection

        private void writeSection​(OutputNode node,
                          java.lang.Object source,
                          Section section)
                   throws java.lang.Exception
        This writeSection method is used to perform serialization of the given source object. Serialization is performed by appending elements and attributes from the source object to the provided XML element object. How the objects contacts are serialized is determined by the XML schema class that the source object is an instance of. If a required contact is null an exception is thrown.
        Parameters:
        source - this is the source object to be serialized
        node - the XML element the object is to be serialized to
        section - this is the section that defines the XML structure
        Throws:
        java.lang.Exception

      • writeVersion

        private void writeVersion​(OutputNode node,
                          java.lang.Object source,
                          Schema schema)
                   throws java.lang.Exception
        This method is used to write the version attribute. A version is written only if it is not the initial version or if it required. The version is used to determine how to deserialize the XML. If the version is different from the expected version then it allows the object to be deserialized in a manner that does not require any attributes or elements, and unmatched nodes are ignored.
        Parameters:
        node - this is the node to read the version attribute from
        source - this is the source object that is to be written
        schema - this is the schema that contains the version
        Throws:
        java.lang.Exception

      • writeAttributes

        private void writeAttributes​(OutputNode node,
                             java.lang.Object source,
                             Section section)
                      throws java.lang.Exception
        This write method is used to write all the attribute contacts from the provided source object to the XML element. This visits all the contacts marked with the Attribute annotation in the source object. All annotated contacts are written as attributes to the XML element. This will throw an exception if a required contact within the source object is null.
        Parameters:
        source - this is the source object to be serialized
        node - this is the XML element to write attributes to
        section - this is the section that defines the XML structure
        Throws:
        java.lang.Exception

      • writeElements

        private void writeElements​(OutputNode node,
                           java.lang.Object source,
                           Section section)
                    throws java.lang.Exception
        This write method is used to write all the element contacts from the provided source object to the XML element. This visits all the contacts marked with the Element annotation in the source object. All annotated contacts are written as children to the XML element. This will throw an exception if a required contact within the source object is null.
        Parameters:
        source - this is the source object to be serialized
        node - this is the XML element to write elements to
        section - this is the section that defines the XML structure
        Throws:
        java.lang.Exception

      • writeUnion

        private void writeUnion​(OutputNode node,
                        java.lang.Object source,
                        Section section,
                        Label label)
                 throws java.lang.Exception
        The writeUnion method is determine the unions for a particular label and set the value of that union to the same value as the label. This helps the serialization process by ensuring once a union is written it is not replaced. This is also required when writing inline lists.
        Parameters:
        node - this is the XML element to write elements to
        source - this is the source object to be serialized
        section - this is the section associated with the label
        label - this is the label used to define the XML element
        Throws:
        java.lang.Exception

      • writeReplace

        private java.lang.Object writeReplace​(java.lang.Object source)
                               throws java.lang.Exception
        The writeReplace method is used to replace an object before it is serialized. This is used so that an object can give a substitute to be written to the XML document in the event that the actual object is not suitable or desired for serialization. This acts as an equivalent to the Java Object Serialization writeReplace method for the object serialization.
        Parameters:
        source - this is the source object that is to be replaced
        Returns:
        this returns the object to use as a replacement value
        Throws:
        java.lang.Exception

      • writeText

        private void writeText​(OutputNode node,
                       java.lang.Object source,
                       Section section)
                throws java.lang.Exception
        This write method is used to write the text contact from the provided source object to the XML element. This takes the text value from the source object and writes it to the single contact marked with the Text annotation. If the value is null and the contact value is required an exception is thrown.
        Parameters:
        source - this is the source object to be serialized
        node - this is the XML element to write text value to
        section - this is used to track the referenced elements
        Throws:
        java.lang.Exception

      • writeAttribute

        private void writeAttribute​(OutputNode node,
                            java.lang.Object value,
                            Label label)
                     throws java.lang.Exception
        This write method is used to set the value of the provided object as an attribute to the XML element. This will acquire the string value of the object using toString only if the object provided is not an enumerated type. If the object is an enumerated type then the Enum.name method is used.
        Parameters:
        value - this is the value to be set as an attribute
        node - this is the XML element to write the attribute to
        label - the label that contains the contact details
        Throws:
        java.lang.Exception

      • writeElement

        private void writeElement​(OutputNode node,
                          java.lang.Object value,
                          Label label)
                   throws java.lang.Exception
        This write method is used to append the provided object as an element to the given XML element object. This will recursively write the contacts from the provided object as elements. This is done using the Converter acquired from the contact label. If the type of the contact value is not of the same type as the XML schema class a "class" attribute is appended.

        If the element being written is inline, then this will not check to see if there is a "class" attribute specifying the name of the class. This is because inline elements do not have an outer class and thus could never have an override.

        Parameters:
        value - this is the value to be set as an element
        node - this is the XML element to write the element to
        label - the label that contains the contact details
        Throws:
        java.lang.Exception

      • writeElement

        private void writeElement​(OutputNode node,
                          java.lang.Object value,
                          Converter convert)
                   throws java.lang.Exception
        This is used write the element specified using the specified converter. Writing the value using the specified converter will result in the node being populated with the elements, attributes, and text values to the provided node. If there is a problem writing the value using the converter an exception is thrown.
        Parameters:
        node - this is the node that the value is to be written to
        value - this is the value that is to be written
        convert - this is the converter used to perform writing
        Throws:
        java.lang.Exception

      • writeNamespaces

        private void writeNamespaces​(OutputNode node,
                             Type type,
                             Label label)
                      throws java.lang.Exception
        This is used to apply Decorator objects to the provided node before it is written. Application of decorations before the node is written allows namespaces and comments to be applied to the node. Decorations such as this do not affect the overall structure of the XML that is written.
        Parameters:
        node - this is the node that decorations are applied to
        type - this is the type to acquire the decoration for
        label - this contains the primary decorator to be used
        Throws:
        java.lang.Exception

      • writeText

        private void writeText​(OutputNode node,
                       java.lang.Object value,
                       Label label)
                throws java.lang.Exception
        This write method is used to set the value of the provided object as the text for the XML element. This will acquire the string value of the object using toString only if the object provided is not an enumerated type. If the object is an enumerated type then the Enum.name method is used.
        Parameters:
        value - this is the value to set as the XML element text
        node - this is the XML element to write the text value to
        label - the label that contains the contact details
        Throws:
        java.lang.Exception

      • isOverridden

        private boolean isOverridden​(OutputNode node,
                             java.lang.Object value,
                             Type type)
                      throws java.lang.Exception
        This is used to determine whether the specified value has been overridden by the strategy. If the item has been overridden then no more serialization is require for that value, this is effectively telling the serialization process to stop writing.
        Parameters:
        node - the node that a potential override is written to
        value - this is the object instance to be serialized
        type - this is the type of the object to be serialized
        Returns:
        returns true if the strategy overrides the object
        Throws:
        java.lang.Exception