diff options
| author | Artur Signell <artur@vaadin.com> | 2011-12-12 13:23:32 +0200 |
|---|---|---|
| committer | Artur Signell <artur@vaadin.com> | 2011-12-12 15:00:45 +0200 |
| commit | b6d785312a8e5679cb9fe41a90b522250a48698d (patch) | |
| tree | beeba63d68c44cebf53b6600197de8076b939d9c | |
| parent | 074daf21fd7f3e78848236405de88318e5b5cea5 (diff) | |
| download | vaadin-framework-b6d785312a8e5679cb9fe41a90b522250a48698d.tar.gz vaadin-framework-b6d785312a8e5679cb9fe41a90b522250a48698d.zip | |
#8101 Javadoc for Converter
| -rw-r--r-- | src/com/vaadin/data/util/converter/Converter.java | 84 |
1 files changed, 82 insertions, 2 deletions
diff --git a/src/com/vaadin/data/util/converter/Converter.java b/src/com/vaadin/data/util/converter/Converter.java index 3d21cc36f7..24107c241e 100644 --- a/src/com/vaadin/data/util/converter/Converter.java +++ b/src/com/vaadin/data/util/converter/Converter.java @@ -7,21 +7,101 @@ package com.vaadin.data.util.converter; import java.io.Serializable;
import java.util.Locale;
+/**
+ * Interface that implements conversion between objects of one type to another
+ * and back.
+ * <p>
+ * Typically {@link #convertFromSourceToTarget(Object, Locale)} and
+ * {@link #convertFromTargetToSource(Object, Locale)} should be symmetric so
+ * that chaining these together returns the original result for all input but
+ * this is not a requirement.
+ * </p>
+ * <p>
+ * Converters must not have any side effects (never update UI from inside a
+ * converter).
+ * </p>
+ * <p>
+ * If conversion of a value fails, a {@link ConversionException} is thrown.
+ * </p>
+ *
+ * @param <SOURCE>
+ * @param <TARGET>
+ * @author Vaadin Ltd.
+ * @version
+ * @VERSION@
+ * @since 7.0
+ */
public interface Converter<SOURCE, TARGET> extends Serializable {
+ /**
+ * Converts the given value from target type to source type.
+ * <p>
+ * A converter can optionally use locale to do the conversion.
+ * </p>
+ * A converter should in most cases be symmetric so chaining
+ * {@link #convertFromSourceToTarget(Object, Locale)} and
+ * {@link #convertFromTargetToSource(Object, Locale)} should return the
+ * original value.
+ *
+ * @param value
+ * The value to convert, compatible with the target type. Can be
+ * null
+ * @param locale
+ * The locale to use for conversion. Can be null.
+ * @return The converted value compatible with the source type
+ * @throws ConversionException
+ * If the value could not be converted
+ */
public SOURCE convertFromTargetToSource(TARGET value, Locale locale)
throws ConversionException;
+ /**
+ * Converts the given value from source type to target type.
+ * <p>
+ * A converter can optionally use locale to do the conversion.
+ * </p>
+ * A converter should in most cases be symmetric so chaining
+ * {@link #convertFromSourceToTarget(Object, Locale)} and
+ * {@link #convertFromTargetToSource(Object, Locale)} should return the
+ * original value.
+ *
+ * @param value
+ * The value to convert, compatible with the target type. Can be
+ * null
+ * @param locale
+ * The locale to use for conversion. Can be null.
+ * @return The converted value compatible with the source type
+ * @throws ConversionException
+ * If the value could not be converted
+ */
public TARGET convertFromSourceToTarget(SOURCE value, Locale locale)
throws ConversionException;
+ /**
+ * The source type of the converter.
+ *
+ * Values of this type can be passed to
+ * {@link #convertFromSourceToTarget(Object, Locale)}.
+ *
+ * @return The source type
+ */
public Class<SOURCE> getSourceType();
+ /**
+ * The target type of the converter.
+ *
+ * Values of this type can be passed to
+ * {@link #convertFromTargetToSource(Object, Locale)}.
+ *
+ * @return The target type
+ */
public Class<TARGET> getTargetType();
/**
- * An exception that signals that the value passed to #convert or
- * Converter.convertFromTargetToSource could not be converted.
+ * An exception that signals that the value passed to
+ * {@link Converter#convertFromSourceToTarget(Object, Locale)} or
+ * {@link Converter#convertFromTargetToSource(Object, Locale)} could not be
+ * converted.
*
* @author Vaadin Ltd
* @version
|