com.vaadin.v7.data.util.converter.Converter Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of vaadin-compatibility-server Show documentation
Vaadin 7 compatibility package for Vaadin 8
There is a newer version: 8.27.3
Show newest version
/*
 * Copyright (C) 2000-2024 Vaadin Ltd
 *
 * This program is available under Vaadin Commercial License and Service Terms.
 *
 * See  for the full
 * license.
 */

package com.vaadin.v7.data.util.converter;

import java.io.Serializable;
import java.util.Locale;

/**
 * Interface that implements conversion between a model and a presentation type.
 * 
 * Typically {@link #convertToPresentation(Object, Class, Locale)} and
 * {@link #convertToModel(Object, Class, Locale)} should be symmetric so that
 * chaining these together returns the original result for all input but this is
 * not a requirement.
 * 
 * 
 * Converters must not have any side effects (never update UI from inside a
 * converter).
 * 
 * 
 * All Converters must be stateless and thread safe.
 * 
 * 
 * If conversion of a value fails, a {@link ConversionException} is thrown.
 * 
 *
 * @param 
 *            The presentation type. Must be compatible with what
 *            {@link #getPresentationType()} returns.
 * @param 
 *            The model type. Must be compatible with what
 *            {@link #getModelType()} returns.
 * @author Vaadin Ltd.
 * @since 7.0
 */
@Deprecated
public interface Converter extends Serializable {

    /**
     * Converts the given value from target type to source type.
     * 
     * A converter can optionally use locale to do the conversion.
     * 
     * A converter should in most cases be symmetric so chaining
     * {@link #convertToPresentation(Object, Class, Locale)} and
     * {@link #convertToModel(Object, Class, Locale)} should return the original
     * value.
     *
     * @param value
     *            The value to convert, compatible with the target type. Can be
     *            null
     * @param targetType
     *            The requested type of the return value
     * @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 MODEL convertToModel(PRESENTATION value,
            Class targetType, Locale locale)
            throws ConversionException;

    /**
     * Converts the given value from source type to target type.
     * 
     * A converter can optionally use locale to do the conversion.
     * 
     * A converter should in most cases be symmetric so chaining
     * {@link #convertToPresentation(Object, Class, Locale)} and
     * {@link #convertToModel(Object, Class, Locale)} should return the original
     * value.
     *
     * @param value
     *            The value to convert, compatible with the target type. Can be
     *            null
     * @param targetType
     *            The requested type of the return value
     * @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 PRESENTATION convertToPresentation(MODEL value,
            Class targetType, Locale locale)
            throws ConversionException;

    /**
     * The source type of the converter.
     *
     * Values of this type can be passed to
     * {@link #convertToPresentation(Object, Class, Locale)}.
     *
     * @return The source type
     */
    public Class getModelType();

    /**
     * The target type of the converter.
     *
     * Values of this type can be passed to
     * {@link #convertToModel(Object, Class, Locale)}.
     *
     * @return The target type
     */
    public Class getPresentationType();

    /**
     * An exception that signals that the value passed to
     * {@link Converter#convertToPresentation(Object, Class, Locale)} or
     * {@link Converter#convertToModel(Object, Class, Locale)} could not be
     * converted.
     *
     * @author Vaadin Ltd
     * @since 7.0
     */
    @Deprecated
    public static class ConversionException extends RuntimeException {

        /**
         * Constructs a new ConversionException without a detail
         * message.
         */
        public ConversionException() {
        }

        /**
         * Constructs a new ConversionException with the specified
         * detail message.
         *
         * @param msg
         *            the detail message
         */
        public ConversionException(String msg) {
            super(msg);
        }

        /**
         * Constructs a new {@code ConversionException} with the specified
         * cause.
         *
         * @param cause
         *            The cause of the the exception
         */
        public ConversionException(Throwable cause) {
            super(cause);
        }

        /**
         * Constructs a new ConversionException with the specified
         * detail message and cause.
         *
         * @param message
         *            the detail message
         * @param cause
         *            The cause of the the exception
         */
        public ConversionException(String message, Throwable cause) {
            super(message, cause);
        }
    }

}