Cayenne User Documentation
Modeling Enumerations

## Mapping and Modeling Java Enumerations

Cayenne natively supports Java 1.5 custom enumerations. There are two levels of support. The more flexible method is to implement the Cayenne ExtendedEnumeration interface and provide the database value for each enumeration. The advantage of implementing this interface is it allows you to specify the exact database value represented by each enumeration and the enumerations are not order-fragile. If you do not implement this interface, Cayenne will use a fallback approach and only use the enum's actual name (for a text column) or the ordinal position (for a numeric column, which is fragile).

Regardless of which incarnation you use, in Cayenne Modeler's ObjEntity editor, under the Attributes tab, give the full class name for your enumeration under the Java Type column. This column is pre-filled with java.lang.String, etc., but you can provide your own Java type there:

Cayenne will auto-register the enumeration at runtime.

There is currently no other modeler support for mapping the enumerations (no "enum editor" in Cayenne Modeler). You have to hand-create the enumerations yourself, but this isn't too difficult to do. Choose either Extended/Standard below and use the examples as a pattern for creating your own.

### Extended Enumerations

Cayenne's extended enumerations need to implement ExtendedEnumeration, which contains only the getDatabaseValue() method. This method is used to specify the exact database value each enumeration represents.

Here is an example mapping enumerations to integers:

    import org.apache.cayenne.ExtendedEnumeration;

    public enum Color implements ExtendedEnumeration {
      RED(3), GREEN(6), BLUE(9);

      private Integer value;

      private Color(Integer value)
      {
        this.value = value;
      }

      public Integer getDatabaseValue()
      {
        return value;
      }
    }

This instructs Cayenne to read/write 3, 6, and 9 as RED, GREEN, and BLUE, respectively. The order is unimportant – if someone re-orders them to be BLUE, GREEN, and RED, all values will still map correctly.

An example mapping enumerations to strings:

    import org.apache.cayenne.ExtendedEnumeration;

    public enum State implements ExtendedEnumeration {
      ALABAMA("AL"), ALASKA("AK"), ARIZONA("AZ"), MARYLAND("MD"), VIRGINIA("VA");

      private String value;

      private State(String value)
      {
        this.value = value;
      }

      public String getDatabaseValue()
      {
        return value;
      }
    }

In this example, long state names are mapped to the database as their two-letter standard abbreviation.

The final example illustrates how the database can store one value, but you might want to utilize a different internal value for calculations or some other purpose:

    import org.apache.cayenne.ExtendedEnumeration;

    public enum InterestTerm implements ExtendedEnumeration
    {
      YEARLY(1, 1), QUARTERLY(2, 4), MONTHLY(3, 12);

      private Integer dbValue;
      private int value;

      private InterestTerm(Integer dbValue, int value)
      {
        this.dbValue = dbValue;
        this.value = value;
      }

      public Integer getDatabaseValue()
      {
        return dbValue;
      }

      public int value()
      {
        return value;
      }
    }

Cayenne will store 1, 2, and 3 as the database values in this case, but the code can call the value() method (which is not part of the ExtendedEnumeration interface) to use a different value for calculations.

As you can see, the constructor can take as many parameters as required and you can add as many methods as you need. Only getDatabaseValue() is required by Cayenne and that will determine the value persisted for each enumeration.

### Standard Enumerations

Cayenne's support for standard enumerations maps the enum's actual name (if a string column) or the ordinal position (if a numeric column). Given the Color example declared this way:

    public enum Color {
      RED, GREEN, BLUE;
    }

Cayenne will persist "RED", "GREEN", or "BLUE" to the database for a string column (you cannot specify the value persisted). For a numeric column, it will persist 0, 1, and 2, respectively (again, you cannot specify the value – they are simply the order defined in the Java code). Numeric columns are especially fragile because if someone re-orders the Java enum to be BLUE, GREEN, and RED, then all previously persisted values of RED and BLUE will swap places when you read from the database (which most likely is incorrect).

.
Copyright ©2001-2008 Apache Software Foundation