Class ElementListLabel

  • All Implemented Interfaces:
    Label

    class ElementListLabel
    extends TemplateLabel
    The ElementListLabel represents a label that is used to represent an XML element list in a class schema. This element list label can be used to convert an XML node into a collection of composite objects. Each element converted with the converter this creates must be an XML serializable element.
    See Also:
    ElementList
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private Expression cache
      This is a cache of the expression for this element list.
      private boolean data
      This is used to determine if the attribute is data.
      private Decorator decorator
      This is the decorator that is associated with the element.
      private Introspector detail
      This contains the details of the annotated contact object.
      private java.lang.String entry
      This is the name of the XML entry from the annotation.
      private Format format
      This is the format used to style the elements in the list.
      private boolean inline
      This is used to determine if the attribute is inline.
      private java.lang.Class item
      Represents the type of objects this list will hold.
      private ElementList label
      This references the annotation that the field uses.
      private java.lang.String name
      This is the name of the XML element from the annotation.
      private java.lang.String override
      This is the name of the element for this label instance.
      private java.lang.String path
      This is the path of the XML entry from the annotation.
      private boolean required
      This is used to determine if the attribute is required.
      private java.lang.Class type
      This is the type of collection this list will instantiate.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.annotation.Annotation getAnnotation()
      This acquires the annotation associated with this label.
      Contact getContact()
      This is used to acquire the contact object for this label.
      Converter getConverter​(Context context)
      This will create a Converter for transforming an XML element into a collection of XML serializable objects.
      private Converter getConverter​(Context context, java.lang.String name)
      This will create a Converter for transforming an XML element into a collection of XML serializable objects.
      Decorator getDecorator()
      This is used to acquire the Decorator for this.
      Type getDependent()
      This is used to acquire the dependent type for the annotated list.
      java.lang.Object getEmpty​(Context context)
      This is used to provide a configured empty value used when the annotated value is null.
      java.lang.String getEntry()
      This is used to either provide the entry value provided within the annotation or compute a entry value.
      Expression getExpression()
      This method is used to return an XPath expression that is used to represent the position of this label.
      private Converter getInlineConverter​(Context context, java.lang.String name)
      This will create a Converter for transforming an XML element into a collection of XML serializable objects.
      java.lang.String getName()
      This is used to acquire the name of the element or attribute that is used by the class schema.
      java.lang.String getOverride()
      This is used to acquire the name of the element or attribute as taken from the annotation.
      java.lang.String getPath()
      This is used to acquire the path of the element or attribute that is used by the class schema.
      java.lang.Class getType()
      This acts as a convenience method used to determine the type of contact this represents.
      boolean isCollection()
      This is used to determine if the label is a collection.
      boolean isData()
      This is used to determine whether the annotation requires it and its children to be written as a CDATA block.
      boolean isInline()
      This is used to determine whether the list has been specified as inline.
      boolean isRequired()
      This is used to determine whether the XML element is required.
      java.lang.String toString()
      This is used to describe the annotation and method or field that this label represents.
      • Methods inherited from class java.lang.Object

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

      • decorator

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

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

        private ElementList label
        This references the annotation that the field uses.
      • cache

        private Expression cache
        This is a cache of the expression for this element list.
      • format

        private Format format
        This is the format used to style the elements in the list.
      • override

        private java.lang.String override
        This is the name of the element for this label instance.
      • entry

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

        private java.lang.String name
        This is the name of the XML element from the annotation.
      • path

        private java.lang.String path
        This is the path of the XML entry from the annotation.
      • type

        private java.lang.Class type
        This is the type of collection this list will instantiate.
      • item

        private java.lang.Class item
        Represents the type of objects this list will hold.
      • required

        private boolean required
        This is used to determine if the attribute is required.
      • inline

        private boolean inline
        This is used to determine if the attribute is inline.
      • data

        private boolean data
        This is used to determine if the attribute is data.
    • Constructor Detail

      • ElementListLabel

        public ElementListLabel​(Contact contact,
                                ElementList label,
                                Format format)
        Constructor for the ElementListLabel object. This creates a label object, which can be used to convert an XML node to a Collection 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 in the list
    • Method Detail

      • getDecorator

        public Decorator getDecorator()
                               throws java.lang.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:
        java.lang.Exception
      • getConverter

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

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

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

        public java.lang.Object getEmpty​(Context context)
                                  throws java.lang.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:
        java.lang.Exception
      • getDependent

        public Type getDependent()
                          throws java.lang.Exception
        This is used to acquire the dependent type for the annotated list. This will simply return the type that the collection 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 collection
        Throws:
        java.lang.Exception
      • getEntry

        public java.lang.String getEntry()
                                  throws java.lang.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:
        java.lang.Exception
      • getName

        public java.lang.String getName()
                                 throws java.lang.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:
        java.lang.Exception
      • getPath

        public java.lang.String getPath()
                                 throws java.lang.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:
        java.lang.Exception
      • getExpression

        public Expression getExpression()
                                 throws java.lang.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:
        java.lang.Exception
      • getAnnotation

        public java.lang.annotation.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
      • getType

        public java.lang.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 java.lang.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
      • 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:
        currently the element list does not require CDATA
      • isCollection

        public boolean isCollection()
        This is used to determine if the label is a collection. If the label represents a collection then any original assignment to the field or method can be written to without the need to create a new collection. This allows obscure collections to be used and also allows initial entries to be maintained.
        Specified by:
        isCollection in interface Label
        Overrides:
        isCollection in class TemplateLabel
        Returns:
        true if the label represents a collection value
      • 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
      • isInline

        public boolean isInline()
        This is used to determine whether the list has been specified as inline. If the list is inline then no overrides are needed and the outer XML element for the list is not used.
        Specified by:
        isInline in interface Label
        Overrides:
        isInline in class TemplateLabel
        Returns:
        this returns whether the annotation is inline
      • toString

        public java.lang.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 java.lang.Object
        Returns:
        this returns a string representation of the label