001/*
002 * Convert.java January 2010
003 *
004 * Copyright (C) 2010, 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.convert;
020
021import java.lang.annotation.Retention;
022import java.lang.annotation.RetentionPolicy;
023
024/**
025 * The <code>Convert</code> annotation is used to specify a converter
026 * class to use for serialization. This annotation is used when an
027 * object needs to be serialized but can not be annotated or when the
028 * object can not conform to an existing XML structure. In order to
029 * specify a <code>Converter</code> object a field or method can be
030 * annotated like the field below.
031 * <pre>
032 * 
033 *    &#64;Element
034 *    &#64;Convert(ExampleConverter.class)
035 *    private Example example;
036 * 
037 * </pre>
038 * Note that for the above field the <code>Element</code> annotation
039 * is required. If this is used with any other XML annotation such 
040 * as the <code>ElementList</code> or <code>Text</code> annotation
041 * then an exception will be thrown. As well as field and methods
042 * this can be used to suggest a converter for a class. Take the 
043 * class below which is annotated.
044 * <pre>
045 * 
046 *    &#64;Root
047 *    &#64;Convert(DemoConverter.class)
048 *    public class Demo {
049 *       ...
050 *    }
051 * 
052 * </pre>
053 * For the above class the specified converter will be used. This is
054 * useful when the class is used within a <code>java.util.List</code>
055 * or another similar collection. Finally, in order for this to work
056 * it must be used with the <code>AnnotationStrategy</code> which is
057 * used to scan for annotations in order to delegate to converters.
058 * 
059 * @author Niall Gallagher
060 * 
061 * @see org.simpleframework.xml.convert.AnnotationStrategy
062 */
063@Retention(RetentionPolicy.RUNTIME)
064public @interface Convert {
065   
066   /**
067    * Specifies the <code>Converter</code> implementation to be used
068    * to convert the annotated object. The converter specified will
069    * be used to convert the object to XML by intercepting the 
070    * serialization and deserialization process as it happens. A
071    * converter should typically be used to handle an object of 
072    * a specific type.
073    * 
074    * @return this returns the converter that has been specified
075    */
076   Class<? extends Converter> value();
077}