/*
 * Copyright (C) 2005 Joe Walnes.
 * Copyright (C) 2006, 2007, 2008, 2009, 2011 XStream Committers.
 * All rights reserved.
 *
 * The software in this package is published under the terms of the BSD
 * style license a copy of which has been included with this distribution in
 * the LICENSE.txt file.
 * 
 * Created on 16. September 2005 by Mauro Talevi
 */
package com.thoughtworks.xstream.annotations;

import com.thoughtworks.xstream.XStream;
import com.thoughtworks.xstream.converters.ConverterMatcher;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;


/**
 * Annotation to declare a converter. The annotation supports additionally the injection of
 * various constructor arguments provided by XStream:
 * <ul>
 * <li>{@link com.thoughtworks.xstream.mapper.Mapper}: The current mapper chain of the XStream
 * instance.</li>
 * <li>{@link ClassLoader}: The class loader used by the XStream instance to deserialize the
 * objects.</li>
 * <li>{@link com.thoughtworks.xstream.converters.reflection.ReflectionProvider}: The reflection
 * provider used by the reflection based converters of the current XStream instance.</li>
 * <li>{@link com.thoughtworks.xstream.converters.ConverterLookup}: The lookup for converters
 * handling a special type.</li>
 * <li>{@link com.thoughtworks.xstream.core.JVM}: Utility e.g. to load classes.</li>
 * <li>All elements provided with the individual arrays of this annotation.</li>
 * <li>{@link Class}: The type of the element where the annotation is declared. Note, that this
 * argument is not supported when using
 * {@link com.thoughtworks.xstream.annotations.XStreamConverters}.</li>
 * </ul>
 * <p>
 * Note, the annotation matches a {@link ConverterMatcher}.
 * {@link com.thoughtworks.xstream.converters.ConverterMatcher} as well as
 * {@link com.thoughtworks.xstream.converters.SingleValueConverter} extend this interface. The
 * {@link com.thoughtworks.xstream.mapper.AnnotationMapper} can only handle these two
 * <strong>known</strong> types.
 * </p>
 * 
 * @author Chung-Onn Cheong
 * @author J&ouml;rg Schaible
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE, ElementType.FIELD})
@Documented
public @interface XStreamConverter {
    Class<? extends ConverterMatcher> value();
    int priority() default XStream.PRIORITY_NORMAL;
    Class<?>[] types() default {};
    String[] strings() default {};
    byte[] bytes() default {};
    char[] chars() default {};
    short[] shorts() default {};
    int[] ints() default {};
    long[] longs() default {};
    float[] floats() default {};
    double[] doubles() default {};
    boolean[] booleans() default {};
}

@@ -75,16 +75,22 @@
 09, 2011
+, 2012
  XStream
@@ -102,16 +102,16 @@
 itters.%0A
-
  * All r
@@ -1568,16 +1568,137 @@
 otation.
+ The provided values%0A * follow the declaration sequence if a constructor requires multiple arguments of the same%0A * type.
 %3C/li%3E%0A *
@@ -1918,20 +1918,108 @@
 %3E%0A * %3Cp%3E
+The algorithm will try the converter's constructor with the most arguments first.%3C/p%3E
 %0A * 
+%3Cp%3E
 Note, th
@@ -2355,20 +2355,16 @@
 %3E types.
-%0A * 
 %3C/p%3E%0A * 
@@ -2605,16 +2605,16 @@
 alue();%0A
-
     int 
@@ -2657,16 +2657,520 @@
 NORMAL;%0A
+    /**%0A     * Provide class types as arguments for the converter's constructor arguments.%0A     * %0A     * %3Cp%3ENote, that XStream itself provides the current class type as first Class argument to%0A     * a constructor, if the annotation is added directly to a class type (and not as part of a%0A     * parameter declaration of a %7B@link XStreamConverters%7D annotation). The current type has%0A     * precedence over any type provided with this method.%0A     * %0A     * @return the types%0A     * @since 1.4.2%0A     */%0A
     Clas

Improve Javadoc.