Coverage Report - org.simpleframework.xml.core.Contact
 
Classes in this File Line Coverage Branch Coverage Complexity
Contact
N/A
N/A
1
 
 1  
 /*
 2  
  * Contact.java April 2007
 3  
  *
 4  
  * Copyright (C) 2007, 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>Contact</code> interface is used to provide a point of
 27  
  * contact with an object. Typically this will be used to get and
 28  
  * set to an from a field or a pair of matching bean methods. Each
 29  
  * contact must be labeled with an annotation.
 30  
  * 
 31  
  * @author Niall Gallagher
 32  
  *
 33  
  * @see org.simpleframework.xml.core.Label
 34  
  */ 
 35  
 interface Contact extends Type {
 36  
    
 37  
    /**
 38  
     * This represents the name of the object contact. If the contact
 39  
     * is a field then the name of the field is provided. If however
 40  
     * the contact is a method then the Java Bean name of the method
 41  
     * is provided, which will be the decapitalized name of the 
 42  
     * method without the get, set, or is prefix to the method.
 43  
     * 
 44  
     * @return this returns the name of the contact represented
 45  
     */
 46  
    String getName();
 47  
    
 48  
    /**
 49  
     * This provides the dependent class for the contact. This will
 50  
     * typically represent a generic type for the actual type. For
 51  
     * contacts that use a <code>Collection</code> type this will
 52  
     * be the generic type parameter for that collection.
 53  
     * 
 54  
     * @return this returns the dependent type for the contact
 55  
     */
 56  
    Class getDependent();
 57  
    
 58  
    /**
 59  
     * This provides the dependent classes for the contact. This will
 60  
     * typically represent a generic types for the actual type. For
 61  
     * contacts that use a <code>Map</code> type this will be the 
 62  
     * generic type parameter for that map type declaration.
 63  
     * 
 64  
     * @return this returns the dependent types for the contact
 65  
     */
 66  
    Class[] getDependents(); 
 67  
    
 68  
    /**
 69  
     * This is the class that declares the contact. The declaring
 70  
     * class is where the field or method has been defined. This will
 71  
     * typically be a class rather than an interface.
 72  
     * 
 73  
     * @return this returns the class the contact is declared within
 74  
     */
 75  
    Class getDeclaringClass();
 76  
    
 77  
    /**
 78  
     * This is the annotation associated with the point of contact.
 79  
     * This will be an XML annotation that describes how the contact
 80  
     * should be serialized and deserialized from the object.
 81  
     *
 82  
     * @return this provides the annotation associated with this
 83  
     */
 84  
    Annotation getAnnotation();
 85  
    
 86  
    /**
 87  
     * This is used to set the value on the specified object through
 88  
     * this contact. Depending on the type of contact this will set
 89  
     * the value given, typically this will be done by invoking a
 90  
     * method or setting the value on the object field.
 91  
     *
 92  
     * @param source this is the object to set the value on
 93  
     * @param value this is the value to be set through the contact
 94  
     */ 
 95  
    void set(Object source, Object value) throws Exception;
 96  
    
 97  
    /**
 98  
     * This is used to get the value from the specified object using
 99  
     * the point of contact. Typically the value is retrieved from
 100  
     * the specified object by invoking a get method of by acquiring
 101  
     * the value from a field within the specified object.
 102  
     *
 103  
     * @param source this is the object to acquire the value from
 104  
     *
 105  
     * @return this is the value acquired from the point of contact
 106  
     */ 
 107  
    Object get(Object source) throws Exception;
 108  
    
 109  
    /**
 110  
     * This is used to determine if the annotated contact is for a
 111  
     * read only variable. A read only variable is a field that
 112  
     * can be set from within the constructor such as a blank final
 113  
     * variable. It can also be a method with no set counterpart.
 114  
     * 
 115  
     * @return this returns true if the contact is a constant one
 116  
     */
 117  
    boolean isReadOnly();
 118  
    
 119  
    /**
 120  
     * This is used to describe the contact as it exists within the
 121  
     * owning class. This is used to provide error messages that can
 122  
     * be used to debug issues that occur when processing a contact.  
 123  
     * 
 124  
     * @return this returns a string representation of the contact
 125  
     */
 126  
    String toString();
 127  
 }