#8101/#8103 Javadoc for converters and converter factory

12 files changed, 343 insertions, 32 deletions

diff --git a/src/com/vaadin/data/util/converter/BooleanToStringConverter.java b/src/com/vaadin/data/util/converter/BooleanToStringConverter.java
index 3deeb8b99f..d0eef353ac 100644
--- a/src/com/vaadin/data/util/converter/BooleanToStringConverter.java
+++ b/src/com/vaadin/data/util/converter/BooleanToStringConverter.java
@@ -6,9 +6,26 @@ package com.vaadin.data.util.converter;
 

 import java.util.Locale;

 

+/**

+ * A converter that converts from {@link Boolean} to {@link String} and back.

+ * The String representation is given by Boolean.toString().

+ * 

+ * @author Vaadin Ltd

+ * @version

+ * @VERSION@

+ * @since 7.0

+ */

 public class BooleanToStringConverter implements Converter<Boolean, String> {

 

-    public Boolean convertFromTargetToSource(String value, Locale locale) {

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromTargetToSource(java

+     * .lang.Object, java.util.Locale)

+     */

+    public Boolean convertFromTargetToSource(String value, Locale locale)

+            throws ConversionException {

         try {

             return Boolean.valueOf(value);

         } catch (Exception e) {

@@ -17,7 +34,15 @@ public class BooleanToStringConverter implements Converter<Boolean, String> {
         }

     }

 

-    public String convertFromSourceToTarget(Boolean value, Locale locale) {

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromSourceToTarget(java

+     * .lang.Object, java.util.Locale)

+     */

+    public String convertFromSourceToTarget(Boolean value, Locale locale)

+            throws ConversionException {

         if (value == null) {

             return "";

         }

@@ -25,10 +50,20 @@ public class BooleanToStringConverter implements Converter<Boolean, String> {
         return value.toString();

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getSourceType()

+     */

     public Class<Boolean> getSourceType() {

         return Boolean.class;

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getTargetType()

+     */

     public Class<String> getTargetType() {

         return String.class;

     }

diff --git a/src/com/vaadin/data/util/converter/Converter.java b/src/com/vaadin/data/util/converter/Converter.java
index 24107c241e..3ed83efe46 100644
--- a/src/com/vaadin/data/util/converter/Converter.java
+++ b/src/com/vaadin/data/util/converter/Converter.java
@@ -21,11 +21,18 @@ import java.util.Locale;
  * converter).

  * </p>

  * <p>

+ * All Converters must be stateless and thread safe.

+ * </p>

+ * <p>

  * If conversion of a value fails, a {@link ConversionException} is thrown.

  * </p>

  * 

  * @param <SOURCE>

+ *            The source type. Must be compatible with what

+ *            {@link #getSourceType()} returns.

  * @param <TARGET>

+ *            The target type. Must be compatible with what

+ *            {@link #getTargetType()} returns.

  * @author Vaadin Ltd.

  * @version

  * @VERSION@

diff --git a/src/com/vaadin/data/util/converter/ConverterFactory.java b/src/com/vaadin/data/util/converter/ConverterFactory.java
index 64622299c1..1770bf85ac 100644
--- a/src/com/vaadin/data/util/converter/ConverterFactory.java
+++ b/src/com/vaadin/data/util/converter/ConverterFactory.java
@@ -6,6 +6,15 @@ package com.vaadin.data.util.converter;
 

 import java.io.Serializable;

 

+/**

+ * Factory interface for providing Converters based on a source and target type.

+ * 

+ * @author Vaadin Ltd.

+ * @version

+ * @VERSION@

+ * @since 7.0

+ * 

+ */

 public interface ConverterFactory extends Serializable {

     <SOURCE, TARGET> Converter<SOURCE, TARGET> createConverter(

             Class<SOURCE> sourceType, Class<TARGET> targetType);

diff --git a/src/com/vaadin/data/util/converter/DateToStringConverter.java b/src/com/vaadin/data/util/converter/DateToStringConverter.java
index 00c83492e9..c87fca5423 100644
--- a/src/com/vaadin/data/util/converter/DateToStringConverter.java
+++ b/src/com/vaadin/data/util/converter/DateToStringConverter.java
@@ -9,8 +9,43 @@ import java.text.ParsePosition;
 import java.util.Date;

 import java.util.Locale;

 

+/**

+ * A converter that converts from {@link Date} to {@link String} and back. Uses

+ * the given locale and {@link DateFormat} for formatting and parsing.

+ * <p>

+ * Override and overwrite {@link #getFormat(Locale)} to use a different format.

+ * </p>

+ * 

+ * @author Vaadin Ltd

+ * @version

+ * @VERSION@

+ * @since 7.0

+ */

 public class DateToStringConverter implements Converter<Date, String> {

 

+    /**

+     * Returns the format used by

+     * {@link #convertFromSourceToTarget(Date, Locale)} and

+     * {@link #convertFromTargetToSource(String, Locale)}.

+     * 

+     * @param locale

+     *            The locale to use

+     * @return A DateFormat instance

+     */

+    protected DateFormat getFormat(Locale locale) {

+        DateFormat f = DateFormat.getDateTimeInstance(DateFormat.MEDIUM,

+                DateFormat.MEDIUM, locale);

+        f.setLenient(false);

+        return f;

+    }

+

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromTargetToSource(java

+     * .lang.Object, java.util.Locale)

+     */

     public Date convertFromTargetToSource(String value, Locale locale)

             throws com.vaadin.data.util.converter.Converter.ConversionException {

         if (value == null) {

@@ -27,6 +62,13 @@ public class DateToStringConverter implements Converter<Date, String> {
         return parsedValue;

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromSourceToTarget(java

+     * .lang.Object, java.util.Locale)

+     */

     public String convertFromSourceToTarget(Date value, Locale locale)

             throws com.vaadin.data.util.converter.Converter.ConversionException {

         if (value == null) {

@@ -36,17 +78,20 @@ public class DateToStringConverter implements Converter<Date, String> {
         return getFormat(locale).format(value);

     }

 

-    protected DateFormat getFormat(Locale locale) {

-        DateFormat f = DateFormat.getDateTimeInstance(DateFormat.MEDIUM,

-                DateFormat.MEDIUM, locale);

-        f.setLenient(false);

-        return f;

-    }

-

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getSourceType()

+     */

     public Class<Date> getSourceType() {

         return Date.class;

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getTargetType()

+     */

     public Class<String> getTargetType() {

         return String.class;

     }

diff --git a/src/com/vaadin/data/util/converter/DefaultConverterFactory.java b/src/com/vaadin/data/util/converter/DefaultConverterFactory.java
index 9d05f89345..073eb10d55 100644
--- a/src/com/vaadin/data/util/converter/DefaultConverterFactory.java
+++ b/src/com/vaadin/data/util/converter/DefaultConverterFactory.java
@@ -7,6 +7,21 @@ package com.vaadin.data.util.converter;
 import java.util.Date;

 import java.util.logging.Logger;

 

+import com.vaadin.Application;

+

+/**

+ * Default implementation of {@link ConverterFactory}. Provides converters for

+ * standard types like {@link String}, {@link Double} and {@link Date}. </p>

+ * <p>

+ * Custom converters can be provided by extending this class and using

+ * {@link Application#setConverterFactory(ConverterFactory)}.

+ * </p>

+ * 

+ * @author Vaadin Ltd

+ * @version

+ * @VERSION@

+ * @since 7.0

+ */

 public class DefaultConverterFactory implements ConverterFactory {

 

     private final static Logger log = Logger

diff --git a/src/com/vaadin/data/util/converter/DoubleToStringConverter.java b/src/com/vaadin/data/util/converter/DoubleToStringConverter.java
index 18b7f85a13..405d034ed7 100644
--- a/src/com/vaadin/data/util/converter/DoubleToStringConverter.java
+++ b/src/com/vaadin/data/util/converter/DoubleToStringConverter.java
@@ -8,15 +8,49 @@ import java.text.NumberFormat;
 import java.text.ParsePosition;

 import java.util.Locale;

 

+/**

+ * A converter that converts from {@link Double} to {@link String} and back.

+ * Uses the given locale and a {@link NumberFormat} instance for formatting and

+ * parsing.

+ * <p>

+ * Override and overwrite {@link #getFormat(Locale)} to use a different format.

+ * </p>

+ * 

+ * @author Vaadin Ltd

+ * @version

+ * @VERSION@

+ * @since 7.0

+ */

 public class DoubleToStringConverter implements Converter<Double, String> {

 

-    protected NumberFormat getFormatter(Locale locale) {

-        return NumberFormat.getNumberInstance(locale);

+    /**

+     * Returns the format used by

+     * {@link #convertFromSourceToTarget(Double, Locale)} and

+     * {@link #convertFromTargetToSource(String, Locale)}.

+     * 

+     * @param locale

+     *            The locale to use

+     * @return A NumberFormat instance

+     */

+    protected NumberFormat getFormat(Locale locale) {

+        if (locale == null) {

+            return NumberFormat.getNumberInstance();

+        } else {

+            return NumberFormat.getNumberInstance(locale);

+        }

     }

 

-    public Double convertFromTargetToSource(String value, Locale locale) {

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromTargetToSource(java

+     * .lang.Object, java.util.Locale)

+     */

+    public Double convertFromTargetToSource(String value, Locale locale)

+            throws ConversionException {

         ParsePosition parsePosition = new ParsePosition(0);

-        Number parsedValue = getFormatter(locale).parse(value, parsePosition);

+        Number parsedValue = getFormat(locale).parse(value, parsePosition);

         if (parsePosition.getIndex() != value.length()) {

             throw new ConversionException("Could not convert '" + value

                     + "' to " + getTargetType().getName());

@@ -24,18 +58,36 @@ public class DoubleToStringConverter implements Converter<Double, String> {
         return parsedValue.doubleValue();

     }

 

-    public String convertFromSourceToTarget(Double value, Locale locale) {

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromSourceToTarget(java

+     * .lang.Object, java.util.Locale)

+     */

+    public String convertFromSourceToTarget(Double value, Locale locale)

+            throws ConversionException {

         if (value == null) {

             return null;

         }

 

-        return getFormatter(locale).format(value);

+        return getFormat(locale).format(value);

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getSourceType()

+     */

     public Class<Double> getSourceType() {

         return Double.class;

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getTargetType()

+     */

     public Class<String> getTargetType() {

         return String.class;

     }

diff --git a/src/com/vaadin/data/util/converter/IntegerToStringConverter.java b/src/com/vaadin/data/util/converter/IntegerToStringConverter.java
index c73f31a527..ef4861f3cd 100644
--- a/src/com/vaadin/data/util/converter/IntegerToStringConverter.java
+++ b/src/com/vaadin/data/util/converter/IntegerToStringConverter.java
@@ -8,9 +8,31 @@ import java.text.NumberFormat;
 import java.text.ParsePosition;

 import java.util.Locale;

 

+/**

+ * A converter that converts from {@link Integer} to {@link String} and back.

+ * Uses the given locale and a {@link NumberFormat} instance for formatting and

+ * parsing.

+ * <p>

+ * Override and overwrite {@link #getFormat(Locale)} to use a different format.

+ * </p>

+ * 

+ * @author Vaadin Ltd

+ * @version

+ * @VERSION@

+ * @since 7.0

+ */

 public class IntegerToStringConverter implements Converter<Integer, String> {

 

-    protected NumberFormat getFormatter(Locale locale) {

+    /**

+     * Returns the format used by

+     * {@link #convertFromSourceToTarget(Integer, Locale)} and

+     * {@link #convertFromTargetToSource(String, Locale)}.

+     * 

+     * @param locale

+     *            The locale to use

+     * @return A NumberFormat instance

+     */

+    protected NumberFormat getFormat(Locale locale) {

         if (locale == null) {

             return NumberFormat.getIntegerInstance();

         } else {

@@ -18,7 +40,8 @@ public class IntegerToStringConverter implements Converter<Integer, String> {
         }

     }

 

-    public Integer convertFromTargetToSource(String value, Locale locale) {

+    public Integer convertFromTargetToSource(String value, Locale locale)

+            throws ConversionException {

         if (value == null) {

             return null;

         }

@@ -29,7 +52,7 @@ public class IntegerToStringConverter implements Converter<Integer, String> {
         // Parse and detect errors. If the full string was not used, it is

         // an error.

         ParsePosition parsePosition = new ParsePosition(0);

-        Number parsedValue = getFormatter(locale).parse(value, parsePosition);

+        Number parsedValue = getFormat(locale).parse(value, parsePosition);

         if (parsePosition.getIndex() != value.length()) {

             throw new ConversionException("Could not convert '" + value

                     + "' to " + getTargetType().getName());

@@ -42,12 +65,13 @@ public class IntegerToStringConverter implements Converter<Integer, String> {
         return parsedValue.intValue();

     }

 

-    public String convertFromSourceToTarget(Integer value, Locale locale) {

+    public String convertFromSourceToTarget(Integer value, Locale locale)

+            throws ConversionException {

         if (value == null) {

             return null;

         }

 

-        return getFormatter(locale).format(value);

+        return getFormat(locale).format(value);

     }

 

     public Class<Integer> getSourceType() {

diff --git a/src/com/vaadin/data/util/converter/LongToDateConverter.java b/src/com/vaadin/data/util/converter/LongToDateConverter.java
index 56f76f08bc..c7d2a33c76 100644
--- a/src/com/vaadin/data/util/converter/LongToDateConverter.java
+++ b/src/com/vaadin/data/util/converter/LongToDateConverter.java
@@ -7,8 +7,23 @@ package com.vaadin.data.util.converter;
 import java.util.Date;

 import java.util.Locale;

 

+/**

+ * A converter that converts from {@link Long} to {@link Date} and back.

+ * 

+ * @author Vaadin Ltd

+ * @version

+ * @VERSION@

+ * @since 7.0

+ */

 public class LongToDateConverter implements Converter<Long, Date> {

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromTargetToSource(java

+     * .lang.Object, java.util.Locale)

+     */

     public Long convertFromTargetToSource(Date value, Locale locale) {

         if (value == null) {

             return null;

@@ -17,6 +32,13 @@ public class LongToDateConverter implements Converter<Long, Date> {
         return value.getTime();

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromSourceToTarget(java

+     * .lang.Object, java.util.Locale)

+     */

     public Date convertFromSourceToTarget(Long value, Locale locale) {

         if (value == null) {

             return null;

@@ -25,10 +47,20 @@ public class LongToDateConverter implements Converter<Long, Date> {
         return new Date(value);

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getSourceType()

+     */

     public Class<Long> getSourceType() {

         return Long.class;

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getTargetType()

+     */

     public Class<Date> getTargetType() {

         return Date.class;

     }

diff --git a/src/com/vaadin/data/util/converter/NumberToStringConverter.java b/src/com/vaadin/data/util/converter/NumberToStringConverter.java
index b6ce96c3ef..f0d57c6083 100644
--- a/src/com/vaadin/data/util/converter/NumberToStringConverter.java
+++ b/src/com/vaadin/data/util/converter/NumberToStringConverter.java
@@ -8,9 +8,30 @@ import java.text.NumberFormat;
 import java.text.ParsePosition;

 import java.util.Locale;

 

+/**

+ * A converter that converts from {@link Number} to {@link String} and back.

+ * Uses the given locale and {@link NumberFormat} for formatting and parsing.

+ * <p>

+ * Override and overwrite {@link #getFormat(Locale)} to use a different format.

+ * </p>

+ * 

+ * @author Vaadin Ltd

+ * @version

+ * @VERSION@

+ * @since 7.0

+ */

 public class NumberToStringConverter implements Converter<Number, String> {

 

-    protected NumberFormat getFormatter(Locale locale) {

+    /**

+     * Returns the format used by

+     * {@link #convertFromSourceToTarget(Number, Locale)} and

+     * {@link #convertFromTargetToSource(String, Locale)}.

+     * 

+     * @param locale

+     *            The locale to use

+     * @return A NumberFormat instance

+     */

+    protected NumberFormat getFormat(Locale locale) {

         if (locale == null) {

             return NumberFormat.getNumberInstance();

         } else {

@@ -18,7 +39,15 @@ public class NumberToStringConverter implements Converter<Number, String> {
         }

     }

 

-    public Number convertFromTargetToSource(String value, Locale locale) {

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromTargetToSource(java

+     * .lang.Object, java.util.Locale)

+     */

+    public Number convertFromTargetToSource(String value, Locale locale)

+            throws ConversionException {

         if (value == null) {

             return null;

         }

@@ -29,7 +58,7 @@ public class NumberToStringConverter implements Converter<Number, String> {
         // Parse and detect errors. If the full string was not used, it is

         // an error.

         ParsePosition parsePosition = new ParsePosition(0);

-        Number parsedValue = getFormatter(locale).parse(value, parsePosition);

+        Number parsedValue = getFormat(locale).parse(value, parsePosition);

         if (parsePosition.getIndex() != value.length()) {

             throw new ConversionException("Could not convert '" + value

                     + "' to " + getTargetType().getName());

@@ -42,18 +71,36 @@ public class NumberToStringConverter implements Converter<Number, String> {
         return parsedValue;

     }

 

-    public String convertFromSourceToTarget(Number value, Locale locale) {

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromSourceToTarget(java

+     * .lang.Object, java.util.Locale)

+     */

+    public String convertFromSourceToTarget(Number value, Locale locale)

+            throws ConversionException {

         if (value == null) {

             return null;

         }

 

-        return getFormatter(locale).format(value);

+        return getFormat(locale).format(value);

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getSourceType()

+     */

     public Class<Number> getSourceType() {

         return Number.class;

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getTargetType()

+     */

     public Class<String> getTargetType() {

         return String.class;

     }

diff --git a/src/com/vaadin/data/util/converter/ReverseConverter.java b/src/com/vaadin/data/util/converter/ReverseConverter.java
index bb334b91a7..d3e2540b57 100644
--- a/src/com/vaadin/data/util/converter/ReverseConverter.java
+++ b/src/com/vaadin/data/util/converter/ReverseConverter.java
@@ -6,29 +6,74 @@ package com.vaadin.data.util.converter;
 

 import java.util.Locale;

 

+/**

+ * A converter that wraps another {@link Converter} and reverses source and

+ * target types.

+ * 

+ * @param <SOURCE>

+ *            The source type

+ * @param <TARGET>

+ *            The target type

+ * 

+ * @author Vaadin Ltd

+ * @version

+ * @VERSION@

+ * @since 7.0

+ */

 public class ReverseConverter<SOURCE, TARGET> implements

         Converter<SOURCE, TARGET> {

 

     private Converter<TARGET, SOURCE> realConverter;

 

-    public ReverseConverter(Converter<TARGET, SOURCE> realConverter) {

-        this.realConverter = realConverter;

+    /**

+     * Creates a converter from source to target based on a converter that

+     * converts from target to source.

+     * 

+     * @param converter

+     *            The converter to use in a reverse fashion

+     */

+    public ReverseConverter(Converter<TARGET, SOURCE> converter) {

+        this.realConverter = converter;

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromTargetToSource(java

+     * .lang.Object, java.util.Locale)

+     */

     public SOURCE convertFromTargetToSource(TARGET value, Locale locale)

             throws com.vaadin.data.util.converter.Converter.ConversionException {

         return realConverter.convertFromSourceToTarget(value, locale);

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see

+     * com.vaadin.data.util.converter.Converter#convertFromSourceToTarget(java

+     * .lang.Object, java.util.Locale)

+     */

     public TARGET convertFromSourceToTarget(SOURCE value, Locale locale)

             throws com.vaadin.data.util.converter.Converter.ConversionException {

         return realConverter.convertFromTargetToSource(value, locale);

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getSourceType()

+     */

     public Class<SOURCE> getSourceType() {

         return realConverter.getTargetType();

     }

 

+    /*

+     * (non-Javadoc)

+     * 

+     * @see com.vaadin.data.util.converter.Converter#getTargetType()

+     */

     public Class<TARGET> getTargetType() {

         return realConverter.getSourceType();

     }

diff --git a/src/com/vaadin/ui/AbstractField.java b/src/com/vaadin/ui/AbstractField.java
index 2db1fc16d9..3e35b4936e 100644
--- a/src/com/vaadin/ui/AbstractField.java
+++ b/src/com/vaadin/ui/AbstractField.java
@@ -348,9 +348,8 @@ public abstract class AbstractField<T> extends AbstractComponent implements
      * Returns the value that is or should be displayed in the field. This is
      * always of type T.
      * 
-     * This method should return the same as
-     * convertFromDataSource(getDataSourceValue()) if there are no buffered
-     * changes in the field.
+     * This method should return the converter data source value if there are no
+     * buffered changes in the field.
      * 
      * @return The value of the field
      */
@@ -732,7 +731,8 @@ public abstract class AbstractField<T> extends AbstractComponent implements
     }
 
     @SuppressWarnings("unchecked")
-    private T convertFromDataSource(Object newValue) {
+    private T convertFromDataSource(Object newValue)
+            throws Converter.ConversionException {
         if (valueConverter != null) {
             return valueConverter.convertFromSourceToTarget(newValue,
                     getLocale());
diff --git a/tests/testbench/com/vaadin/tests/components/table/DoublesInTable.java b/tests/testbench/com/vaadin/tests/components/table/DoublesInTable.java
index e9ba5ff579..273114d2ea 100644
--- a/tests/testbench/com/vaadin/tests/components/table/DoublesInTable.java
+++ b/tests/testbench/com/vaadin/tests/components/table/DoublesInTable.java
@@ -252,7 +252,7 @@ public class DoublesInTable extends TestBase {
 

         t.setConverter("rent", new NumberToStringConverter() {

             @Override

-            protected NumberFormat getFormatter(Locale locale) {

+            protected NumberFormat getFormat(Locale locale) {

                 return NumberFormat.getCurrencyInstance(locale);

                 // DecimalFormat df = new DecimalFormat();

                 // df.setDecimalSeparatorAlwaysShown(true);