Class TreeModel

java.lang.Object
org.simpleframework.xml.core.TreeModel
All Implemented Interfaces:
Iterable<String>, Model
class TreeModel extends Object implements Model
The TreeModel object is used to build a tree like structure to represent the XML schema for an annotated class. The model is responsible for building, ordering, and validating all criteria used to represent the class schema. This is immutable to ensure it can be reused many time, in a concurrent environment. Each time attribute and element definitions are requested they are build as new LabelMap objects using a provided context. This ensures the mappings can be styled as required.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static class 
    TreeModel.OrderList
    The OrderList object is used to maintain the order of the XML elements within the model.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private LabelMap
    attributes
    This holds the mappings for elements within the model.
    private Detail
    detail
    This is the type used for reporting validation errors.
    private LabelMap
    elements
    This holds the mappings for elements within the model.
    private Expression
    expression
    This is the XPath expression representing the location.
    private int
    index
    This is the index used to sort similarly named models.
    private Label
    list
    This is an optional text label used for this model.
    private ModelMap
    models
    This holds the mappings for the models within this instance.
    private String
    name
    This must be a valid XML element representing the name.
    private TreeModel.OrderList
    order
    This is used to provide the order of the model elements.
    private Policy
    policy
    This is the serialization policy enforced on this model.
    private String
    prefix
    This is used to represent the prefix for this model.
    private Label
    text
    This is an optional text label used for this model.

  • Constructor Summary

    Constructors
    Constructor
    Description
    TreeModel(Policy policy, Detail detail)
    Constructor for the TreeModel object.
    TreeModel(Policy policy, Detail detail, String name, String prefix, int index)
    Constructor for the TreeModel object.

  • Method Summary

    Modifier and Type
    Method
    Description
    private Model
    create(String name, String prefix, int index)
    This is used to register a Model within this model.
    LabelMap
    getAttributes()
    This is used to build a map from a Context object.
    LabelMap
    getElements()
    This is used to build a map from a Context object.
    Expression
    getExpression()
    This returns an Expression representing the path this model exists at within the class schema.
    int
    getIndex()
    This method is used to return the index of the model.
    ModelMap
    getModels()
    This is used to build a map from a Context object.
    String
    getName()
    This is used to return the name of the model.
    String
    getPrefix()
    This is used to acquire the path prefix for the model.
    Label
    getText()
    This returns a text label if one is associated with the model.
    boolean
    isAttribute(String name)
    This is used to determine if the provided name represents an attribute.
    boolean
    isComposite()
    This is used to perform a recursive search of the models that have been registered, if a model has elements or attributes then this returns true.
    boolean
    isElement(String name)
    This is used to determine if the provided name represents an element.
    boolean
    isEmpty()
    Used to determine if a model is empty.
    boolean
    isModel(String name)
    This is used to determine if the provided name represents a model.
    Iterator<String>
    iterator()
    This will return the names of all elements contained within the model.
    Model
    lookup(String name, int index)
    This method is used to look for a Model that matches the specified element name.
    Model
    lookup(Expression path)
    This method is used to look for a Model that matches the specified expression.
    Model
    register(String name, String prefix, int index)
    This is used to register a Model within this model.
    void
    register(Label label)
    This is used to register an XML entity within the model.
    void
    registerAttribute(String name)
    This is used to register an XML entity within the model.
    void
    registerAttribute(Label label)
    This is used to register an XML entity within the model.
    void
    registerElement(String name)
    This is used to register an XML entity within the model.
    void
    registerElement(Label label)
    This is used to register an XML entity within the model.
    void
    registerText(Label label)
    This is used to register an XML entity within the model.
    String
    toString()
    For the purposes of debugging we provide a representation of the model in a string format.
    void
    validate(Class type)
    This is used to validate the model to ensure all elements and attributes are valid.
    private void
    validateAttributes(Class type)
    This is used to validate the individual attributes within the model.
    private void
    validateElements(Class type)
    This is used to validate the individual elements within the model.
    private void
    validateExpression(Label label)
    This is used to validate the expressions used for a label that this model represents.
    private void
    validateExpressions(Class type)
    This is used to validate the expressions used for each label that this model represents.
    private void
    validateModels(Class type)
    This is used to validate the models within the instance.
    private void
    validateText(Class type)
    This method is used to validate the model based on whether it has a text annotation.

    Methods inherited from class Object

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

    Methods inherited from interface Iterable

    forEach, spliterator

  • Field Details

    • expression

      private Expression expression
      This is the XPath expression representing the location.

    • attributes

      private LabelMap attributes
      This holds the mappings for elements within the model.

    • elements

      private LabelMap elements
      This holds the mappings for elements within the model.

    • models

      private ModelMap models
      This holds the mappings for the models within this instance.

    • order

      private TreeModel.OrderList order
      This is used to provide the order of the model elements.

    • policy

      private Policy policy
      This is the serialization policy enforced on this model.

    • detail

      private Detail detail
      This is the type used for reporting validation errors.

    • name

      private String name
      This must be a valid XML element representing the name.

    • prefix

      private String prefix
      This is used to represent the prefix for this model.

    • text

      private Label text
      This is an optional text label used for this model.

    • list

      private Label list
      This is an optional text label used for this model.

    • index

      private int index
      This is the index used to sort similarly named models.

  • Constructor Details

    • TreeModel

      public TreeModel(Policy policy, Detail detail)
      Constructor for the TreeModel object. This can be used to register the attributes and elements associated with an annotated class. Also, if there are any path references, this can contain a tree of models mirroring the XML structure.
      Parameters:
      policy - this is the serialization policy enforced
      detail - this is the detail associated with this model

    • TreeModel

      public TreeModel(Policy policy, Detail detail, String name, String prefix, int index)
      Constructor for the TreeModel object. This can be used to register the attributes and elements associated with an annotated class. Also, if there are any path references, this can contain a tree of models mirroring the XML structure.
      Parameters:
      policy - this is the serialization policy enforced
      detail - this is the detail associated with this model
      name - this is the XML element name for this model
      prefix - this is the prefix used for this model object
      index - this is the index used to order the model

  • Method Details

    • lookup

      public Model lookup(Expression path)
      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.
      Specified by:
      lookup in interface Model
      Parameters:
      path - an XPath expression used to locate a model
      Returns:
      this returns the model located by the expression

    • registerElement

      public void registerElement(String name) throws Exception
      This is used to register an XML entity within the model. The registration process has the affect of telling the model that it will contain a specific, named, XML entity. It also has the affect of ordering them within the model, such that the first registered entity is the first iterated over.
      Specified by:
      registerElement in interface Model
      Parameters:
      name - this is the name of the element to register
      Throws:
      Exception

    • registerAttribute

      public void registerAttribute(String name) throws Exception
      This is used to register an XML entity within the model. The registration process has the affect of telling the model that it will contain a specific, named, XML entity. It also has the affect of ordering them within the model, such that the first registered entity is the first iterated over.
      Specified by:
      registerAttribute in interface Model
      Parameters:
      name - this is the name of the element to register
      Throws:
      Exception

    • registerText

      public void registerText(Label label) throws Exception
      This is used to register an XML entity within the model. The registration process has the affect of telling the model that it will contain a specific, named, XML entity. It also has the affect of ordering them within the model, such that the first registered entity is the first iterated over.
      Specified by:
      registerText in interface Model
      Parameters:
      label - this is the label to register with the model
      Throws:
      Exception

    • registerAttribute

      public void registerAttribute(Label label) throws Exception
      This is used to register an XML entity within the model. The registration process has the affect of telling the model that it will contain a specific, named, XML entity. It also has the affect of ordering them within the model, such that the first registered entity is the first iterated over.
      Specified by:
      registerAttribute in interface Model
      Parameters:
      label - this is the label to register with the model
      Throws:
      Exception

    • registerElement

      public void registerElement(Label label) throws Exception
      This is used to register an XML entity within the model. The registration process has the affect of telling the model that it will contain a specific, named, XML entity. It also has the affect of ordering them within the model, such that the first registered entity is the first iterated over.
      Specified by:
      registerElement in interface Model
      Parameters:
      label - this is the label to register with the model
      Throws:
      Exception

    • getModels

      public ModelMap getModels() throws Exception
      This is used to build a map from a Context object. Building a map in this way ensures that any style specified by the context can be used to create the XML element and attribute names in the styled format. It also ensures that the model remains immutable as it only provides copies of its data.
      Specified by:
      getModels in interface Model
      Returns:
      this returns a map built from the specified context
      Throws:
      Exception

    • getAttributes

      public LabelMap getAttributes() throws Exception
      This is used to build a map from a Context object. Building a map in this way ensures that any style specified by the context can be used to create the XML element and attribute names in the styled format. It also ensures that the model remains immutable as it only provides copies of its data.
      Specified by:
      getAttributes in interface Model
      Returns:
      this returns a map built from the specified context
      Throws:
      Exception

    • getElements

      public LabelMap getElements() throws Exception
      This is used to build a map from a Context object. Building a map in this way ensures that any style specified by the context can be used to create the XML element and attribute names in the styled format. It also ensures that the model remains immutable as it only provides copies of its data.
      Specified by:
      getElements in interface Model
      Returns:
      this returns a map built from the specified context
      Throws:
      Exception

    • isModel

      public boolean isModel(String name)
      This is used to determine if the provided name represents a model. This is useful when validating the model as it allows determination of a named model, which is an element.
      Specified by:
      isModel in interface Model
      Parameters:
      name - this is the name of the section to determine
      Returns:
      this returns true if the model is registered

    • isElement

      public boolean isElement(String name)
      This is used to determine if the provided name represents an element. This is useful when validating the model as it allows determination of a named XML element.
      Specified by:
      isElement in interface Model
      Parameters:
      name - this is the name of the section to determine
      Returns:
      this returns true if the element is registered

    • isAttribute

      public boolean isAttribute(String name)
      This is used to determine if the provided name represents an attribute. This is useful when validating the model as it allows determination of a named XML attribute
      Specified by:
      isAttribute in interface Model
      Parameters:
      name - this is the name of the attribute to determine
      Returns:
      this returns true if the attribute is registered

    • iterator

      public Iterator<String> iterator()
      This will return the names of all elements contained within the model. This includes the names of all XML elements that have been registered as well as any other models that have been added. Iteration is done in an ordered manner, according to the registration of elements and models.
      Specified by:
      iterator in interface Iterable<String>
      Returns:
      an order list of the elements and models registered

    • validate

      public void validate(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.
      Specified by:
      validate in interface Model
      Parameters:
      type - this is the object type representing the schema
      Throws:
      Exception - if text and element annotations are present

    • validateText

      private void validateText(Class type) throws Exception
      This method is used to validate the model based on whether it has a text annotation. If this model has a text annotation then it is checked to see if it is a composite model or has any elements. If it has either then the model is considered invalid.
      Parameters:
      type - this is the object type representing the schema
      Throws:
      Exception

    • validateExpressions

      private void validateExpressions(Class type) throws Exception
      This is used to validate the expressions used for each label that this model represents. Each label within a model must have an XPath expression, if the expressions do not match then this will throw an exception. If the model contains no labels then it is considered empty and does not need validation.
      Parameters:
      type - this is the object type representing the schema
      Throws:
      Exception

    • validateExpression

      private void validateExpression(Label label) throws Exception
      This is used to validate the expressions used for a label that this model represents. Each label within a model must have an XPath expression, if the expressions do not match then this will throw an exception. If the model contains no labels then it is considered empty and does not need validation.
      Parameters:
      label - this is the object type representing the schema
      Throws:
      Exception

    • validateModels

      private void validateModels(Class type) throws Exception
      This is used to validate the models within the instance. This will basically result in validation of the entire tree. Once finished all models contained within the tree will be valid. If any model is invalid an exception will be thrown.

      To ensure that all ordering and registration of the models is consistent this will check to ensure the indexes of each registered model are in sequence. If they are out of sequence then this will throw an exception.

      Parameters:
      type - this is the type this model is created for
      Throws:
      Exception

    • validateAttributes

      private void validateAttributes(Class type) throws Exception
      This is used to validate the individual attributes within the model. Validation is done be acquiring all the attributes and determining if they are null. If they are null this means that an ordering has been imposed on a non-existing attribute.
      Parameters:
      type - this is the type this model is created for
      Throws:
      Exception

    • validateElements

      private void validateElements(Class type) throws Exception
      This is used to validate the individual elements within the model. Validation is done be acquiring all the elements and determining if they are null. If they are null this means that an ordering has been imposed on a non-existing element.
      Parameters:
      type - this is the type this model is created for
      Throws:
      Exception

    • register

      public void register(Label label) throws Exception
      This is used to register an XML entity within the model. The registration process has the affect of telling the model that it will contain a specific, named, XML entity. It also has the affect of ordering them within the model, such that the first registered entity is the first iterated over.
      Specified by:
      register in interface Model
      Parameters:
      label - this is the label to register with the model
      Throws:
      Exception

    • lookup

      public Model lookup(String name, int index)
      This method is used to look for a Model that matches the specified element name. If no such model exists then this will return null. This is used as an alternative to providing an XPath expression to navigate the tree.
      Specified by:
      lookup in interface Model
      Parameters:
      name - this is the name of the model to be acquired
      index - this is the index used to order the model
      Returns:
      this returns the model located by the expression

    • register

      public Model register(String name, String prefix, int index) throws Exception
      This is used to register a Model within this model. Registration of a model creates a tree of models that can be used to represent an XML structure. Each model can contain elements and attributes associated with a type.
      Specified by:
      register in interface Model
      Parameters:
      name - this is the name of the model to be registered
      prefix - this is the prefix used for this model
      index - this is the index used to order the model
      Returns:
      this returns the model that was registered
      Throws:
      Exception

    • create

      private Model create(String name, String prefix, int index) throws Exception
      This is used to register a Model within this model. Registration of a model creates a tree of models that can be used to represent an XML structure. Each model can contain elements and attributes associated with a type.
      Parameters:
      name - this is the name of the model to be registered
      prefix - this is the prefix used for this model
      index - this is the index used to order the model
      Returns:
      this returns the model that was registered
      Throws:
      Exception

    • isComposite

      public boolean isComposite()
      This is used to perform a recursive search of the models that have been registered, if a model has elements or attributes then this returns true. If however no other model contains any attributes or elements then this will return false.
      Specified by:
      isComposite in interface Model
      Returns:
      true if any model has elements or attributes

    • isEmpty

      public boolean isEmpty()
      Used to determine if a model is empty. A model is considered empty if that model does not contain any registered elements or attributes. However, if the model contains other models that have registered elements or attributes it is not empty.
      Specified by:
      isEmpty in interface Model
      Returns:
      true if the model does not contain registrations

    • getText

      public Label getText()
      This returns a text label if one is associated with the model. If the model does not contain a text label then this method will return null. Any model with a text label should not be composite and should not contain any elements.
      Specified by:
      getText in interface Model
      Returns:
      this is the optional text label for this model

    • getExpression

      public Expression getExpression()
      This returns an Expression representing the path this model exists at within the class schema. This should never be null for any model that is not empty.
      Specified by:
      getExpression in interface Model
      Returns:
      this returns the expression associated with this

    • getPrefix

      public String getPrefix()
      This is used to acquire the path prefix for the model. The path prefix is used when the model is transformed in to an XML structure. This ensures that the XML element created to represent the model contains the optional prefix.
      Specified by:
      getPrefix in interface Model
      Returns:
      this returns the prefix for this model

    • getName

      public String getName()
      This is used to return the name of the model. The name is must be a valid XML element name. It is used when a style is applied to a section as the model name must be styled.
      Specified by:
      getName in interface Model
      Returns:
      this returns the name of this model instance

    • getIndex

      public int getIndex()
      This method is used to return the index of the model. The index is the order that this model appears within the XML document. Having an index allows multiple models of the same name to be inserted in to a sorted collection.
      Specified by:
      getIndex in interface Model
      Returns:
      this is the index of this model instance

    • toString

      public String toString()
      For the purposes of debugging we provide a representation of the model in a string format. This will basically show the name of the model and the index it exists at.
      Overrides:
      toString in class Object
      Returns:
      this returns some details for the model