com.vaadin.data.util.converter.Converter Maven / Gradle / Ivy
/*
* Vaadin Framework 7
*
* 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.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
*/
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
*/
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);
}
}
}