Class StructureBuilder


  • class StructureBuilder
    extends java.lang.Object
    The StructureBuilder object is used to build the XML structure of an annotated class. Once all the information scanned from the class has been collected a Structure object can be built using this object. The structure instance will contain relevant information regarding the class schema.

    This builder exposes several methods, which are invoked in a sequence by the Scanner object. In particular there is a process method which is used to consume the annotated fields and methods. With the annotations it then builds the underlying structure representing the class schema.

    See Also:
    Scanner
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private ModelAssembler assembler
      This is used to perform the initial ordered registrations.
      private LabelMap attributes
      For validation all attributes must be stored in the builder.
      private ExpressionBuilder builder
      This is used to build XPath expressions from annotations.
      private LabelMap elements
      For validation all elements must be stored in the builder.
      private Instantiator factory
      This is the instantiator that is used to create instances.
      private boolean primitive
      This is used to determine if the scanned class is primitive.
      private InstantiatorBuilder resolver
      This is used to build an instantiator for creating objects.
      private Model root
      This the core model used to represent the XML structure.
      private Scanner scanner
      This is the source scanner that is used to scan the class.
      private Support support
      This object contains various support functions for the class.
      private Label text
      This represents a text annotation extracted from the class.
      private LabelMap texts
      This is used to maintain the text labels for the class.
      private Label version
      This is the version annotation extracted from the class.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void assemble​(java.lang.Class type)
      This is used to acquire the optional order annotation to provide order to the elements and attributes for the generated XML.
      Structure build​(java.lang.Class type)
      This is used to build the Structure that has been built.
      void commit​(java.lang.Class type)
      This is used to commit the structure of the type.
      private Model create​(Expression path)
      This is used to register a Model for this builder.
      private boolean isAttribute​(java.lang.String path)
      This is used to determine if the specified XPath expression represents an attribute within the root model.
      private boolean isElement​(java.lang.String path)
      This is used to determine if the specified XPath expression represents an element within the root model.
      private boolean isEmpty()
      This is used to determine if the structure is empty.
      private Model lookup​(Expression path)
      This method is used to look for a Model that matches the specified expression.
      void process​(Contact field, java.lang.annotation.Annotation label)
      This reflectively checks the annotation to determine the type of annotation it represents.
      private void process​(Contact field, java.lang.annotation.Annotation type, LabelMap map)
      This is used when all details from a field have been gathered and a Label implementation needs to be created.
      private void process​(Contact field, Label label, LabelMap map)
      This is used when all details from a field have been gathered and a Label implementation needs to be created.
      private Model register​(Expression path)
      This is used to register a Model for this builder.
      private void text​(Contact field, java.lang.annotation.Annotation type)
      This is used to process the Text annotations that are present in the scanned class.
      private void union​(Contact field, java.lang.annotation.Annotation type, LabelMap map)
      This is used when all details from a field have been gathered and a Label implementation needs to be created.
      void validate​(java.lang.Class type)
      This is used to validate the configuration of the scanned class.
      private void validateAttributes​(java.lang.Class type, Order order)
      This is used to validate the configuration of the scanned class.
      private void validateElements​(java.lang.Class type, Order order)
      This is used to validate the configuration of the scanned class.
      private void validateModel​(java.lang.Class type)
      This is used to validate the model to ensure all elements and attributes are valid.
      private void validateText​(java.lang.Class type)
      This is used to validate the configuration of the scanned class.
      private void validateTextList​(java.lang.Class type)
      This is used to validate the configuration of the scanned class.
      private void validateUnions​(java.lang.Class type)
      This is used to validate the unions that have been defined within the type.
      private void version​(Contact field, java.lang.annotation.Annotation type)
      This is used to process the Text annotations that are present in the scanned class.
      • Methods inherited from class java.lang.Object

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

      • resolver

        private InstantiatorBuilder resolver
        This is used to build an instantiator for creating objects.
      • builder

        private ExpressionBuilder builder
        This is used to build XPath expressions from annotations.
      • assembler

        private ModelAssembler assembler
        This is used to perform the initial ordered registrations.
      • factory

        private Instantiator factory
        This is the instantiator that is used to create instances.
      • attributes

        private LabelMap attributes
        For validation all attributes must be stored in the builder.
      • elements

        private LabelMap elements
        For validation all elements must be stored in the builder.
      • texts

        private LabelMap texts
        This is used to maintain the text labels for the class.
      • scanner

        private Scanner scanner
        This is the source scanner that is used to scan the class.
      • support

        private Support support
        This object contains various support functions for the class.
      • version

        private Label version
        This is the version annotation extracted from the class.
      • text

        private Label text
        This represents a text annotation extracted from the class.
      • root

        private Model root
        This the core model used to represent the XML structure.
      • primitive

        private boolean primitive
        This is used to determine if the scanned class is primitive.
    • Constructor Detail

      • StructureBuilder

        public StructureBuilder​(Scanner scanner,
                                Detail detail,
                                Support support)
                         throws java.lang.Exception
        Constructor for the StructureBuilder object. This is used to process all the annotations for a class schema and build a hierarchical model representing the required structure. Once the structure has been built then it is validated to ensure that all elements and attributes exist.
        Parameters:
        scanner - this is the scanner used to scan annotations
        type - this is the type that is being scanned
        format - this is the format used to style the XML
        Throws:
        java.lang.Exception
    • Method Detail

      • assemble

        public void assemble​(java.lang.Class type)
                      throws java.lang.Exception
        This is used to acquire the optional order annotation to provide order to the elements and attributes for the generated XML. This acts as an override to the order provided by the declaration of the types within the object.
        Parameters:
        type - this is the type to be scanned for the order
        Throws:
        java.lang.Exception
      • process

        public void process​(Contact field,
                            java.lang.annotation.Annotation label)
                     throws java.lang.Exception
        This reflectively checks the annotation to determine the type of annotation it represents. If it represents an XML schema annotation it is used to create a Label which can be used to represent the field within the context object.
        Parameters:
        field - the field that the annotation comes from
        label - the annotation used to model the XML schema
        Throws:
        java.lang.Exception - if there is more than one text annotation
      • union

        private void union​(Contact field,
                           java.lang.annotation.Annotation type,
                           LabelMap map)
                    throws java.lang.Exception
        This is used when all details from a field have been gathered and a Label implementation needs to be created. This will build a label instance based on the field annotation. If a label with the same name was already inserted then it is ignored and the value for that field will not be serialized.
        Parameters:
        field - the field the annotation was extracted from
        type - the annotation extracted from the field
        map - this is used to collect the label instance created
        Throws:
        java.lang.Exception - thrown if the label can not be created
      • process

        private void process​(Contact field,
                             java.lang.annotation.Annotation type,
                             LabelMap map)
                      throws java.lang.Exception
        This is used when all details from a field have been gathered and a Label implementation needs to be created. This will build a label instance based on the field annotation. If a label with the same name was already inserted then it is ignored and the value for that field will not be serialized.
        Parameters:
        field - the field the annotation was extracted from
        type - the annotation extracted from the field
        map - this is used to collect the label instance created
        Throws:
        java.lang.Exception - thrown if the label can not be created
      • process

        private void process​(Contact field,
                             Label label,
                             LabelMap map)
                      throws java.lang.Exception
        This is used when all details from a field have been gathered and a Label implementation needs to be created. This will build a label instance based on the field annotation. If a label with the same name was already inserted then it is ignored and the value for that field will not be serialized.
        Parameters:
        field - the field the annotation was extracted from
        label - this is the label representing a field or method
        map - this is used to collect the label instance created
        Throws:
        java.lang.Exception - thrown if the label can not be created
      • text

        private void text​(Contact field,
                          java.lang.annotation.Annotation type)
                   throws java.lang.Exception
        This is used to process the Text annotations that are present in the scanned class. This will set the text label for the class and an ensure that if there is more than one text label within the class an exception is thrown.
        Parameters:
        field - the field the annotation was extracted from
        type - the annotation extracted from the field
        Throws:
        java.lang.Exception - if there is more than one text annotation
      • version

        private void version​(Contact field,
                             java.lang.annotation.Annotation type)
                      throws java.lang.Exception
        This is used to process the Text annotations that are present in the scanned class. This will set the text label for the class and an ensure that if there is more than one text label within the class an exception is thrown.
        Parameters:
        field - the field the annotation was extracted from
        type - the annotation extracted from the field
        Throws:
        java.lang.Exception - if there is more than one text annotation
      • build

        public Structure build​(java.lang.Class type)
                        throws java.lang.Exception
        This is used to build the Structure that has been built. The structure will contain all the details required to serialize and deserialize the type. Once created the structure is immutable, and can be used to create Section objects, which contains the element and attribute details.
        Parameters:
        type - this is the type that represents the schema class
        Returns:
        this returns the structure that has been built
        Throws:
        java.lang.Exception
      • isElement

        private boolean isElement​(java.lang.String path)
                           throws java.lang.Exception
        This is used to determine if the specified XPath expression represents an element within the root model. This will return true if the specified path exists as either an element or as a valid path to an existing model.

        If the path references a Model then that is an element only if it is not empty. If the model is empty this means that it was used in the Order annotation only and this does not refer to a value XML element.

        Parameters:
        path - this is the path to search for the element
        Returns:
        this returns true if an element or model exists
        Throws:
        java.lang.Exception
      • isAttribute

        private boolean isAttribute​(java.lang.String path)
                             throws java.lang.Exception
        This is used to determine if the specified XPath expression represents an attribute within the root model. This returns true if the specified path exists as either an attribute.
        Parameters:
        path - this is the path to search for the attribute
        Returns:
        this returns true if the attribute exists
        Throws:
        java.lang.Exception
      • lookup

        private Model lookup​(Expression path)
                      throws java.lang.Exception
        This method is used to look for a Model that matches the specified expression. If no such model exists then this will return null. Using an XPath expression allows a tree like structure to be navigated with ease.
        Parameters:
        path - an XPath expression used to locate a model
        Returns:
        this returns the model located by the expression
        Throws:
        java.lang.Exception
      • register

        private Model register​(Expression path)
                        throws java.lang.Exception
        This is used to register a Model for this builder. Registration of a model creates a tree of models that is used to represent an XML structure. Each model can contain elements and attributes associated with a type.
        Parameters:
        path - this is the path of the model to be resolved
        Returns:
        this returns the model that was registered
        Throws:
        java.lang.Exception
      • create

        private Model create​(Expression path)
                      throws java.lang.Exception
        This is used to register a Model for this builder. Registration of a model creates a tree of models that is used to represent an XML structure. Each model can contain elements and attributes associated with a type.
        Parameters:
        path - this is the path of the model to be resolved
        Returns:
        this returns the model that was registered
        Throws:
        java.lang.Exception
      • commit

        public void commit​(java.lang.Class type)
                    throws java.lang.Exception
        This is used to commit the structure of the type. This will build an Instantiator that can be used to create instances using annotated constructors. If no constructors have be annotated then instances can use the default constructor.
        Parameters:
        type - this is the type that this builder creates
        Throws:
        java.lang.Exception
      • validate

        public void validate​(java.lang.Class type)
                      throws java.lang.Exception
        This is used to validate the configuration of the scanned class. If a Text annotation has been used with elements then validation will fail and an exception will be thrown.
        Parameters:
        type - this is the object type that is being scanned
        Throws:
        java.lang.Exception
      • validateModel

        private void validateModel​(java.lang.Class type)
                            throws java.lang.Exception
        This is used to validate the model to ensure all elements and attributes are valid. Validation also ensures that any order specified by an annotated class did not contain invalid XPath values, or redundant elements and attributes.
        Parameters:
        type - this is the object type representing the schema
        Throws:
        java.lang.Exception
      • validateText

        private void validateText​(java.lang.Class type)
                           throws java.lang.Exception
        This is used to validate the configuration of the scanned class. If a Text annotation has been used with elements then validation will fail and an exception will be thrown.
        Parameters:
        type - this is the object type that is being scanned
        Throws:
        java.lang.Exception
      • validateTextList

        private void validateTextList​(java.lang.Class type)
                               throws java.lang.Exception
        This is used to validate the configuration of the scanned class. If an ElementListUnion annotation has been used with a Text annotation this validates to ensure there are no other elements declared and no Path annotations have been used, which ensures free text can be processed.
        Parameters:
        type - this is the object type that is being scanned
        Throws:
        java.lang.Exception
      • validateUnions

        private void validateUnions​(java.lang.Class type)
                             throws java.lang.Exception
        This is used to validate the unions that have been defined within the type. Union validation is done by determining if the union has consistent inline values. If one annotation in the union declaration is inline, then all must be inline.
        Parameters:
        type - this is the type to validate the unions for
        Throws:
        java.lang.Exception
      • validateElements

        private void validateElements​(java.lang.Class type,
                                      Order order)
                               throws java.lang.Exception
        This is used to validate the configuration of the scanned class. If an ordered element is specified but does not refer to an existing element then this will throw an exception.
        Parameters:
        type - this is the object type that is being scanned
        order - this is the order that is to be validated
        Throws:
        java.lang.Exception
      • validateAttributes

        private void validateAttributes​(java.lang.Class type,
                                        Order order)
                                 throws java.lang.Exception
        This is used to validate the configuration of the scanned class. If an ordered attribute is specified but does not refer to an existing attribute then this will throw an exception.
        Parameters:
        type - this is the object type that is being scanned
        order - this is the order that is to be validated
        Throws:
        java.lang.Exception
      • isEmpty

        private boolean isEmpty()
        This is used to determine if the structure is empty. To check to see if the structure is empty all models within the tree must be examined. Also, if there is a text annotation then it is not considered to be empty.
        Returns:
        true if the structure represents an empty schema