001/*
002 * ElementArray.java July 2006
003 *
004 * Copyright (C) 2006, 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>ElementArray</code> annotation represents a method or 
026 * field that is an array of elements. The array deserialized is the
027 * same type as the field or method, all entries within the array 
028 * must be a compatible type. However, a <code>class</code> attribute 
029 * can be used to override an entry, this must be an assignable type.
030 * <pre>
031 *
032 *    &lt;array length="3"&gt;
033 *       &lt;entry&gt;
034 *          &lt;value&gt;example text value&lt;/value&gt;
035 *       &lt;/entry&gt;
036 *       &lt;entry&gt;
037 *          &lt;value&gt;some other value&lt;/value&gt;
038 *       &lt;/entry&gt;
039 *       &lt;entry/&gt;
040 *    &lt;/array&gt;
041 * 
042 * </pre>
043 * All null objects within the array are represented as an empty XML
044 * element so that they can be deserialized accurately. This ensures
045 * that the length attribute of the array is respected, as well as 
046 * the index position of all serialized entries. The length of the 
047 * array must be specified for deserialization to instantiate the 
048 * array before the array values are instantiated. This is required 
049 * to account for cyclical references in the object graph.
050 * 
051 * @author Niall Gallagher
052 */
053@Retention(RetentionPolicy.RUNTIME)
054public @interface ElementArray {
055   
056   /**
057    * This represents the name of the XML element. Annotated fields
058    * or methods can optionally provide the name of the element. If 
059    * no name is provided then the name of the annotated field or 
060    * method will be used in its place. The name is provided if the 
061    * field or method name is not suitable as an XML element name.
062    * 
063    * @return the name of the XML element this represents
064    */
065   String name() default "";
066   
067   /**
068    * This is used to provide a name of the XML element representing
069    * the entry within the array. An entry name is optional and is
070    * used when the name needs to be overridden. This also ensures
071    * that entry, regardless of type has the same root name.   
072    * 
073    * @return this returns the entry XML element for each value
074    */
075   String entry() default "";
076   
077   /**
078    * This is used to determine whether the element data is written
079    * in a CDATA block or not. If this is set to true then the text
080    * is written within a CDATA block, by default the text is output
081    * as escaped XML. Typically this is useful when this annotation
082    * is applied to an array of primitives, such as strings.
083    * 
084    * @return true if entries are to be wrapped in a CDATA block
085    */
086   boolean data() default false;
087   
088   /**
089    * Determines whether the element is required within the XML
090    * document. Any field marked as not required will not have its
091    * value set when the object is deserialized. If an object is to
092    * be serialized only a null attribute will not appear as XML.
093    * 
094    * @return true if the element is required, false otherwise
095    */        
096   boolean required() default true;
097   
098   /**
099    * This is used to determine if an optional field or method can
100    * remain null if it does not exist. If this is false then the
101    * optional element is given an empty array. This is a convenience
102    * attribute which avoids having to check if the element is null
103    * before providing it with a suitable default instance.
104    * 
105    * @return false if an optional element is always instantiated
106    */
107   boolean empty() default true;
108}