Class ElementArrayLabel

java.lang.Object
org.simpleframework.xml.core.TemplateLabel
org.simpleframework.xml.core.ElementArrayLabel
All Implemented Interfaces:
Label

class ElementArrayLabel extends TemplateLabel
The ElementArrayLabel represents a label that is used to represent an XML element array in a class schema. This element array label can be used to convert an XML node into an array of composite or primitive objects. If the array is of primitive types then the entry attribute must be specified so that the primitive values can be serialized in a structured manner.
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private boolean
    This is used to determine if the element is data.
    private Decorator
    This is the decorator that is associated with the element.
    private Introspector
    This contains the details of the annotated contact object.
    private String
    This is the name of the XML entry from the annotation.
    private Format
    This is used to style the elements associated with this.
    private ElementArray
    This references the annotation that the field uses.
    private String
    This is the name of the element for this label instance.
    private Expression
    This is the path that is used to represent this attribute.
    private boolean
    This is used to determine if the element is required.
    private Class
    This is the type of array this label will represent.
  • Constructor Summary

    Constructors
    Constructor
    Description
    ElementArrayLabel(Contact contact, ElementArray label, Format format)
    Constructor for the ElementArrayLabel object.
  • Method Summary

    Modifier and Type
    Method
    Description
    This acquires the annotation associated with this label.
    This is used to acquire the contact object for this label.
    This will create a Converter for transforming an XML element into an array of XML serializable objects.
    private Converter
    getConverter(Context context, String name)
    This will create a Converter for transforming an XML element into an array of XML serializable objects.
    This is used to acquire the Decorator for this.
    This is used to acquire the dependent type for the annotated array.
    getEmpty(Context context)
    This is used to provide a configured empty value used when the annotated value is null.
    This is used to either provide the entry value provided within the annotation or compute a entry value.
    This method is used to return an XPath expression that is used to represent the position of this label.
    This is used to acquire the name of the element or attribute that is used by the class schema.
    This is used to acquire the name of the element or attribute as taken from the annotation.
    This is used to acquire the path of the element or attribute that is used by the class schema.
    This acts as a convenience method used to determine the type of contact this represents.
    boolean
    This is used to determine whether the annotation requires it and its children to be written as a CDATA block.
    boolean
    This is used to determine whether the XML element is required.
    This is used to describe the annotation and method or field that this label represents.

    Methods inherited from class org.simpleframework.xml.core.TemplateLabel

    getKey, getLabel, getNames, getPaths, getType, isAttribute, isCollection, isInline, isText, isTextList, isUnion

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
  • Field Details

    • decorator

      private Decorator decorator
      This is the decorator that is associated with the element.
    • label

      private ElementArray label
      This references the annotation that the field uses.
    • detail

      private Introspector detail
      This contains the details of the annotated contact object.
    • path

      private Expression path
      This is the path that is used to represent this attribute.
    • format

      private Format format
      This is used to style the elements associated with this.
    • type

      private Class type
      This is the type of array this label will represent.
    • entry

      private String entry
      This is the name of the XML entry from the annotation.
    • name

      private String name
      This is the name of the element for this label instance.
    • required

      private boolean required
      This is used to determine if the element is required.
    • data

      private boolean data
      This is used to determine if the element is data.
  • Constructor Details

    • ElementArrayLabel

      public ElementArrayLabel(Contact contact, ElementArray label, Format format)
      Constructor for the ElementArrayLabel object. This creates a label object, which can be used to convert an element node to an array of XML serializable objects.
      Parameters:
      contact - this is the contact that this label represents
      label - the annotation that contains the schema details
      format - this is used to style the elements for this label
  • Method Details

    • getDecorator

      public Decorator getDecorator() throws Exception
      This is used to acquire the Decorator for this. 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.
      Returns:
      this returns the decorator associated with this
      Throws:
      Exception
    • getConverter

      public Converter getConverter(Context context) throws Exception
      This will create a Converter for transforming an XML element into an array of XML serializable objects. The XML schema class for these objects must present the element array annotation.
      Parameters:
      context - this is the context object used for serialization
      Returns:
      this returns the converter for creating a collection
      Throws:
      Exception
    • getConverter

      private Converter getConverter(Context context, String name) throws Exception
      This will create a Converter for transforming an XML element into an array of XML serializable objects. The XML schema class for these objects must present the element array annotation.
      Parameters:
      context - this is the context object used for serialization
      name - this is the name of the entry XML element to use
      Returns:
      this returns the converter for creating a collection
      Throws:
      Exception
    • getEmpty

      public Object getEmpty(Context context) throws Exception
      This is used to provide a configured empty value used when the annotated value is null. This ensures that XML can be created with required details regardless of whether values are null or not. It also provides a means for sensible default values.
      Parameters:
      context - this is the context object for the serialization
      Returns:
      this returns the string to use for default values
      Throws:
      Exception
    • getEntry

      public String getEntry() throws Exception
      This is used to either provide the entry value provided within the annotation or compute a entry value. If the entry string is not provided the the entry value is calculated as the type of primitive the object is as a simplified class name.
      Specified by:
      getEntry in interface Label
      Overrides:
      getEntry in class TemplateLabel
      Returns:
      this returns the name of the XML entry element used
      Throws:
      Exception
    • getName

      public String getName() throws Exception
      This is used to acquire the name of the element or attribute that is used by the class schema. The name is determined by checking for an override within the annotation. If it contains a name then that is used, if however the annotation does not specify a name the the field or method name is used instead.
      Returns:
      returns the name that is used for the XML property
      Throws:
      Exception
    • getPath

      public String getPath() throws Exception
      This is used to acquire the path of the element or attribute that is used by the class schema. The path is determined by acquiring the XPath expression and appending the name of the label to form a fully qualified path.
      Returns:
      returns the path that is used for the XML property
      Throws:
      Exception
    • getExpression

      public Expression getExpression() throws Exception
      This method is used to return an XPath expression that is used to represent the position of this label. If there is no XPath expression associated with this then an empty path is returned. This will never return a null expression.
      Returns:
      the XPath expression identifying the location
      Throws:
      Exception
    • getAnnotation

      public Annotation getAnnotation()
      This acquires the annotation associated with this label. This is typically the annotation acquired from the field or method. However, in the case of unions this will return the actual annotation within the union group that this represents.
      Returns:
      this returns the annotation that this represents
    • getDependent

      public Type getDependent()
      This is used to acquire the dependent type for the annotated array. This will simply return the type that the array is composed to hold. This must be a serializable type, that is, a type that is annotated with the Root class.
      Specified by:
      getDependent in interface Label
      Overrides:
      getDependent in class TemplateLabel
      Returns:
      this returns the component type for the array
    • getType

      public Class getType()
      This acts as a convenience method used to determine the type of contact this represents. This is used when an object is written to XML. It determines whether a class attribute is required within the serialized XML element, that is, if the class returned by this is different from the actual value of the object to be serialized then that type needs to be remembered.
      Returns:
      this returns the type of the contact class
    • getContact

      public Contact getContact()
      This is used to acquire the contact object for this label. The contact retrieved can be used to set any object or primitive that has been deserialized, and can also be used to acquire values to be serialized in the case of object persistence. All contacts that are retrieved from this method will be accessible.
      Returns:
      returns the contact that this label is representing
    • getOverride

      public String getOverride()
      This is used to acquire the name of the element or attribute as taken from the annotation. If the element or attribute explicitly specifies a name then that name is used for the XML element or attribute used. If however no overriding name is provided then the method or field is used for the name.
      Returns:
      returns the name of the annotation for the contact
    • isRequired

      public boolean isRequired()
      This is used to determine whether the XML element is required. This ensures that if an XML element is missing from a document that deserialization can continue. Also, in the process of serialization, if a value is null it does not need to be written to the resulting XML document.
      Returns:
      true if the label represents a some required data
    • isData

      public boolean isData()
      This is used to determine whether the annotation requires it and its children to be written as a CDATA block. This is done when a primitive or other such element requires a text value and that value needs to be encapsulated within a CDATA block.
      Returns:
      this returns true if the element requires CDATA
    • toString

      public String toString()
      This is used to describe the annotation and method or field that this label represents. This is used to provide error messages that can be used to debug issues that occur when processing a method. This will provide enough information such that the problem can be isolated correctly.
      Specified by:
      toString in interface Label
      Overrides:
      toString in class Object
      Returns:
      this returns a string representation of the label