From affa369b7f338d0e094b1e48c12a29e88b6d2d1a Mon Sep 17 00:00:00 2001 From: Artur Signell Date: Mon, 12 Dec 2011 14:31:43 +0200 Subject: #8101/#8103 Javadoc for converters and converter factory --- .../util/converter/BooleanToStringConverter.java | 39 ++++++++++++- src/com/vaadin/data/util/converter/Converter.java | 7 +++ .../data/util/converter/ConverterFactory.java | 9 +++ .../data/util/converter/DateToStringConverter.java | 59 +++++++++++++++++--- .../util/converter/DefaultConverterFactory.java | 15 +++++ .../util/converter/DoubleToStringConverter.java | 64 ++++++++++++++++++++-- .../util/converter/IntegerToStringConverter.java | 34 ++++++++++-- .../data/util/converter/LongToDateConverter.java | 32 +++++++++++ .../util/converter/NumberToStringConverter.java | 57 +++++++++++++++++-- .../data/util/converter/ReverseConverter.java | 49 ++++++++++++++++- src/com/vaadin/ui/AbstractField.java | 8 +-- .../tests/components/table/DoublesInTable.java | 2 +- 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 { - 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 { } } - 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 { return value.toString(); } + /* + * (non-Javadoc) + * + * @see com.vaadin.data.util.converter.Converter#getSourceType() + */ public Class getSourceType() { return Boolean.class; } + /* + * (non-Javadoc) + * + * @see com.vaadin.data.util.converter.Converter#getTargetType() + */ public Class 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). *

*

+ * All Converters must be stateless and thread safe. + *

+ *

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

* * @param + * The source type. Must be compatible with what + * {@link #getSourceType()} returns. * @param + * 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 { Converter createConverter( Class sourceType, Class 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. + *

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

+ * + * @author Vaadin Ltd + * @version + * @VERSION@ + * @since 7.0 + */ public class DateToStringConverter implements Converter { + /** + * 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 { 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 { 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 getSourceType() { return Date.class; } + /* + * (non-Javadoc) + * + * @see com.vaadin.data.util.converter.Converter#getTargetType() + */ public Class 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}.

+ *

+ * Custom converters can be provided by extending this class and using + * {@link Application#setConverterFactory(ConverterFactory)}. + *

+ * + * @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. + *

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

+ * + * @author Vaadin Ltd + * @version + * @VERSION@ + * @since 7.0 + */ public class DoubleToStringConverter implements Converter { - 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 { 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 getSourceType() { return Double.class; } + /* + * (non-Javadoc) + * + * @see com.vaadin.data.util.converter.Converter#getTargetType() + */ public Class 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. + *

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

+ * + * @author Vaadin Ltd + * @version + * @VERSION@ + * @since 7.0 + */ public class IntegerToStringConverter implements Converter { - 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 { } } - 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 { // 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 { 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 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 { + /* + * (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 { 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 { return new Date(value); } + /* + * (non-Javadoc) + * + * @see com.vaadin.data.util.converter.Converter#getSourceType() + */ public Class getSourceType() { return Long.class; } + /* + * (non-Javadoc) + * + * @see com.vaadin.data.util.converter.Converter#getTargetType() + */ public Class 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. + *

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

+ * + * @author Vaadin Ltd + * @version + * @VERSION@ + * @since 7.0 + */ public class NumberToStringConverter implements Converter { - 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 { } } - 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 { // 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 { 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 getSourceType() { return Number.class; } + /* + * (non-Javadoc) + * + * @see com.vaadin.data.util.converter.Converter#getTargetType() + */ public Class 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 + * The source type + * @param + * The target type + * + * @author Vaadin Ltd + * @version + * @VERSION@ + * @since 7.0 + */ public class ReverseConverter implements Converter { private Converter realConverter; - public ReverseConverter(Converter 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 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 getSourceType() { return realConverter.getTargetType(); } + /* + * (non-Javadoc) + * + * @see com.vaadin.data.util.converter.Converter#getTargetType() + */ public Class 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 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 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); -- cgit v1.2.3