Coverage Report - org.simpleframework.xml.core.Context
 
Classes in this File Line Coverage Branch Coverage Complexity
Context
N/A
N/A
1
 
 1  
 /*
 2  
  * Context.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 org.simpleframework.xml.Version;
 22  
 import org.simpleframework.xml.strategy.Type;
 23  
 import org.simpleframework.xml.strategy.Value;
 24  
 import org.simpleframework.xml.stream.InputNode;
 25  
 import org.simpleframework.xml.stream.OutputNode;
 26  
 import org.simpleframework.xml.stream.Style;
 27  
 
 28  
 /**
 29  
  * The <code>Context</code> object acts as a contextual object that is
 30  
  * used to store all information regarding an instance of serialization
 31  
  * or deserialization. This maintains the <code>Strategy</code> as
 32  
  * well as the <code>Filter</code> used to replace template variables.
 33  
  * When serialization and deserialization are performed the source is
 34  
  * required as it acts as a factory for objects used in the process.
 35  
  * <p>
 36  
  * For serialization the source object is required as a factory for
 37  
  * <code>Schema</code> objects, which are used to visit each field 
 38  
  * in the class that can be serialized. Also this can be used to get
 39  
  * any data entered into the session <code>Map</code> object.
 40  
  * <p>
 41  
  * When deserializing the source object provides the contextual data
 42  
  * used to replace template variables extracted from the XML source.
 43  
  * This is performed using the <code>Filter</code> object. Also, as 
 44  
  * in serialization it acts as a factory for the <code>Schema</code> 
 45  
  * objects used to examine the serializable fields of an object.
 46  
  * 
 47  
  * @author Niall Gallagher
 48  
  * 
 49  
  * @see org.simpleframework.xml.strategy.Strategy
 50  
  */ 
 51  
 interface Context {
 52  
    
 53  
    /**
 54  
     * This is used to determine if the deserialization mode is strict
 55  
     * or not. If this is not strict then deserialization will be done
 56  
     * in such a way that additional elements and attributes can be
 57  
     * ignored. This allows external XML formats to be used without 
 58  
     * having to match the object structure to the XML fully.
 59  
     * 
 60  
     * @return this returns true if the deserialization is strict
 61  
     */
 62  
    boolean isStrict();
 63  
    
 64  
    /**
 65  
     * This is used to acquire the <code>Style</code> for the format.
 66  
     * If no style has been set a default style is used, which does 
 67  
     * not modify the attributes and elements that are used to build
 68  
     * the resulting XML document.
 69  
     * 
 70  
     * @return this returns the style used for this format object
 71  
     */
 72  
    Style getStyle();
 73  
    
 74  
    /**
 75  
     * This is used to acquire the <code>Session</code> object that 
 76  
     * is used to store the values used within the serialization
 77  
     * process. This provides the internal map that is passed to all
 78  
     * of the call back methods so that is can be populated.
 79  
     * 
 80  
     * @return this returns the session that is used by this source
 81  
     */
 82  
    Session getSession();
 83  
    
 84  
    /**
 85  
     * This is used to acquire the <code>Support</code> object.
 86  
     * The support object is used to translate strings to and from
 87  
     * their object representations and is also used to convert the
 88  
     * strings to their template values. This is the single source 
 89  
     * of translation for all of the strings encountered.
 90  
     * 
 91  
     * @return this returns the support used by the context
 92  
     */
 93  
    Support getSupport();
 94  
    
 95  
    /**
 96  
     * This is used to determine if the type specified is a floating
 97  
     * point type. Types that are floating point are the double and
 98  
     * float primitives as well as the java types for this primitives.
 99  
     * 
 100  
     * @param type this is the type to determine if it is a float
 101  
     * 
 102  
     * @return this returns true if the type is a floating point
 103  
     */
 104  
    boolean isFloat(Class type) throws Exception;
 105  
    
 106  
    /**
 107  
     * This is used to determine if the type specified is a floating
 108  
     * point type. Types that are floating point are the double and
 109  
     * float primitives as well as the java types for this primitives.
 110  
     * 
 111  
     * @param type this is the type to determine if it is a float
 112  
     * 
 113  
     * @return this returns true if the type is a floating point
 114  
     */
 115  
    boolean isFloat(Type type) throws Exception;
 116  
    
 117  
    /**
 118  
     * This is used to determine whether the scanned class represents
 119  
     * a primitive type. A primitive type is a type that contains no
 120  
     * XML annotations and so cannot be serialized with an XML form.
 121  
     * Instead primitives a serialized using transformations.
 122  
     *
 123  
     * @param type this is the type to determine if it is primitive
 124  
     * 
 125  
     * @return this returns true if no XML annotations were found
 126  
     */
 127  
    boolean isPrimitive(Class type) throws Exception;  
 128  
    
 129  
    /**
 130  
     * This is used to determine whether the scanned type represents
 131  
     * a primitive type. A primitive type is a type that contains no
 132  
     * XML annotations and so cannot be serialized with an XML form.
 133  
     * Instead primitives a serialized using transformations.
 134  
     *
 135  
     * @param type this is the type to determine if it is primitive
 136  
     * 
 137  
     * @return this returns true if no XML annotations were found
 138  
     */
 139  
    boolean isPrimitive(Type type) throws Exception;   
 140  
    
 141  
    /**
 142  
     * This will create an <code>Instance</code> that can be used
 143  
     * to instantiate objects of the specified class. This leverages
 144  
     * an internal constructor cache to ensure creation is quicker.
 145  
     * 
 146  
     * @param value this contains information on the object instance
 147  
     * 
 148  
     * @return this will return an object for instantiating objects
 149  
     */
 150  
    Instance getInstance(Value value);
 151  
 
 152  
    /**
 153  
     * This will create an <code>Instance</code> that can be used
 154  
     * to instantiate objects of the specified class. This leverages
 155  
     * an internal constructor cache to ensure creation is quicker.
 156  
     * 
 157  
     * @param type this is the type that is to be instantiated
 158  
     * 
 159  
     * @return this will return an object for instantiating objects
 160  
     */
 161  
    Instance getInstance(Class type);
 162  
    
 163  
    /**
 164  
     * This is used to acquire the name of the specified type using
 165  
     * the <code>Root</code> annotation for the class. This will 
 166  
     * use either the name explicitly provided by the annotation or
 167  
     * it will use the name of the class that the annotation was
 168  
     * placed on if there is no explicit name for the root.
 169  
     * 
 170  
     * @param type this is the type to acquire the root name for
 171  
     * 
 172  
     * @return this returns the name of the type from the root
 173  
     * 
 174  
     * @throws Exception if the class contains an illegal schema
 175  
     */
 176  
    String getName(Class type) throws Exception;
 177  
    
 178  
    /**
 179  
     * This is used to acquire the <code>Caller</code> object. This
 180  
     * is used to call the callback methods within the object. If the
 181  
     * object contains no callback methods then this will return an
 182  
     * object that does not invoke any methods that are invoked. 
 183  
     * 
 184  
     * @param type this is the type to acquire the caller for
 185  
     * 
 186  
     * @return this returns the caller for the specified type
 187  
     */
 188  
    Caller getCaller(Class type) throws Exception;
 189  
    
 190  
    /**
 191  
     * This returns the version for the type specified. The version is
 192  
     * used to determine how the deserialization process is performed.
 193  
     * If the version of the type is different from the version for
 194  
     * the XML document, then deserialization is done in a best effort.
 195  
     * 
 196  
     * @param type this is the type to acquire the version for
 197  
     * 
 198  
     * @return the version that has been set for this XML schema class
 199  
     */
 200  
    Version getVersion(Class type) throws Exception;
 201  
    
 202  
    /**
 203  
     * This will acquire the <code>Decorator</code> for the type.
 204  
     * A decorator is an object that adds various details to the
 205  
     * node without changing the overall structure of the node. For
 206  
     * example comments and namespaces can be added to the node with
 207  
     * a decorator as they do not affect the deserialization.
 208  
     * 
 209  
     * @param type this is the type to acquire the decorator for 
 210  
     *
 211  
     * @return this returns the decorator associated with this
 212  
     */
 213  
    Decorator getDecorator(Class type) throws Exception;
 214  
 
 215  
    /**
 216  
     * This creates a <code>Schema</code> object that can be used to
 217  
     * examine the fields within the XML class schema. The schema
 218  
     * maintains information when a field from within the schema is
 219  
     * visited, this allows the serialization and deserialization
 220  
     * process to determine if all required XML annotations are used.
 221  
     * 
 222  
     * @param type the schema class the schema is created for
 223  
     * 
 224  
     * @return a new schema that can track visits within the schema
 225  
     * 
 226  
     * @throws Exception if the class contains an illegal schema 
 227  
     */   
 228  
    Schema getSchema(Class type) throws Exception;
 229  
    
 230  
    /**
 231  
     * This is used to resolve and load a class for the given element.
 232  
     * The class should be of the same type or a subclass of the class
 233  
     * specified. It can be resolved using the details within the
 234  
     * provided XML element, if the details used do not represent any
 235  
     * serializable values they should be removed so as not to disrupt
 236  
     * the deserialization process. For example the default strategy
 237  
     * removes all "class" attributes from the given elements.
 238  
     * 
 239  
     * @param type this is the type of the root element expected
 240  
     * @param node this is the element used to resolve an override
 241  
     * 
 242  
     * @return returns the type that should be used for the object
 243  
     * 
 244  
     * @throws Exception thrown if the class cannot be resolved  
 245  
     */
 246  
    Value getOverride(Type type, InputNode node) throws Exception;
 247  
 
 248  
    /**    
 249  
     * This is used to attach elements or attributes to the given 
 250  
     * element during the serialization process. This method allows
 251  
     * the strategy to augment the XML document so that it can be
 252  
     * deserialized using a similar strategy. For example the 
 253  
     * default strategy adds a "class" attribute to the element.
 254  
     * 
 255  
     * @param type this is the field type for the associated value 
 256  
     * @param value this is the instance variable being serialized
 257  
     * @param node this is the element used to represent the value
 258  
     * 
 259  
     * @return this returns true if serialization has complete
 260  
     * 
 261  
     * @throws Exception thrown if the details cannot be set
 262  
     */
 263  
    boolean setOverride(Type type, Object value, OutputNode node) throws Exception;
 264  
    
 265  
    /**
 266  
     * This is used to determine the type of an object given the 
 267  
     * source instance. To provide a best match approach this will
 268  
     * first attempt to get the value for the actual instance, if
 269  
     * however the instance is null the type is delegated to.
 270  
     * 
 271  
     * @param type this is the type used in the serialization
 272  
     * @param value this is the source instance being used
 273  
     * 
 274  
     * @return the best match given the criteria
 275  
     */
 276  
    Class getType(Type type, Object value);
 277  
 
 278  
    /**
 279  
     * This is used to acquire the attribute mapped to the specified
 280  
     * key. In order for this to return a value it must have been
 281  
     * previously placed into the context as it is empty by default.
 282  
     * 
 283  
     * @param key this is the name of the attribute to retrieve
 284  
     *
 285  
     * @return this returns the value mapped to the specified key
 286  
     */     
 287  
    Object getAttribute(Object key);
 288  
    
 289  
    /**
 290  
     * Replaces any template variables within the provided string. 
 291  
     * This is used in the deserialization process to replace 
 292  
     * variables with system properties, environment variables, or
 293  
     * used specified mappings. If a template variable does not have
 294  
     * a mapping from the <code>Filter</code> is is left unchanged.  
 295  
     * 
 296  
     * @param text this is processed by the template engine object
 297  
     * 
 298  
     * @return this returns the text will all variables replaced
 299  
     */
 300  
    String getProperty(String text);
 301  
 }