Package org.simpleframework.xml.core

Class StructureBuilder

java.lang.Object
org.simpleframework.xml.core.StructureBuilder
class StructureBuilder extends 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:

  • 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.

  • Constructor Summary

    Constructors
    Constructor
    Description
    StructureBuilder(Scanner scanner, Detail detail, Support support)
    Constructor for the StructureBuilder object.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    assemble(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(Class type)
    This is used to build the Structure that has been built.
    void
    commit(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(String path)
    This is used to determine if the specified XPath expression represents an attribute within the root model.
    private boolean
    isElement(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, Annotation label)
    This reflectively checks the annotation to determine the type of annotation it represents.
    private void
    process(Contact field, 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, Annotation type)
    This is used to process the Text annotations that are present in the scanned class.
    private void
    union(Contact field, 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(Class type)
    This is used to validate the configuration of the scanned class.
    private void
    validateAttributes(Class type, Order order)
    This is used to validate the configuration of the scanned class.
    private void
    validateElements(Class type, Order order)
    This is used to validate the configuration of the scanned class.
    private void
    validateModel(Class type)
    This is used to validate the model to ensure all elements and attributes are valid.
    private void
    validateText(Class type)
    This is used to validate the configuration of the scanned class.
    private void
    validateTextList(Class type)
    This is used to validate the configuration of the scanned class.
    private void
    validateUnions(Class type)
    This is used to validate the unions that have been defined within the type.
    private void
    version(Contact field, 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 Details

    • 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 Details

    • StructureBuilder

      public StructureBuilder(Scanner scanner, Detail detail, Support support) throws 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:
      Exception

  • Method Details

    • assemble

      public void assemble(Class type) throws 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:
      Exception

    • process

      public void process(Contact field, Annotation label) throws 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:
      Exception - if there is more than one text annotation

    • union

      private void union(Contact field, Annotation type, LabelMap map) throws 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:
      Exception - thrown if the label can not be created

    • process

      private void process(Contact field, Annotation type, LabelMap map) throws 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:
      Exception - thrown if the label can not be created

    • process

      private void process(Contact field, Label label, LabelMap map) throws 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:
      Exception - thrown if the label can not be created

    • text

      private void text(Contact field, Annotation type) throws 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:
      Exception - if there is more than one text annotation

    • version

      private void version(Contact field, Annotation type) throws 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:
      Exception - if there is more than one text annotation

    • build

      public Structure build(Class type) throws 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:
      Exception

    • isElement

      private boolean isElement(String path) throws 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:
      Exception

    • isAttribute

      private boolean isAttribute(String path) throws 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:
      Exception

    • lookup

      private Model lookup(Expression path) throws 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:
      Exception

    • register

      private Model register(Expression path) throws 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:
      Exception

    • create

      private Model create(Expression path) throws 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:
      Exception

    • commit

      public void commit(Class type) throws 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:
      Exception

    • validate

      public void validate(Class type) throws 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:
      Exception

    • validateModel

      private void validateModel(Class type) throws 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:
      Exception

    • validateText

      private void validateText(Class type) throws 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:
      Exception

    • validateTextList

      private void validateTextList(Class type) throws 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:
      Exception

    • validateUnions

      private void validateUnions(Class type) throws 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:
      Exception

    • validateElements

      private void validateElements(Class type, Order order) throws 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:
      Exception

    • validateAttributes

      private void validateAttributes(Class type, Order order) throws 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:
      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