001/*
002 * Element.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>Element</code> annotation is used to represent a field
026 * or method that appears as an XML element. Fields or methods that
027 * are annotated with this can be either primitive or compound, that
028 * is, represent an object that can be serialized and deserialized.
029 * Below is an example of the serialized format for a compound object.
030 * <p>
031 * If this annotates a type that contains no XML annotations then
032 * this will look for a suitable <code>Transform</code> for the type
033 * using the <code>Transformer</code>. For instance, all primitives 
034 * and primitive arrays that are annotated with this will make use 
035 * of a transform in order to convert its value to and from suitable 
036 * XML representations.
037 * <pre>
038 * 
039 *    &lt;example class="demo.Example"&gt;
040 *       &lt;data/&gt;
041 *    &lt;example&gt;
042 * 
043 * </pre>
044 * Each element may have any number of attributes and sub-elements
045 * representing fields or methods of that compound object. Attribute
046 * and element names can be acquired from the annotation or, if the
047 * annotation does not explicitly declare a name, it is taken from
048 * the annotated field or method. There are exceptions in some cases,
049 * for example, the <code>class</code> attribute is reserved by the
050 * serialization framework to represent the serialized type. 
051 * 
052 * @author Niall Gallagher
053 */ 
054@Retention(RetentionPolicy.RUNTIME)
055public @interface Element {
056   
057   /**
058    * This represents the name of the XML element. Annotated fields
059    * can optionally provide the name of the element. If no name is
060    * provided then the name of the annotated field or method will
061    * be used in its place. The name is provided if the field or
062    * method name is not suitable as an XML element name.
063    * 
064    * @return the name of the XML element this represents
065    */
066   String name() default "";
067   
068   /**
069    * This is used to determine whether the element data is written
070    * in a CDATA block or not. If this is set to true then the text
071    * is written within a CDATA block, by default the text is output
072    * as escaped XML. Typically this is useful for primitives only.
073    * 
074    * @return true if the data is to be wrapped in a CDATA block
075    */
076   boolean data() default false;
077   
078   /**
079    * Determines whether the element is required within the XML
080    * document. Any field marked as not required will not have its
081    * value set when the object is deserialized. If an object is to
082    * be serialized only a null attribute will not appear as XML.
083    * 
084    * @return true if the element is required, false otherwise
085    */
086   boolean required() default true; 
087   
088   /**
089    * This represents an explicit type that should be used for the
090    * annotated field or method. Typically this is used when the
091    * element forms part of a union group. It allows the union
092    * to distinguish the annotation to use based on the type.
093    * 
094    * @return this returns the explicit type to use for this
095    */
096   Class type() default void.class;
097}