Coverage Report - org.simpleframework.xml.core.Scanner
 
Classes in this File Line Coverage Branch Coverage Complexity
Scanner
N/A
N/A
1
 
 1  
 /*
 2  
  * Scanner.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.util.List;
 22  
 
 23  
 import org.simpleframework.xml.Order;
 24  
 import org.simpleframework.xml.Version;
 25  
 
 26  
 /**
 27  
  * The <code>Scanner</code> object performs the reflective inspection
 28  
  * of a class and builds a map of attributes and elements for each
 29  
  * annotated field. This acts as a cachable container for reflection
 30  
  * actions performed on a specific type. When scanning the provided
 31  
  * class this inserts the scanned field as a <code>Label</code> in to
 32  
  * a map so that it can be retrieved by name. Annotations classified
 33  
  * as attributes have the <code>Attribute</code> annotation, all other
 34  
  * annotated fields are stored as elements.
 35  
  * 
 36  
  * @author Niall Gallagher
 37  
  * 
 38  
  * @see org.simpleframework.xml.core.Schema
 39  
  */ 
 40  
 interface Scanner extends Policy {
 41  
    
 42  
    /**
 43  
     * This is used to acquire the default signature for the class. 
 44  
     * The default signature is the signature for the no argument
 45  
     * constructor for the type. If there is no default constructor
 46  
     * for the type then this will return null.
 47  
     * 
 48  
     * @return this returns the default signature if it exists
 49  
     */
 50  
    Signature getSignature();
 51  
    
 52  
    /**
 53  
     * This returns the signatures for the type. All constructors are
 54  
     * represented as a signature and returned. More signatures than
 55  
     * constructors will be returned if a constructor is annotated 
 56  
     * with a union annotation.
 57  
     *
 58  
     * @return this returns the list of signatures for the type
 59  
     */
 60  
    List<Signature> getSignatures();
 61  
    
 62  
    /**
 63  
     * This returns a map of all parameters that exist. This is used
 64  
     * to validate all the parameters against the field and method
 65  
     * annotations that exist within the class. 
 66  
     * 
 67  
     * @return this returns a map of all parameters within the type
 68  
     */
 69  
    ParameterMap getParameters();
 70  
    
 71  
    /**
 72  
     * This is used to acquire the instantiator for the type. This is
 73  
     * used to create object instances based on the constructors that
 74  
     * have been annotated. If no constructors have been annotated
 75  
     * then this can be used to create default no argument instances.
 76  
     * 
 77  
     * @return this instantiator responsible for creating instances
 78  
     */
 79  
    Instantiator getInstantiator();
 80  
 
 81  
    /**
 82  
     * This is used to acquire the type that this scanner scans for
 83  
     * annotations to be used in a schema. Exposing the class that
 84  
     * this represents allows the schema it creates to be known.
 85  
     * 
 86  
     * @return this is the type that this creator will represent
 87  
     */
 88  
    Class getType();
 89  
    
 90  
    /**
 91  
     * This is used to acquire the <code>Decorator</code> for this.
 92  
     * A decorator is an object that adds various details to the
 93  
     * node without changing the overall structure of the node. For
 94  
     * example comments and namespaces can be added to the node with
 95  
     * a decorator as they do not affect the deserialization.
 96  
     * 
 97  
     * @return this returns the decorator associated with this
 98  
     */
 99  
    Decorator getDecorator();
 100  
    
 101  
    /**
 102  
     * This method is used to return the <code>Caller</code> for this
 103  
     * class. The caller is a means to deliver invocations to the
 104  
     * object for the persister callback methods. It aggregates all of
 105  
     * the persister callback methods in to a single object.
 106  
     * 
 107  
     * @return this returns a caller used for delivering callbacks
 108  
     */
 109  
    Caller getCaller(Context context);
 110  
 
 111  
    /**
 112  
     * This is used to create a <code>Section</code> given the context
 113  
     * used for serialization. A section is an XML structure that 
 114  
     * contains all the elements and attributes defined for the class.
 115  
     * Each section is a tree like structure defining exactly where
 116  
     * each attribute an element is located within the source XML.
 117  
     * 
 118  
     * @return this will return a section for serialization
 119  
     */
 120  
    Section getSection();
 121  
    
 122  
    /**
 123  
     * This is the <code>Version</code> for the scanned class. It 
 124  
     * allows the deserialization process to be configured such that
 125  
     * if the version is different from the schema class none of
 126  
     * the fields and methods are required and unmatched elements
 127  
     * and attributes will be ignored.
 128  
     * 
 129  
     * @return this returns the version of the class that is scanned
 130  
     */
 131  
    Version getRevision();
 132  
    
 133  
    /**
 134  
     * This is used to acquire the <code>Order</code> annotation for
 135  
     * the class schema. The order annotation defines the order that
 136  
     * the elements and attributes should appear within the document.
 137  
     * Providing order in this manner makes the resulting XML more
 138  
     * predictable. If no order is provided, appearance is random.
 139  
     * 
 140  
     * @return this returns the order, if any, defined for the class
 141  
     */
 142  
    Order getOrder();
 143  
    
 144  
    /**
 145  
     * This returns the <code>Label</code> that represents the version
 146  
     * annotation for the scanned class. Only a single version can
 147  
     * exist within the class if more than one exists an exception is
 148  
     * thrown. This will read only floating point types such as double.
 149  
     * 
 150  
     * @return this returns the label used for reading the version
 151  
     */
 152  
    Label getVersion();
 153  
    
 154  
    /**
 155  
     * This returns the <code>Label</code> that represents the text
 156  
     * annotation for the scanned class. Only a single text annotation
 157  
     * can be used per class, so this returns only a single label
 158  
     * rather than a <code>LabelMap</code> object. Also if this is
 159  
     * not null then the elements label map must be empty.
 160  
     * 
 161  
     * @return this returns the text label for the scanned class
 162  
     */
 163  
    Label getText();
 164  
    
 165  
    /**
 166  
     * This returns the name of the class processed by this scanner.
 167  
     * The name is either the name as specified in the last found
 168  
     * <code>Root</code> annotation, or if a name was not specified
 169  
     * within the discovered root then the Java Bean class name of
 170  
     * the last class annotated with a root annotation.
 171  
     * 
 172  
     * @return this returns the name of the object being scanned
 173  
     */
 174  
    String getName();
 175  
 
 176  
    /**
 177  
     * This method is used to retrieve the schema class commit method
 178  
     * during the deserialization process. The commit method must be
 179  
     * marked with the <code>Commit</code> annotation so that when the
 180  
     * object is deserialized the persister has a chance to invoke the
 181  
     * method so that the object can build further data structures.
 182  
     * 
 183  
     * @return this returns the commit method for the schema class
 184  
     */
 185  
    Function getCommit();
 186  
 
 187  
    /**
 188  
     * This method is used to retrieve the schema class validation
 189  
     * method during the deserialization process. The validation method
 190  
     * must be marked with the <code>Validate</code> annotation so that
 191  
     * when the object is deserialized the persister has a chance to 
 192  
     * invoke that method so that object can validate its field values.
 193  
     * 
 194  
     * @return this returns the validate method for the schema class
 195  
     */   
 196  
    Function getValidate();
 197  
    
 198  
    /**
 199  
     * This method is used to retrieve the schema class persistence
 200  
     * method. This is invoked during the serialization process to
 201  
     * get the object a chance to perform an nessecary preparation
 202  
     * before the serialization of the object proceeds. The persist
 203  
     * method must be marked with the <code>Persist</code> annotation.
 204  
     * 
 205  
     * @return this returns the persist method for the schema class
 206  
     */
 207  
    Function getPersist();
 208  
 
 209  
    /**
 210  
     * This method is used to retrieve the schema class completion
 211  
     * method. This is invoked after the serialization process has
 212  
     * completed and gives the object a chance to restore its state
 213  
     * if the persist method required some alteration or locking.
 214  
     * This is marked with the <code>Complete</code> annotation.
 215  
     * 
 216  
     * @return returns the complete method for the schema class
 217  
     */   
 218  
    Function getComplete();
 219  
    
 220  
    /**
 221  
     * This method is used to retrieve the schema class replacement
 222  
     * method. The replacement method is used to substitute an object
 223  
     * that has been deserialized with another object. This allows
 224  
     * a seamless delegation mechanism to be implemented. This is
 225  
     * marked with the <code>Replace</code> annotation. 
 226  
     * 
 227  
     * @return returns the replace method for the schema class
 228  
     */
 229  
    Function getReplace();
 230  
    
 231  
    /**
 232  
     * This method is used to retrieve the schema class replacement
 233  
     * method. The replacement method is used to substitute an object
 234  
     * that has been deserialized with another object. This allows
 235  
     * a seamless delegation mechanism to be implemented. This is
 236  
     * marked with the <code>Replace</code> annotation. 
 237  
     * 
 238  
     * @return returns the replace method for the schema class
 239  
     */
 240  
    Function getResolve();
 241  
 
 242  
    /**
 243  
     * This is used to determine whether the scanned class represents
 244  
     * a primitive type. A primitive type is a type that contains no
 245  
     * XML annotations and so cannot be serialized with an XML form.
 246  
     * Instead primitives a serialized using transformations.
 247  
     * 
 248  
     * @return this returns true if no XML annotations were found
 249  
     */
 250  
    boolean isPrimitive();
 251  
    
 252  
    /**
 253  
     * This is used to determine whether the scanned class represents
 254  
     * a primitive type. A primitive type is a type that contains no
 255  
     * XML annotations and so cannot be serialized with an XML form.
 256  
     * Instead primitives a serialized using transformations.
 257  
     * 
 258  
     * @return this returns true if no XML annotations were found
 259  
     */
 260  
    boolean isEmpty();
 261  
    
 262  
    /**
 263  
     * This method is used to determine whether strict mappings are
 264  
     * required. Strict mapping means that all labels in the class
 265  
     * schema must match the XML elements and attributes in the
 266  
     * source XML document. When strict mapping is disabled, then
 267  
     * XML elements and attributes that do not exist in the schema
 268  
     * class will be ignored without breaking the parser.
 269  
     *
 270  
     * @return true if strict parsing is enabled, false otherwise
 271  
     */ 
 272  
    boolean isStrict();
 273  
 }
 274