001/*
002 * ElementMap.java August 2007
003 *
004 * Copyright (C) 2007, Niall Gallagher <niallg@users.sf.net>
005 *
006 * Licensed under the Apache License, Version 2.0 (the "License");
007 * you may not use this file except in compliance with the License.
008 * You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
015 * implied. See the License for the specific language governing 
016 * permissions and limitations under the License.
017 */
018
019package org.simpleframework.xml;
020
021import java.lang.annotation.RetentionPolicy;
022import java.lang.annotation.Retention;
023
024/**
025 * The <code>ElementMap</code> annotation represents a method or field
026 * that is a <code>Map</code> for storing key value pairs. The map 
027 * object deserialized is typically of the same type as the field. 
028 * However, a <code>class</code> attribute can be used to override the 
029 * field type, however the type must be assignable.
030 * <pre>
031 * 
032 *    &lt;map class="java.util.HashMap"&gt;
033 *       &lt;entry key="one"&gt;value one&lt;/entry&gt;
034 *       &lt;entry key="two"&gt;value two&lt;/entry&gt;
035 *       &lt;entry key="three"&gt;value three&lt;/entry&gt;  
036 *    &lt;/map&gt;
037 * 
038 * </pre>
039 * If a <code>class</code> attribute is not provided and the type or
040 * the field or method is abstract, a suitable match is searched for 
041 * from the maps available from the Java collections framework. This 
042 * annotation can support both primitive and composite values and 
043 * keys enabling just about any configuration to be used.
044 * <pre>
045 *
046 *    &lt;map class="java.util.HashMap"&gt;
047 *       &lt;entry key="1"&gt;
048 *          &lt;value&gt;value one&lt;/value&gt;
049 *       &lt;/entry&gt;
050 *       &lt;entry key="2"&gt;
051 *          &lt;value&gt;value two&lt;/value&gt;
052 *       &lt;/entry&gt;
053 *       &lt;entry key="3"&gt;
054 *          &lt;value&gt;value three&lt;/value&gt;
055 *       &lt;/entry&gt; 
056 *    &lt;/map&gt;
057 * 
058 * </pre>
059 * The above XML is an example of the output for an composite value
060 * object. Composite and primitive values can be used without any
061 * specified attributes, in such a case names for primitives are the
062 * names of the objects they represent. Also, if desired these 
063 * default names can be overridden using the provided attributes
064 * making the resulting XML entirely configurable.
065 * 
066 * @author Niall Gallagher
067 */
068@Retention(RetentionPolicy.RUNTIME)
069public @interface ElementMap {
070
071   /**
072    * This represents the name of the XML element. Annotated fields
073    * can optionally provide the name of the element. If no name is
074    * provided then the name of the annotated field or method will
075    * be used in its place. The name is provided if the field or
076    * method name is not suitable as an XML element name. Also, if
077    * the list is inline then this must not be specified.
078    * 
079    * @return the name of the XML element this represents
080    */
081   String name() default "";
082   
083   /**
084    * This is used to provide a the name of the entry XML element 
085    * that wraps the key and value elements. If specified the entry
086    * value specified will be used instead of the default name of 
087    * the element. This is used to ensure the resulting XML is 
088    * configurable to the requirements of the generated XML. 
089    * 
090    * @return this returns the entry XML element for each entry
091    */
092   String entry() default ""; 
093
094   /**
095    * This is used to provide a value XML element for each of the
096    * values within the map. This essentially wraps the entity to
097    * be serialized such that there is an extra XML element present.
098    * This can be used to override the default names of primitive
099    * values, however it can also be used to wrap composite values. 
100    * 
101    * @return this returns the value XML element for each value
102    */
103   String value() default "";
104
105   /**
106    * This is used to provide a key XML element for each of the
107    * keys within the map. This essentially wraps the entity to
108    * be serialized such that there is an extra XML element present.
109    * This can be used to override the default names of primitive
110    * keys, however it can also be used to wrap composite keys. 
111    * 
112    * @return this returns the key XML element for each key
113    */
114   String key() default "";
115   
116   /**
117    * Represents the type of key the element map contains. This
118    * type is used to deserialize the XML entry key from the map. 
119    * The object typically represents the deserialized type, but can
120    * represent a subclass of the type deserialized as determined
121    * by the <code>class</code> attribute value for the map. If 
122    * this is not specified then the type can be determined from the
123    * generic parameter of the annotated <code>Map</code> object.
124    * 
125    * @return the type of the entry key deserialized from the XML
126    */
127   Class keyType() default void.class;
128   
129   /**
130    * Represents the type of value the element map contains. This
131    * type is used to deserialize the XML entry value from the map. 
132    * The object typically represents the deserialized type, but can
133    * represent a subclass of the type deserialized as determined
134    * by the <code>class</code> attribute value for the map. If 
135    * this is not specified then the type can be determined from the
136    * generic parameter of the annotated <code>Map</code> object.
137    * 
138    * @return the type of the entry value deserialized from the XML
139    */
140   Class valueType() default void.class;
141
142   /**
143    * Represents whether the key value is to be an attribute or an
144    * element. This allows the key to be embedded within the entry
145    * XML element allowing for a more compact representation. Only
146    * primitive key objects can be represented as an attribute. For
147    * example a <code>java.util.Date</code> or a string could be
148    * represented as an attribute key for the generated XML. 
149    *  
150    * @return true if the key is to be inlined as an attribute
151    */
152   boolean attribute() default false;
153   
154   /**
155    * Determines whether the element is required within the XML
156    * document. Any field marked as not required will not have its
157    * value set when the object is deserialized. If an object is to
158    * be serialized only a null attribute will not appear as XML.
159    * 
160    * @return true if the element is required, false otherwise
161    */ 
162   boolean required() default true;
163   
164   /**
165    * This is used to determine whether the element data is written
166    * in a CDATA block or not. If this is set to true then the text
167    * is written within a CDATA block, by default the text is output
168    * as escaped XML. Typically this is useful when this annotation
169    * is applied to an array of primitives, such as strings.
170    * 
171    * @return true if entries are to be wrapped in a CDATA block
172    */
173   boolean data() default false;
174   
175   /**
176    * Determines whether the element list is inlined with respect
177    * to the parent XML element. An inlined element list does not
178    * contain an enclosing element. It is simple a sequence of 
179    * elements that appear one after another within an element.
180    * As such an inline element list must not have a name. 
181    *
182    * @return this returns true if the element list is inline
183    */
184   boolean inline() default false;
185   
186   /**
187    * This is used to determine if an optional field or method can
188    * remain null if it does not exist. If this is false then the
189    * optional element is given an empty map. This is a convenience
190    * attribute which avoids having to check if the element is null
191    * before providing it with a suitable default instance.
192    * 
193    * @return false if an optional element is always instantiated
194    */
195   boolean empty() default true;
196}