001package com.avaje.ebean.config;
002
003/**
004 * Used to convert between a value object and a known scalar type. The value
005 * object is the logical type used in your application and the scalar type is
006 * the value used to persist than to the DB.
007 * <p>
008 * The Value object should be immutable and scalar (aka not compound) and
009 * converts to and from a known scalar type which Ebean will use to persist the
010 * value.
011 * </p>
012 * <p>
013 * This is an easier alternative to implementing the
014 * com.avaje.ebean.server.type.ScalarType interface.
015 * </p>
016 * <p>
017 * Note that Ebean will automatically try to detect Immutable Scalar Value
018 * Objects and automatically support them via reflection. This however would not
019 * be appropriate when the logical type is different from the type you wish to
020 * use for persistence - for example, if the logical type was long and you
021 * wanted to use java.sql.Timestamp for persistence. In this case you would want
022 * to implement this interface rather than let Ebean automatically support that
023 * type via reflection.
024 * </p>
025 * <p>
026 * If you want to support a Compound Type rather than a Scalar Type refer to
027 * {@link CompoundType}.
028 * </p>
029 * 
030 * @author rbygrave
031 * 
032 * @param <B>
033 *          The value object type.
034 * @param <S>
035 *          The scalar object type that is used to persist the value object.
036 * 
037 * @see CompoundType
038 * @see CompoundTypeProperty
039 */
040public interface ScalarTypeConverter<B, S> {
041
042  /**
043   * Return the value to represent null. Typically this is actually null but for
044   * scala.Option and similar type converters this actually returns an instance
045   * representing "None".
046   */
047  B getNullValue();
048
049  /**
050   * Convert the scalar type value into the value object.
051   * <p>
052   * This typically occurs when Ebean reads the value from a resultSet or other
053   * data source.
054   * </p>
055   * 
056   * @param scalarType
057   *          the value from the data source
058   */
059  B wrapValue(S scalarType);
060
061  /**
062   * Convert the value object into a scalar value that Ebean knows how to
063   * persist.
064   * <p>
065   * This typically occurs when Ebean is persisting the value object to the data
066   * store.
067   * </p>
068   * 
069   * @param beanType
070   *          the value object
071   */
072  S unwrapValue(B beanType);
073
074}