Class Source

  • All Implemented Interfaces:
    Context

    class Source
    extends java.lang.Object
    implements Context
    The Source object acts as a contextual object that is used to store all information regarding an instance of serialization or deserialization. This maintains the Strategy as well as the Filter used to replace template variables. When serialization and deserialization are performed the source is required as it acts as a factory for objects used in the process.

    For serialization the source object is required as a factory for Schema objects, which are used to visit each field in the class that can be serialized. Also this can be used to get any data entered into the session Map object.

    When deserializing the source object provides the contextual data used to replace template variables extracted from the XML source. This is performed using the Filter object. Also, as in serialization it acts as a factory for the Schema objects used to examine the serializable fields of an object.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private TemplateEngine engine
      This is used to replace variables within the XML source.
      private Filter filter
      This is the filter used by this object for templating.
      private Session session
      This is used to store the source context attribute values.
      private Strategy strategy
      This is the strategy used to resolve the element classes.
      private Support support
      This support is used to convert the strings encountered.
    • Constructor Summary

      Constructors 
      Constructor Description
      Source​(Strategy strategy, Support support, Session session)
      Constructor for the Source object.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object getAttribute​(java.lang.Object key)
      This is used to acquire the attribute mapped to the specified key.
      Caller getCaller​(java.lang.Class type)
      This is used to acquire the Caller object.
      Decorator getDecorator​(java.lang.Class type)
      This will acquire the Decorator for the type.
      Instance getInstance​(java.lang.Class type)
      This will create an Instance that can be used to instantiate objects of the specified class.
      Instance getInstance​(Value value)
      This will create an Instance that can be used to instantiate objects of the specified class.
      java.lang.String getName​(java.lang.Class type)
      This is used to acquire the name of the specified type using the Root annotation for the class.
      Value getOverride​(Type type, InputNode node)
      This is used to resolve and load a class for the given element.
      java.lang.String getProperty​(java.lang.String text)
      Replaces any template variables within the provided string.
      private Scanner getScanner​(java.lang.Class type)
      This creates a Scanner object that can be used to examine the fields within the XML class schema.
      Schema getSchema​(java.lang.Class type)
      This creates a Schema object that can be used to examine the fields within the XML class schema.
      Session getSession()
      This is used to acquire the Session object that is used to store the values used within the serialization process.
      Style getStyle()
      This is used to acquire the Style for the format.
      Support getSupport()
      This is used to acquire the Support object.
      java.lang.Class getType​(Type type, java.lang.Object value)
      This is used to determine the type of an object given the source instance.
      Version getVersion​(java.lang.Class type)
      This returns the version for the type specified.
      boolean isFloat​(java.lang.Class type)
      This is used to determine if the type specified is a floating point type.
      boolean isFloat​(Type type)
      This is used to determine if the type specified is a floating point type.
      boolean isPrimitive​(java.lang.Class type)
      This is used to determine whether the scanned class represents a primitive type.
      boolean isPrimitive​(Type type)
      This is used to determine whether the scanned type represents a primitive type.
      boolean isStrict()
      This is used to determine if the deserialization mode is strict or not.
      boolean setOverride​(Type type, java.lang.Object value, OutputNode node)
      This is used to attach elements or attributes to the given element during the serialization process.
      • Methods inherited from class java.lang.Object

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

      • engine

        private TemplateEngine engine
        This is used to replace variables within the XML source.
      • strategy

        private Strategy strategy
        This is the strategy used to resolve the element classes.
      • support

        private Support support
        This support is used to convert the strings encountered.
      • session

        private Session session
        This is used to store the source context attribute values.
      • filter

        private Filter filter
        This is the filter used by this object for templating.
    • Constructor Detail

      • Source

        public Source​(Strategy strategy,
                      Support support,
                      Session session)
        Constructor for the Source object. This is used to maintain a context during the serialization process. It holds the Strategy and Context used in the serialization process. The same source instance is used for each XML element evaluated in a the serialization process.
        Parameters:
        strategy - this is used to resolve the classes used
        support - this is the context used to process strings
        session - this is the session to use for this context
    • Method Detail

      • isStrict

        public boolean isStrict()
        This is used to determine if the deserialization mode is strict or not. If this is not strict then deserialization will be done in such a way that additional elements and attributes can be ignored. This allows external XML formats to be used without having to match the object structure to the XML fully.
        Specified by:
        isStrict in interface Context
        Returns:
        this returns true if the deserialization is strict
      • getSession

        public Session getSession()
        This is used to acquire the Session object that is used to store the values used within the serialization process. This provides the internal map that is passed to all of the call back methods so that is can be populated.
        Specified by:
        getSession in interface Context
        Returns:
        this returns the session that is used by this source
      • getSupport

        public Support getSupport()
        This is used to acquire the Support object. The support object is used to translate strings to and from their object representations and is also used to convert the strings to their template values. This is the single source of translation for all of the strings encountered.
        Specified by:
        getSupport in interface Context
        Returns:
        this returns the support used by the context
      • getStyle

        public Style getStyle()
        This is used to acquire the Style for the format. If no style has been set a default style is used, which does not modify the attributes and elements that are used to build the resulting XML document.
        Specified by:
        getStyle in interface Context
        Returns:
        this returns the style used for this format object
      • isFloat

        public boolean isFloat​(java.lang.Class type)
                        throws java.lang.Exception
        This is used to determine if the type specified is a floating point type. Types that are floating point are the double and float primitives as well as the java types for this primitives.
        Specified by:
        isFloat in interface Context
        Parameters:
        type - this is the type to determine if it is a float
        Returns:
        this returns true if the type is a floating point
        Throws:
        java.lang.Exception
      • isFloat

        public boolean isFloat​(Type type)
                        throws java.lang.Exception
        This is used to determine if the type specified is a floating point type. Types that are floating point are the double and float primitives as well as the java types for this primitives.
        Specified by:
        isFloat in interface Context
        Parameters:
        type - this is the type to determine if it is a float
        Returns:
        this returns true if the type is a floating point
        Throws:
        java.lang.Exception
      • isPrimitive

        public boolean isPrimitive​(java.lang.Class type)
                            throws java.lang.Exception
        This is used to determine whether the scanned class represents a primitive type. A primitive type is a type that contains no XML annotations and so cannot be serialized with an XML form. Instead primitives a serialized using transformations.
        Specified by:
        isPrimitive in interface Context
        Parameters:
        type - this is the type to determine if it is primitive
        Returns:
        this returns true if no XML annotations were found
        Throws:
        java.lang.Exception
      • isPrimitive

        public boolean isPrimitive​(Type type)
                            throws java.lang.Exception
        This is used to determine whether the scanned type represents a primitive type. A primitive type is a type that contains no XML annotations and so cannot be serialized with an XML form. Instead primitives a serialized using transformations.
        Specified by:
        isPrimitive in interface Context
        Parameters:
        type - this is the type to determine if it is primitive
        Returns:
        this returns true if no XML annotations were found
        Throws:
        java.lang.Exception
      • getInstance

        public Instance getInstance​(java.lang.Class type)
        This will create an Instance that can be used to instantiate objects of the specified class. This leverages an internal constructor cache to ensure creation is quicker.
        Specified by:
        getInstance in interface Context
        Parameters:
        type - this is the type that is to be instantiated
        Returns:
        this will return an object for instantiating objects
      • getInstance

        public Instance getInstance​(Value value)
        This will create an Instance that can be used to instantiate objects of the specified class. This leverages an internal constructor cache to ensure creation is quicker.
        Specified by:
        getInstance in interface Context
        Parameters:
        value - this contains information on the object instance
        Returns:
        this will return an object for instantiating objects
      • getName

        public java.lang.String getName​(java.lang.Class type)
                                 throws java.lang.Exception
        This is used to acquire the name of the specified type using the Root annotation for the class. This will use either the name explicitly provided by the annotation or it will use the name of the class that the annotation was placed on if there is no explicit name for the root.
        Specified by:
        getName in interface Context
        Parameters:
        type - this is the type to acquire the root name for
        Returns:
        this returns the name of the type from the root
        Throws:
        java.lang.Exception - if the class contains an illegal schema
      • getVersion

        public Version getVersion​(java.lang.Class type)
                           throws java.lang.Exception
        This returns the version for the type specified. The version is used to determine how the deserialization process is performed. If the version of the type is different from the version for the XML document, then deserialization is done in a best effort.
        Specified by:
        getVersion in interface Context
        Parameters:
        type - this is the type to acquire the version for
        Returns:
        the version that has been set for this XML schema class
        Throws:
        java.lang.Exception
      • getScanner

        private Scanner getScanner​(java.lang.Class type)
                            throws java.lang.Exception
        This creates a Scanner object that can be used to examine the fields within the XML class schema. The scanner maintains information when a field from within the scanner is visited, this allows the serialization and deserialization process to determine if all required XML annotations are used.
        Parameters:
        type - the schema class the scanner is created for
        Returns:
        a scanner that can maintains information on the type
        Throws:
        java.lang.Exception - if the class contains an illegal schema
      • getDecorator

        public 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.
        Specified by:
        getDecorator in interface Context
        Parameters:
        type - this is the type to acquire the decorator for
        Returns:
        this returns the decorator associated with this
        Throws:
        java.lang.Exception
      • getCaller

        public Caller getCaller​(java.lang.Class type)
                         throws java.lang.Exception
        This is used to acquire the Caller object. This is used to call the callback methods within the object. If the object contains no callback methods then this will return an object that does not invoke any methods that are invoked.
        Specified by:
        getCaller in interface Context
        Parameters:
        type - this is the type to acquire the caller for
        Returns:
        this returns the caller for the specified type
        Throws:
        java.lang.Exception
      • getSchema

        public Schema getSchema​(java.lang.Class type)
                         throws java.lang.Exception
        This creates a Schema object that can be used to examine the fields within the XML class schema. The schema maintains information when a field from within the schema is visited, this allows the serialization and deserialization process to determine if all required XML annotations are used.
        Specified by:
        getSchema in interface Context
        Parameters:
        type - the schema class the schema is created for
        Returns:
        a new schema that can track visits within the schema
        Throws:
        java.lang.Exception - if the class contains an illegal schema
      • getAttribute

        public java.lang.Object getAttribute​(java.lang.Object key)
        This is used to acquire the attribute mapped to the specified key. In order for this to return a value it must have been previously placed into the context as it is empty by default.
        Specified by:
        getAttribute in interface Context
        Parameters:
        key - this is the name of the attribute to retrieve
        Returns:
        this returns the value mapped to the specified key
      • getOverride

        public Value getOverride​(Type type,
                                 InputNode node)
                          throws java.lang.Exception
        This is used to resolve and load a class for the given element. The class should be of the same type or a subclass of the class specified. It can be resolved using the details within the provided XML element, if the details used do not represent any serializable values they should be removed so as not to disrupt the deserialization process. For example the default strategy removes all "class" attributes from the given elements.
        Specified by:
        getOverride in interface Context
        Parameters:
        type - this is the type of the root element expected
        node - this is the element used to resolve an override
        Returns:
        returns the type that should be used for the object
        Throws:
        java.lang.Exception - thrown if the class cannot be resolved
      • setOverride

        public boolean setOverride​(Type type,
                                   java.lang.Object value,
                                   OutputNode node)
                            throws java.lang.Exception
        This is used to attach elements or attributes to the given element during the serialization process. This method allows the strategy to augment the XML document so that it can be deserialized using a similar strategy. For example the default strategy adds a "class" attribute to the element.
        Specified by:
        setOverride in interface Context
        Parameters:
        type - this is the field type for the associated value
        value - this is the instance variable being serialized
        node - this is the element used to represent the value
        Returns:
        this returns true if serialization has complete
        Throws:
        java.lang.Exception - thrown if the details cannot be set
      • getType

        public java.lang.Class getType​(Type type,
                                       java.lang.Object value)
        This is used to determine the type of an object given the source instance. To provide a best match approach this will first attempt to get the value for the actual instance, if however the instance is null the type is delegated to.
        Specified by:
        getType in interface Context
        Parameters:
        type - this is the type used in the serialization
        value - this is the source instance being used
        Returns:
        the best match given the criteria
      • getProperty

        public java.lang.String getProperty​(java.lang.String text)
        Replaces any template variables within the provided string. This is used in the deserialization process to replace variables with system properties, environment variables, or used specified mappings. If a template variable does not have a mapping from the Filter is is left unchanged.
        Specified by:
        getProperty in interface Context
        Parameters:
        text - this is processed by the template engine object
        Returns:
        this returns the text will all variables replaced