Coverage Report

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

Classes in this File

Line Coverage

Branch Coverage

Complexity

ElementLabel

100%

20/20

100%

1/1

1.154

 /*
  * ElementLabel.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;
 
 import org.simpleframework.xml.Element;
 
 /**
  * The <code>ElementLabel</code> represents a label that is used to
  * represent an XML element in a class schema. This element can be
  * used to convert an XML node into either a primitive value such as
  * a string or composite object value, which is itself a schema for
  * a section of XML within the XML document. 
  * 
  * @author Niall Gallagher
  * 
  *  @see org.simpleframework.xml.Element
  */
 class ElementLabel implements Label {
    
    /**
     * The contact that this element label represents.
     */
    private Signature detail;
    
    /**
     * References the annotation that was used by the field.
     */
    private Element label;
    
    /**
     * This is the type of the class that the field references.
     */
    private Class type;
    
    /**
     * This is the name of the element for this label instance.
     */
    private String name;
    
    /**
     * Constructor for the <code>ElementLabel</code> object. This is
     * used to create a label that can convert a XML node into a 
     * composite object or a primitive type from an XML element. 
     * 
     * @param contact this is the field that this label represents
     * @param label this is the annotation for the contact 
     */
    public ElementLabel(Contact contact, Element label) {
       this.detail = new Signature(contact, this);
       this.type = contact.getType();
       this.name = label.name();     
       this.label = label;      
    }
    
    /**
     * Creates a converter that can be used to transform an XML node to
     * an object and vice versa. The converter created will handles
     * only XML elements and requires the source object to be provided. 
     * 
     * @param root this is the source object used for serialization
     * 
     * @return this returns a converter for serializing XML elements
     */
    public Converter getConverter(Source root) throws Exception {
       if(Factory.isPrimitive(type)) {
          return new Primitive(root, type);
       }
       return new Composite(root, type);
    }
    
    /**
     * 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 {
       return detail.getName();
    }
    
    /**
     * 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 contact that this label is representing
     */
    public Contact getContact() {
       return detail.getContact();
    }
    
    /**
     * 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() {
       return name;
    }
    
    /**
     * This acts as a convinience method used to determine the type of
     * contact 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 contact class
     */  
    public Class getType() {
       return type;
    }
    
    /**
     * This is typically used to acquire the entry value as acquired
     * from the annotation. However given that the annotation this
     * represents does not have a entry attribute this will always
     * provide a null value for the entry string.
     * 
     * @return this will always return null for the entry value 
     */
    public String getEntry() {
       return null;
    }
    
    /**
     * This is used to acquire the dependant class for this label. 
     * This returns null as there are no dependants to the element
     * annotation as it can only hold primitives with no dependants.
     * 
     * @return this is used to return the dependant type of null
     */
    public Class getDependant() {
       return null;
    }
    
    /**
     * This is used to determine whether the XML 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() {
       return label.required();
    }
    
    /**
     * 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() {
       return label.data();
    }
    
    /**
     * 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() {
       return null;
    }
    
    /**
     * This method is used by the deserialization process to check
     * to see if an annotation is inline or not. If an annotation
     * represents an inline XML entity then the deserialization
     * and serialization process ignores overrides and special 
     * attributes. By default all XML elements are not inline.
     * 
     * @return this always returns false for element labels
     */
    public boolean isInline() {
       return false;
    }
    
    /**
     * 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 will provide enough information
     * such that the problem can be isolated correctly. 
     * 
     * @return this returns a string representation of the label
     */
    public String toString() {
       return detail.toString();
    }
 }

1		/*
2		* ElementLabel.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		import org.simpleframework.xml.Element;
24
25		/**
26		* The <code>ElementLabel</code> represents a label that is used to
27		* represent an XML element in a class schema. This element can be
28		* used to convert an XML node into either a primitive value such as
29		* a string or composite object value, which is itself a schema for
30		* a section of XML within the XML document.
31		*
32		* @author Niall Gallagher
33		*
34		* @see org.simpleframework.xml.Element
35		*/
36		class ElementLabel implements Label {
37
38		/**
39		* The contact that this element label represents.
40		*/
41		private Signature detail;
42
43		/**
44		* References the annotation that was used by the field.
45		*/
46		private Element label;
47
48		/**
49		* This is the type of the class that the field references.
50		*/
51		private Class type;
52
53		/**
54		* This is the name of the element for this label instance.
55		*/
56		private String name;
57
58		/**
59		* Constructor for the <code>ElementLabel</code> object. This is
60		* used to create a label that can convert a XML node into a
61		* composite object or a primitive type from an XML element.
62		*
63		* @param contact this is the field that this label represents
64		* @param label this is the annotation for the contact
65		*/
66	182	public ElementLabel(Contact contact, Element label) {
67	182	this.detail = new Signature(contact, this);
68	182	this.type = contact.getType();
69	182	this.name = label.name();
70	182	this.label = label;
71	182	}
72
73		/**
74		* Creates a converter that can be used to transform an XML node to
75		* an object and vice versa. The converter created will handles
76		* only XML elements and requires the source object to be provided.
77		*
78		* @param root this is the source object used for serialization
79		*
80		* @return this returns a converter for serializing XML elements
81		*/
82		public Converter getConverter(Source root) throws Exception {
83	730056	if(Factory.isPrimitive(type)) {
84	568857	return new Primitive(root, type);
85		}
86	161199	return new Composite(root, type);
87		}
88
89		/**
90		* This is used to acquire the name of the element or attribute
91		* that is used by the class schema. The name is determined by
92		* checking for an override within the annotation. If it contains
93		* a name then that is used, if however the annotation does not
94		* specify a name the the field or method name is used instead.
95		*
96		* @return returns the name that is used for the XML property
97		*/
98		public String getName() throws Exception {
99	182	return detail.getName();
100		}
101
102		/**
103		* This is used to acquire the contact object for this label. The
104		* contact retrieved can be used to set any object or primitive that
105		* has been deserialized, and can also be used to acquire values to
106		* be serialized in the case of object persistance. All contacts
107		* that are retrieved from this method will be accessible.
108		*
109		* @return returns the contact that this label is representing
110		*/
111		public Contact getContact() {
112	182	return detail.getContact();
113		}
114
115		/**
116		* This is used to acquire the name of the element or attribute
117		* as taken from the annotation. If the element or attribute
118		* explicitly specifies a name then that name is used for the
119		* XML element or attribute used. If however no overriding name
120		* is provided then the method or field is used for the name.
121		*
122		* @return returns the name of the annotation for the contact
123		*/
124		public String getOverride() {
125	364	return name;
126		}
127
128		/**
129		* This acts as a convinience method used to determine the type of
130		* contact this represents. This is used when an object is written
131		* to XML. It determines whether a <code>class</code> attribute
132		* is required within the serialized XML element, that is, if the
133		* class returned by this is different from the actual value of the
134		* object to be serialized then that type needs to be remembered.
135		*
136		* @return this returns the type of the contact class
137		*/
138		public Class getType() {
139	182	return type;
140		}
141
142		/**
143		* This is typically used to acquire the entry value as acquired
144		* from the annotation. However given that the annotation this
145		* represents does not have a entry attribute this will always
146		* provide a null value for the entry string.
147		*
148		* @return this will always return null for the entry value
149		*/
150		public String getEntry() {
151	364	return null;
152		}
153
154		/**
155		* This is used to acquire the dependant class for this label.
156		* This returns null as there are no dependants to the element
157		* annotation as it can only hold primitives with no dependants.
158		*
159		* @return this is used to return the dependant type of null
160		*/
161		public Class getDependant() {
162	182	return null;
163		}
164
165		/**
166		* This is used to determine whether the XML element is required.
167		* This ensures that if an XML element is missing from a document
168		* that deserialization can continue. Also, in the process of
169		* serialization, if a value is null it does not need to be
170		* written to the resulting XML document.
171		*
172		* @return true if the label represents a some required data
173		*/
174		public boolean isRequired() {
175	182	return label.required();
176		}
177
178		/**
179		* This is used to determine whether the annotation requires it
180		* and its children to be written as a CDATA block. This is done
181		* when a primitive or other such element requires a text value
182		* and that value needs to be encapsulated within a CDATA block.
183		*
184		* @return this returns true if the element requires CDATA
185		*/
186		public boolean isData() {
187	182	return label.data();
188		}
189
190		/**
191		* This is used to provide a configured empty value used when the
192		* annotated value is null. This ensures that XML can be created
193		* with required details regardless of whether values are null or
194		* not. It also provides a means for sensible default values.
195		*
196		* @return this returns the string to use for default values
197		*/
198		public String getEmpty() {
199	182	return null;
200		}
201
202		/**
203		* This method is used by the deserialization process to check
204		* to see if an annotation is inline or not. If an annotation
205		* represents an inline XML entity then the deserialization
206		* and serialization process ignores overrides and special
207		* attributes. By default all XML elements are not inline.
208		*
209		* @return this always returns false for element labels
210		*/
211		public boolean isInline() {
212	364	return false;
213		}
214
215		/**
216		* This is used to describe the annotation and method or field
217		* that this label represents. This is used to provide error
218		* messages that can be used to debug issues that occur when
219		* processing a method. This will provide enough information
220		* such that the problem can be isolated correctly.
221		*
222		* @return this returns a string representation of the label
223		*/
224		public String toString() {
225	5	return detail.toString();
226		}
227		}