Coverage Report

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

Classes in this File

Line Coverage

Branch Coverage

Complexity

ElementArrayLabel

96%

27/28

100%

3/3

1.357

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