org.omnifaces.persistence.model

Annotation Type EnumMapping

@Target(value=TYPE)
 @Retention(value=RUNTIME)
public @interface EnumMapping

Basic annotation to change default behaviour of @Enumerated. When this annotation is added to the declaration of declaration of custom enum then persisting its value by using @Enumerated will be changed. If EnumType.ORDINAL is used as type() (default) then the enum will be persisted basing on fieldName() that's holding custom state of enum that must correspond to the real property of enum and must be of int type, otherwise default mapping will be applied. If EnumType.STRING is used as type() then the enum will be persisted basing on fieldName() that must correspond to the real property of enum and must be of String type, otherwise default mapping will be applied. The fieldName() defaults to "id" when type() evaluates to EnumType.ORDINAL and to "code" when type() evaluates to EnumType.STRING.

Modified behaviour of @Enumerated will be used when the entities are managed by BaseEntityService. Noted should be that when any entity managed by BaseEntityService uses the enum with EnumMapping applied then it will be persisted in a modified way way even when the other entity is not managed by BaseEntityService to entail consistency.

This is particularly useful if you want to avoid drawbacks of standard JPA enum mappings, like reordering or renaming, by enforcing consistency between enum modifications during application development, like addition of new, or removal of old enum values. By using this annotation developer has full control of what part of the enum will be mapped to the database.

Usage of this annotation is as follows:

 @EnumMapping(fieldName = "id")
 public enum ProductStatus {

     IN_STOCK(1), OUT_OF_STOCK(10), DISCONTINUED(20);

     private int id;

     private ProductStatus(int id) {
         this.id = id;
     }

     public int getId() {
         return id;
     }

 }
 

and

 @EnumMapping(type = EnumType.STRING, fieldName = "code")
 public enum UserRole {

     USER("USR"), EMPLOYEE("EMP"), MANAGER("MGR");

     private String code;

     private UserRole(String code) {
         this.code = code;
     }

     public String getCode() {
         return code;
     }

 }
 

with

 @Entity
 public class Product extends GeneratedIdEntity<Long> {

      @Enumerated
     private ProductStatus productStatus;

      @ElementCollection
      @Enumerated(STRING)
     private Set<UserRole> userRoles = new HashSet<>();

     // ...
 }
 

In such setup persistence provider will save to the database the status as either 1, 10 or 20 (as opposed to 0, 1 or 2) and role as either USR, EMP or MGR (as opposed to USER, EMPLOYEE or MANAGER).

The behaviour described above allows to change the way that enums are persisted, thus making persistence of enums steadier than by default, but it doesn't allow to keep all possible enum values in a separate database table, nor it allows to differentiate between discontinued enum values that were used in the past, but are not now supported. By using the additional EnumMappingTable annotation the correspondence between java enum and database table representations can be established and enum mapping can be fine-tuned.

When using this annotation the default mapping can be changed and one-to-one correspondence between java enum and database table representations can be achieved, with the additional possibility to track historical values of enum constants used before. By default this behaviour is turned off, as it requires developer to specify the additional enum mapping characteristics, and the standard enum mapping specified with this annotation is applied.

Author:

Sergey Kuntsel

See Also:

EnumMappingTable

Field Summary

Fields

Modifier and Type	Fields and Description
static String	CODE_FIELD_NAME
static String	ID_FIELD_NAME

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
EnumMappingTable	enumMappingTable Fine-tunes mapping between the java enum and the database table.
String	fieldName Specifies the corresponding field name of mapped enum.
EnumType	type Specifies the enum mapping type.

Field Detail

ID_FIELD_NAME

public static final String ID_FIELD_NAME

CODE_FIELD_NAME

public static final String CODE_FIELD_NAME

Element Detail

type

public abstract EnumType type

Specifies the enum mapping type. Defaults to EnumType.ORDINAL.

Returns:

The enum mapping type.

Default:

javax.persistence.EnumType.ORDINAL

fieldName

public abstract String fieldName

Specifies the corresponding field name of mapped enum. Defaults to "id" when type() evaluates to EnumType.ORDINAL and to "code" when type() evaluates to EnumType.STRING.

Returns:

The corresponding field name of mapped enum.

Default:

""

enumMappingTable

public abstract EnumMappingTable enumMappingTable

Fine-tunes mapping between the java enum and the database table. By default no fine-tuning will be performed.

Returns:

Mapping between java enum and database table.

Default:

@org.omnifaces.persistence.model.EnumMappingTable