Coverage Report

Coverage Report - org.simpleframework.xml.load.Label

Classes in this File

 /*
  * Label.java July 2006
  *
  * Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation.
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
  * GNU Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General 
  * Public License along with this library; if not, write to the 
  * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 
  * Boston, MA  02111-1307  USA
  */
 
 package org.simpleframework.xml.load;
 
 /**
  * The <code>Label</code> interface is used to describe an reference to
  * a field annotated with an XML schema annotation. Because each field
  * and annotation is different, there are different ways in which the
  * annotation can be accessed. This provides a uniform means for 
  * accessing the field annotation details and the field properties.
  * <p>
  * This also exposes a <code>Converter</code> object, which is used to
  * convert an XML node into a property that can be assigned to the 
  * annotated field. Each converter returned is specific to the label
  * and knows, based on the annotation, how to serialize the field.
  * 
  * @author Niall Gallagher
  */
 interface Label {
 
    /**
     * This method returns a <code>Converter</code> which can be used to
     * convert an XML node into an object value and vice versa. The 
     * converter requires only the source object in order to perform
     * serialization or deserialization of the provided XML node.
     * 
     * @param root this is the source object for the serialization
     * 
     * @return this returns an object that is used for conversion
     */
    public Converter getConverter(Source root) throws 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.
     * 
     * @return returns the name that is used for the XML property
     */
    public String getName() throws Exception;
    
    /**
     * This returns the dependant type for the annotation. This type
     * is the type other than the annotated field or method type that
     * the label depends on. For the <code>ElementList</code> and 
     * the <code>ElementArray</code> this is the component type that
     * is deserialized individually and inserted into the container. 
     * 
     * @return this is the type that the annotation depends on
     */
    public Class getDependant() throws 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.
     * 
     * @return this returns the name of the XML entry element used 
     */
    public String getEntry() throws 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.
     * 
     * @return this returns the string to use for default values
     */
    public String getEmpty();
    
    /**
     * 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 persistance. All contacts 
     * that are retrieved from this method will be accessible. 
     * 
     * @return returns the field that this label is representing
     */
    public Contact getContact();
 
    /**
     * This acts as a convinience 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 <code>class</code> 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.
     *  
     * @return this returns the type of the field class
     */
    public Class getType();
    
    /**
     * 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. 
     * 
     * @return returns the name of the annotation for the contact
     */
    public String getOverride();
    
    /**
     * 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.
     * 
     * @return this returns true if the element requires CDATA
     */
    public boolean isData();
    
    /**
     * 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.
     * 
     * @return true if the label represents a some required data
     */
    public boolean isRequired();
    
    /**
     * This is used to determine whether the label represents an
     * inline XML entity. The <code>ElementList</code> annotation
     * and the <code>Text</code> annotation represent inline 
     * items. This means that they contain no containing element
     * and so can not specify overrides or special attributes.
     * 
     * @return this returns true if the annotation is inline
     */
    public boolean isInline();
    
    /**
     * 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 should provide enough information
     * such that the problem can be isolated correctly. 
     * 
     * @return this returns a string representation of the label
     */
    public String toString();
 }

1		/*
2		* Label.java July 2006
3		*
4		* Copyright (C) 2006, Niall Gallagher <niallg@users.sf.net>
5		*
6		* This library is free software; you can redistribute it and/or
7		* modify it under the terms of the GNU Lesser General Public
8		* License as published by the Free Software Foundation.
9		*
10		* This library is distributed in the hope that it will be useful,
11		* but WITHOUT ANY WARRANTY; without even the implied warranty of
12		* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13		* GNU Lesser General Public License for more details.
14		*
15		* You should have received a copy of the GNU Lesser General
16		* Public License along with this library; if not, write to the
17		* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
18		* Boston, MA 02111-1307 USA
19		*/
20
21		package org.simpleframework.xml.load;
22
23		/**
24		* The <code>Label</code> interface is used to describe an reference to
25		* a field annotated with an XML schema annotation. Because each field
26		* and annotation is different, there are different ways in which the
27		* annotation can be accessed. This provides a uniform means for
28		* accessing the field annotation details and the field properties.
29		* <p>
30		* This also exposes a <code>Converter</code> object, which is used to
31		* convert an XML node into a property that can be assigned to the
32		* annotated field. Each converter returned is specific to the label
33		* and knows, based on the annotation, how to serialize the field.
34		*
35		* @author Niall Gallagher
36		*/
37		interface Label {
38
39		/**
40		* This method returns a <code>Converter</code> which can be used to
41		* convert an XML node into an object value and vice versa. The
42		* converter requires only the source object in order to perform
43		* serialization or deserialization of the provided XML node.
44		*
45		* @param root this is the source object for the serialization
46		*
47		* @return this returns an object that is used for conversion
48		*/
49		public Converter getConverter(Source root) throws Exception;
50
51		/**
52		* This is used to acquire the name of the element or attribute
53		* that is used by the class schema. The name is determined by
54		* checking for an override within the annotation. If it contains
55		* a name then that is used, if however the annotation does not
56		* specify a name the the field or method name is used instead.
57		*
58		* @return returns the name that is used for the XML property
59		*/
60		public String getName() throws Exception;
61
62		/**
63		* This returns the dependant type for the annotation. This type
64		* is the type other than the annotated field or method type that
65		* the label depends on. For the <code>ElementList</code> and
66		* the <code>ElementArray</code> this is the component type that
67		* is deserialized individually and inserted into the container.
68		*
69		* @return this is the type that the annotation depends on
70		*/
71		public Class getDependant() throws Exception;
72
73		/**
74		* This is used to either provide the entry value provided within
75		* the annotation or compute a entry value. If the entry string
76		* is not provided the the entry value is calculated as the type
77		* of primitive the object is as a simplified class name.
78		*
79		* @return this returns the name of the XML entry element used
80		*/
81		public String getEntry() throws Exception;
82
83		/**
84		* This is used to provide a configured empty value used when the
85		* annotated value is null. This ensures that XML can be created
86		* with required details regardless of whether values are null or
87		* not. It also provides a means for sensible default values.
88		*
89		* @return this returns the string to use for default values
90		*/
91		public String getEmpty();
92
93		/**
94		* This is used to acquire the contact object for this label. The
95		* contact retrieved can be used to set any object or primitive that
96		* has been deserialized, and can also be used to acquire values to
97		* be serialized in the case of object persistance. All contacts
98		* that are retrieved from this method will be accessible.
99		*
100		* @return returns the field that this label is representing
101		*/
102		public Contact getContact();
103
104		/**
105		* This acts as a convinience method used to determine the type of
106		* the field this represents. This is used when an object is written
107		* to XML. It determines whether a <code>class</code> attribute
108		* is required within the serialized XML element, that is, if the
109		* class returned by this is different from the actual value of the
110		* object to be serialized then that type needs to be remembered.
111		*
112		* @return this returns the type of the field class
113		*/
114		public Class getType();
115
116		/**
117		* This is used to acquire the name of the element or attribute
118		* as taken from the annotation. If the element or attribute
119		* explicitly specifies a name then that name is used for the
120		* XML element or attribute used. If however no overriding name
121		* is provided then the method or field is used for the name.
122		*
123		* @return returns the name of the annotation for the contact
124		*/
125		public String getOverride();
126
127		/**
128		* This is used to determine whether the annotation requires it
129		* and its children to be written as a CDATA block. This is done
130		* when a primitive or other such element requires a text value
131		* and that value needs to be encapsulated within a CDATA block.
132		*
133		* @return this returns true if the element requires CDATA
134		*/
135		public boolean isData();
136
137		/**
138		* Determines whether the XML attribute or element is required.
139		* This ensures that if an XML element is missing from a document
140		* that deserialization can continue. Also, in the process of
141		* serialization, if a value is null it does not need to be
142		* written to the resulting XML document.
143		*
144		* @return true if the label represents a some required data
145		*/
146		public boolean isRequired();
147
148		/**
149		* This is used to determine whether the label represents an
150		* inline XML entity. The <code>ElementList</code> annotation
151		* and the <code>Text</code> annotation represent inline
152		* items. This means that they contain no containing element
153		* and so can not specify overrides or special attributes.
154		*
155		* @return this returns true if the annotation is inline
156		*/
157		public boolean isInline();
158
159		/**
160		* This is used to describe the annotation and method or field
161		* that this label represents. This is used to provide error
162		* messages that can be used to debug issues that occur when
163		* processing a method. This should provide enough information
164		* such that the problem can be isolated correctly.
165		*
166		* @return this returns a string representation of the label
167		*/
168		public String toString();
169		}