Class ElementMapUnionLabel

  • All Implemented Interfaces:
    Label

    class ElementMapUnionLabel
    extends TemplateLabel
    The ElementMapUnionLabel is an adapter for an internal label. Each annotation within the union can be acquired by type so that deserialization can dynamically switch the converter used. Each union label can be used in place of any other, this means that regardless of which union is matched it can be used.

    Each instance of this Label is given the union and the primary label it represents. This allows the label extract each other label within the union group. The Converter created by this can therefore acquire any label instance required.

    See Also:
    ElementMapUnion
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private Contact contact
      This is the contact that this label is associated with.
      private GroupExtractor extractor
      This is used to extract the individual unions in the group.
      private Label label
      This is the label that this acts as an adapter to.
      private Expression path
      This is the expression that is associated with this label.
    • 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 method returns a Converter which can be used to convert an XML node into an object value and vice versa.
      Decorator getDecorator()
      This is used to acquire the Decorator for this.
      Type getDependent()
      This returns the dependent type for the annotation.
      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.
      Label getLabel​(java.lang.Class type)
      This is used to acquire the Label that the type provided is represented by.
      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[] getNames()
      This returns a Collection of element names.
      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.String[] getPaths()
      This returns a Collection of element paths.
      java.lang.Class getType()
      This acts as a convenience method used to determine the type of the field this represents.
      Type getType​(java.lang.Class type)
      This is used to acquire the Type that the type provided is represented by.
      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 label represents an inline XML entity.
      boolean isRequired()
      Determines whether the XML attribute or element is required.
      boolean isUnion()
      This is used to determine if this label is a union.
      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

      • extractor

        private GroupExtractor extractor
        This is used to extract the individual unions in the group.
      • path

        private Expression path
        This is the expression that is associated with this label.
      • contact

        private Contact contact
        This is the contact that this label is associated with.
      • label

        private Label label
        This is the label that this acts as an adapter to.
    • Constructor Detail

      • ElementMapUnionLabel

        public ElementMapUnionLabel​(Contact contact,
                                    ElementMapUnion union,
                                    ElementMap element,
                                    Format format)
                             throws java.lang.Exception
        Constructor for the ElementMapUnionLabel object. This is given the union this represents as well as the individual element it will act as an adapter for. This allows the union label to acquire any other label within the group.
        Parameters:
        contact - this is the contact associated with the union
        union - this is the union annotation this represents
        element - this is the individual annotation used
        format - this is the format used to style this union
        Throws:
        java.lang.Exception
    • Method Detail

      • isUnion

        public boolean isUnion()
        This is used to determine if this label is a union. If this is true then this label represents a number of labels and is simply a wrapper for these labels.
        Specified by:
        isUnion in interface Label
        Overrides:
        isUnion in class TemplateLabel
        Returns:
        this returns true if the label represents a union
      • 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 field that this label is representing
      • 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 Type getType​(java.lang.Class type)
        This is used to acquire the Type that the type provided is represented by. Typically this will return the field or method represented by the label. However, in the case of unions this will provide an override type.
        Specified by:
        getType in interface Label
        Overrides:
        getType in class TemplateLabel
        Parameters:
        type - this is the class to acquire the type for
        Returns:
        this returns the type represented by this class
      • getLabel

        public Label getLabel​(java.lang.Class type)
        This is used to acquire the Label that the type provided is represented by. Typically this will return the same instance. However, in the case of unions this will look for an individual label to match the type provided.
        Specified by:
        getLabel in interface Label
        Overrides:
        getLabel in class TemplateLabel
        Parameters:
        type - this is the type to acquire the label for
        Returns:
        this returns the label represented by this type
      • getConverter

        public Converter getConverter​(Context context)
                               throws java.lang.Exception
        This method returns a Converter which can be used to convert an XML node into an object value and vice versa. The converter requires only the context object in order to perform serialization or deserialization of the provided XML node.
        Parameters:
        context - this is the context object for the serialization
        Returns:
        this returns an object that is used for conversion
        Throws:
        java.lang.Exception
      • getNames

        public java.lang.String[] getNames()
                                    throws java.lang.Exception
        This returns a Collection of element names. This will typically contain both the name and path of the label. However, if this is a union it can contain many names and paths. This method should never return null.
        Specified by:
        getNames in interface Label
        Overrides:
        getNames in class TemplateLabel
        Returns:
        this returns the names of each of the elements
        Throws:
        java.lang.Exception
      • getPaths

        public java.lang.String[] getPaths()
                                    throws java.lang.Exception
        This returns a Collection of element paths. This will typically contain only the path of the label, which is composed using the Path annotation and the name of the label. However, if this is a union it can contain many paths. This method should never return null.
        Specified by:
        getPaths in interface Label
        Overrides:
        getPaths in class TemplateLabel
        Returns:
        this returns the names of each of the elements
        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
      • 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
      • getDependent

        public Type getDependent()
                          throws java.lang.Exception
        This returns the dependent type for the annotation. This type is the type other than the annotated field or method type that the label depends on. For the ElementList and the ElementArray this is the component type that is deserialized individually and inserted into the container.
        Specified by:
        getDependent in interface Label
        Overrides:
        getDependent in class TemplateLabel
        Returns:
        this is the type that the annotation depends on
        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
      • 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
      • getType

        public java.lang.Class getType()
        This acts as a convenience method used to determine the type of the field 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 field class
      • 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
      • 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
      • isInline

        public boolean isInline()
        This is used to determine whether the label represents an inline XML entity. The ElementList annotation and the Text annotation represent inline items. This means that they contain no containing element and so can not specify overrides or special attributes.
        Specified by:
        isInline in interface Label
        Overrides:
        isInline in class TemplateLabel
        Returns:
        this returns true if the annotation is inline
      • isRequired

        public boolean isRequired()
        Determines whether the XML attribute or 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
      • 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