Coverage Report - org.simpleframework.xml.core.Label
 
Classes in this File Line Coverage Branch Coverage Complexity
Label
N/A
N/A
1
 
 1  
 /*
 2  
  * Label.java July 2006
 3  
  *
 4  
  * Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
 5  
  *
 6  
  * Licensed under the Apache License, Version 2.0 (the "License");
 7  
  * you may not use this file except in compliance with the License.
 8  
  * You may obtain a copy of the License at
 9  
  *
 10  
  *     http://www.apache.org/licenses/LICENSE-2.0
 11  
  *
 12  
  * Unless required by applicable law or agreed to in writing, software
 13  
  * distributed under the License is distributed on an "AS IS" BASIS,
 14  
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
 15  
  * implied. See the License for the specific language governing 
 16  
  * permissions and limitations under the License.
 17  
  */
 18  
 
 19  
 package org.simpleframework.xml.core;
 20  
 
 21  
 import java.lang.annotation.Annotation;
 22  
 
 23  
 import org.simpleframework.xml.strategy.Type;
 24  
 
 25  
 /**
 26  
  * The <code>Label</code> interface is used to describe an reference to
 27  
  * a field annotated with an XML schema annotation. Because each field
 28  
  * and annotation is different, there are different ways in which the
 29  
  * annotation can be accessed. This provides a uniform means for 
 30  
  * accessing the field annotation details and the field properties.
 31  
  * <p>
 32  
  * This also exposes a <code>Converter</code> object, which is used to
 33  
  * convert an XML node into a property that can be assigned to the 
 34  
  * annotated field. Each converter returned is specific to the label
 35  
  * and knows, based on the annotation, how to serialize the field.
 36  
  * 
 37  
  * @author Niall Gallagher
 38  
  */
 39  
 interface Label {
 40  
      
 41  
    /**
 42  
     * This is used to acquire the <code>Decorator</code> for this.
 43  
     * A decorator is an object that adds various details to the
 44  
     * node without changing the overall structure of the node. For
 45  
     * example comments and namespaces can be added to the node with
 46  
     * a decorator as they do not affect the deserialization.
 47  
     * 
 48  
     * @return this returns the decorator associated with this
 49  
     */
 50  
    Decorator getDecorator() throws Exception;
 51  
 
 52  
    /**
 53  
     * This is used to acquire the <code>Type</code> that the type
 54  
     * provided is represented by. Typically this will return the
 55  
     * field or method represented by the label. However, in the 
 56  
     * case of unions this will provide an override type.
 57  
     * 
 58  
     * @param type this is the class to acquire the type for
 59  
     * 
 60  
     * @return this returns the type represented by this class
 61  
     */
 62  
    Type getType(Class type) throws Exception;   
 63  
    
 64  
    /**
 65  
     * This is used to acquire the <code>Label</code> that the type
 66  
     * provided is represented by. Typically this will return the
 67  
     * same instance. However, in the case of unions this will
 68  
     * look for an individual label to match the type provided.
 69  
     * 
 70  
     * @param type this is the type to acquire the label for
 71  
     * 
 72  
     * @return this returns the label represented by this type
 73  
     */
 74  
    Label getLabel(Class type) throws Exception;
 75  
 
 76  
    /**
 77  
     * This returns a <code>Collection</code> of element names. This
 78  
     * will typically contain both the name and path of the label. 
 79  
     * However, if this is a union it can contain many names and
 80  
     * paths. This method should never return null. 
 81  
     * 
 82  
     * @return this returns the names of each of the elements
 83  
     */
 84  
    String[] getNames() throws Exception; 
 85  
    
 86  
    /**
 87  
     * This returns a <code>Collection</code> of element paths. This
 88  
     * will typically contain only the path of the label, which is
 89  
     * composed using the <code>Path</code> annotation and the name
 90  
     * of the label. However, if this is a union it can contain many 
 91  
     * paths. This method should never return null.
 92  
     * 
 93  
     * @return this returns the names of each of the elements
 94  
     */
 95  
    String[] getPaths() throws Exception;
 96  
    
 97  
    /**
 98  
     * This is used to provide a configured empty value used when the
 99  
     * annotated value is null. This ensures that XML can be created
 100  
     * with required details regardless of whether values are null or
 101  
     * not. It also provides a means for sensible default values.
 102  
     * 
 103  
     * @param context this is the context object for the serialization
 104  
     * 
 105  
     * @return this returns the string to use for default values
 106  
     */
 107  
    Object getEmpty(Context context) throws Exception;
 108  
    
 109  
    /**
 110  
     * This method returns a <code>Converter</code> which can be used to
 111  
     * convert an XML node into an object value and vice versa. The 
 112  
     * converter requires only the context object in order to perform
 113  
     * serialization or deserialization of the provided XML node.
 114  
     * 
 115  
     * @param context this is the context object for the serialization
 116  
     * 
 117  
     * @return this returns an object that is used for conversion
 118  
     */
 119  
    Converter getConverter(Context context) throws Exception;
 120  
    
 121  
    /**
 122  
     * This is used to acquire the name of the element or attribute
 123  
     * that is used by the class schema. The name is determined by
 124  
     * checking for an override within the annotation. If it contains
 125  
     * a name then that is used, if however the annotation does not
 126  
     * specify a name the the field or method name is used instead.
 127  
     * 
 128  
     * @return returns the name that is used for the XML property
 129  
     */
 130  
    String getName() throws Exception;
 131  
    
 132  
    /**
 133  
     * This is used to acquire the path of the element or attribute
 134  
     * that is used by the class schema. The path is determined by
 135  
     * acquiring the XPath expression and appending the name of the
 136  
     * label to form a fully qualified path.
 137  
     * 
 138  
     * @return returns the path that is used for the XML property
 139  
     */
 140  
    String getPath() throws Exception;
 141  
    
 142  
    /**
 143  
     * This method is used to return an XPath expression that is 
 144  
     * used to represent the position of this label. If there is no
 145  
     * XPath expression associated with this then an empty path is
 146  
     * returned. This will never return a null expression.
 147  
     * 
 148  
     * @return the XPath expression identifying the location
 149  
     */
 150  
    Expression getExpression() throws Exception;
 151  
    
 152  
    /**
 153  
     * This returns the dependent type for the annotation. This type
 154  
     * is the type other than the annotated field or method type that
 155  
     * the label depends on. For the <code>ElementList</code> and 
 156  
     * the <code>ElementArray</code> this is the component type that
 157  
     * is deserialized individually and inserted into the container. 
 158  
     * 
 159  
     * @return this is the type that the annotation depends on
 160  
     */
 161  
    Type getDependent() throws Exception;
 162  
    
 163  
    /**
 164  
     * This is used to either provide the entry value provided within
 165  
     * the annotation or compute a entry value. If the entry string
 166  
     * is not provided the the entry value is calculated as the type
 167  
     * of primitive the object is as a simplified class name.
 168  
     * 
 169  
     * @return this returns the name of the XML entry element used 
 170  
     */
 171  
    String getEntry() throws Exception;
 172  
    
 173  
    /**
 174  
     * This is the key used to represent this label. The key is used
 175  
     * to store the parameter in hash containers. Typically the
 176  
     * key is generated from the paths associated with the label.
 177  
     * 
 178  
     * @return this is the key used to represent the label
 179  
     */
 180  
    Object getKey() throws Exception;
 181  
    
 182  
    /**
 183  
     * This acquires the annotation associated with this label. This
 184  
     * is typically the annotation acquired from the field or method.
 185  
     * However, in the case of unions this will return the actual
 186  
     * annotation within the union group that this represents.
 187  
     * 
 188  
     * @return this returns the annotation that this represents
 189  
     */
 190  
    Annotation getAnnotation();
 191  
    
 192  
    /**
 193  
     * This is used to acquire the contact object for this label. The 
 194  
     * contact retrieved can be used to set any object or primitive that
 195  
     * has been deserialized, and can also be used to acquire values to
 196  
     * be serialized in the case of object persistence. All contacts 
 197  
     * that are retrieved from this method will be accessible. 
 198  
     * 
 199  
     * @return returns the field that this label is representing
 200  
     */
 201  
    Contact getContact();
 202  
 
 203  
    /**
 204  
     * This acts as a convenience method used to determine the type of
 205  
     * the field this represents. This is used when an object is written
 206  
     * to XML. It determines whether a <code>class</code> attribute
 207  
     * is required within the serialized XML element, that is, if the
 208  
     * class returned by this is different from the actual value of the
 209  
     * object to be serialized then that type needs to be remembered.
 210  
     *  
 211  
     * @return this returns the type of the field class
 212  
     */
 213  
    Class getType();
 214  
    
 215  
    /**
 216  
     * This is used to acquire the name of the element or attribute
 217  
     * as taken from the annotation. If the element or attribute
 218  
     * explicitly specifies a name then that name is used for the
 219  
     * XML element or attribute used. If however no overriding name
 220  
     * is provided then the method or field is used for the name. 
 221  
     * 
 222  
     * @return returns the name of the annotation for the contact
 223  
     */
 224  
    String getOverride();
 225  
    
 226  
    /**
 227  
     * This is used to determine whether the annotation requires it
 228  
     * and its children to be written as a CDATA block. This is done
 229  
     * when a primitive or other such element requires a text value
 230  
     * and that value needs to be encapsulated within a CDATA block.
 231  
     * 
 232  
     * @return this returns true if the element requires CDATA
 233  
     */
 234  
    boolean isData();
 235  
    
 236  
    /**
 237  
     * Determines whether the XML attribute or element is required. 
 238  
     * This ensures that if an XML element is missing from a document
 239  
     * that deserialization can continue. Also, in the process of
 240  
     * serialization, if a value is null it does not need to be 
 241  
     * written to the resulting XML document.
 242  
     * 
 243  
     * @return true if the label represents a some required data
 244  
     */
 245  
    boolean isRequired();
 246  
    
 247  
    /**
 248  
     * This method is used to determine if the label represents an
 249  
     * attribute. This is used to style the name so that elements
 250  
     * are styled as elements and attributes are styled as required.
 251  
     * 
 252  
     * @return this is used to determine if this is an attribute
 253  
     */
 254  
    boolean isAttribute();
 255  
    
 256  
    /**
 257  
     * This is used to determine if the label is a collection. If the
 258  
     * label represents a collection then any original assignment to
 259  
     * the field or method can be written to without the need to 
 260  
     * create a new collection. This allows obscure collections to be
 261  
     * used and also allows initial entries to be maintained.
 262  
     * 
 263  
     * @return true if the label represents a collection value
 264  
     */
 265  
    boolean isCollection();
 266  
    
 267  
    /**
 268  
     * This is used to determine whether the label represents an
 269  
     * inline XML entity. The <code>ElementList</code> annotation
 270  
     * and the <code>Text</code> annotation represent inline 
 271  
     * items. This means that they contain no containing element
 272  
     * and so can not specify overrides or special attributes.
 273  
     * 
 274  
     * @return this returns true if the annotation is inline
 275  
     */
 276  
    boolean isInline();
 277  
    
 278  
    /**
 279  
     * This is used to determine if the label represents text. If
 280  
     * a label represents text it typically does not have a name,
 281  
     * instead the empty string represents the name. Also text
 282  
     * labels can not exist with other text labels, or elements.
 283  
     * 
 284  
     * @return this returns true if this label represents text
 285  
     */
 286  
    boolean isText();
 287  
    
 288  
    /**
 289  
     * This is used to determine if an annotated list is a text 
 290  
     * list. A text list is a list of elements that also accepts
 291  
     * free text. Typically this will be an element list union that
 292  
     * will allow unstructured XML such as XHTML to be parsed.
 293  
     * 
 294  
     * @return returns true if the label represents a text list
 295  
     */
 296  
    boolean isTextList();
 297  
    
 298  
    /**
 299  
     * This is used to determine if this label is a union. If this
 300  
     * is true then this label represents a number of labels and
 301  
     * is simply a wrapper for these labels. 
 302  
     * 
 303  
     * @return this returns true if the label represents a union
 304  
     */
 305  
    boolean isUnion();
 306  
    
 307  
    /**
 308  
     * This is used to describe the annotation and method or field
 309  
     * that this label represents. This is used to provide error
 310  
     * messages that can be used to debug issues that occur when
 311  
     * processing a method. This should provide enough information
 312  
     * such that the problem can be isolated correctly. 
 313  
     * 
 314  
     * @return this returns a string representation of the label
 315  
     */
 316  
    String toString();
 317  
 }