Package org.simpleframework.xml.core
Class StructureBuilder
- java.lang.Object
-
- org.simpleframework.xml.core.StructureBuilder
-
class StructureBuilder extends java.lang.Object
TheStructureBuilder
object is used to build the XML structure of an annotated class. Once all the information scanned from the class has been collected aStructure
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 aprocess
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.
-
Constructor Summary
Constructors Constructor Description StructureBuilder(Scanner scanner, Detail detail, Support support)
Constructor for theStructureBuilder
object.
-
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 theStructure
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 aModel
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 aModel
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 aLabel
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 aLabel
implementation needs to be created.private Model
register(Expression path)
This is used to register aModel
for this builder.private void
text(Contact field, java.lang.annotation.Annotation type)
This is used to process theText
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 aLabel
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 theText
annotations that are present in the scanned class.
-
-
-
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 theStructureBuilder
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 annotationstype
- this is the type that is being scannedformat
- 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 aLabel
which can be used to represent the field within the context object.- Parameters:
field
- the field that the annotation comes fromlabel
- 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 aLabel
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 fromtype
- the annotation extracted from the fieldmap
- 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 aLabel
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 fromtype
- the annotation extracted from the fieldmap
- 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 aLabel
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 fromlabel
- this is the label representing a field or methodmap
- 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 theText
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 fromtype
- 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 theText
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 fromtype
- 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 theStructure
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 createSection
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 theOrder
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 aModel
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 aModel
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 aModel
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 anInstantiator
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 aText
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 aText
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 anElementListUnion
annotation has been used with aText
annotation this validates to ensure there are no other elements declared and noPath
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 scannedorder
- 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 scannedorder
- 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
-
-