001package com.avaje.ebean.annotation;
002
003import java.lang.annotation.ElementType;
004import java.lang.annotation.Retention;
005import java.lang.annotation.RetentionPolicy;
006import java.lang.annotation.Target;
007
008/**
009 * For mapping the values of an Enum to and from Database values.
010 * <p>
011 * Also refer to the {@link EnumValue} approach which probably the preferred now
012 * (preferred over using this EnumMapping annotation).
013 * </p>
014 * <p>
015 * Both of the approaches defined in the JPA have significant problems!!!
016 * </p>
017 * <p>
018 * Using the ordinal value is VERY RISKY because that depends on the compile
019 * order of the enum values. Aka if you change the order of the enum values you
020 * have changed their ordinal values and now your DB values are WRONG - a HUGE
021 * disaster!!!.
022 * </p>
023 * <p>
024 * Using the String values of enums is fairly restrictive because in a Database
025 * these values are usually truncated into short codes (e.g. "A" short for
026 * "ACTIVE") so space used in the database is minimised. Making your enum names
027 * match the database values would give them very short less meaningful names -
028 * not a great solution.
029 * </p>
030 * <p>
031 * You can use this annotation to control the mapping of your enums to database
032 * values.
033 * </p>
034 * <p>
035 * The design of this using nameValuePairs is not optimal for safety or
036 * refactoring so if you have a better solution I'm all ears. The other
037 * solutions would probably involve modifying each enumeration with a method
038 * which may be ok.
039 * </p>
040 * <p>
041 * An example mapping the UserState enum.
042 * </p>
043 * 
044 * <pre class="code">
045 * ...
046 * &#064;EnumMapping(nameValuePairs=&quot;NEW=N, ACTIVE=A, INACTIVE=I&quot;)
047 *  public enum UserState {
048 *  NEW,
049 *  ACTIVE,
050 *  INACTIVE;
051 *  }
052 * </pre>
053 * 
054 * @see EnumValue
055 */
056@Target({ ElementType.TYPE })
057@Retention(RetentionPolicy.RUNTIME)
058public @interface EnumMapping {
059
060  /**
061   * A comma delimited list of name=value pairs.
062   * <p>
063   * e.g. "ACTIVE=A, INACTIVE=I, NEW=N".
064   * </p>
065   * <p>
066   * Where ACTIVE, INACTIVE and NEW are the enumeration values and "A", "I" and
067   * "N" are the database values.
068   * </p>
069   * <p>
070   * This is not really an optimal approach so if you have a better one I'm all
071   * ears - thanks.
072   * </p>
073   */
074  String nameValuePairs();
075
076  /**
077   * Defaults to mapping values to database VARCHAR type. If this is set to true
078   * then the values will be converted to INTEGER and mapped to the database
079   * integer type.
080   * <p>
081   * e.g. "ACTIVE=1, INACTIVE=0, NEW=2".
082   * </p>
083   */
084  boolean integerType() default false;
085
086  /**
087   * The length of DB column if mapping to string values.
088   */
089  int length() default 0;
090}