Coverage Report

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

Classes in this File

Line Coverage

Branch Coverage

Complexity

AttributeLabel

96%

23/24

100%

2/2

1.308

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