Using Java enums properly in Seam2/JSF/JPA

By Ian Darwin on 2009-01-27 22:22 in Category: java web

The Seam documentation covers this now, but it's a bit short of complete examples. Most of this probably applies to other JSF/JPA deployments too..

This first part is Seam-specific: To make the list of a given enum's values available to the view,  just add one new annotated method to a "Factories" class.

@Name("factories")
public class Factories {

    @Factory("countries")
    public Country[] getCountries() {
       return Country.values();
    }

Because you want to display a user-friendly name in the web form, but store a short and consistent name in the database, the enum must have a "label" or "name" field and a getter method (many enums already do). For example, we'll display Canada in the drop-down but enter the ISO-3166 country code CA in the database.

/** See ISO-3166 */
public enum Country {
   CA("Canada"),
   US("United States"),
   AF("Afghanistan"),
   ...
   ;
   private String longName;
   private Country(String longName) {
       this.longName = longName;
   }
   public String getLongName() {
       return longName;
   }    
   @Override
   public String toString () {
       return getLongName();
   }

You may want to save the string name rather than the ordinal value into the database (especially with Countries where the list order will change in future as countries split or join!). OTOH a simple enum like Status { Unkown, Active, Defunct } is unlikely to pick up new enum values, so use integers, and if you do add any, add at the end.

The @Entity class should be annotated thusly:

   @Column(name="Country")
   @Enumerated(EnumType.STRING)   // default and only other choice is ORDINAL
   public Country getCountry() {
       return this.country;
   }

Then, to select it (display a drop-down), you'd use, for example:

      <h:selectOneMenu value="#{register.personalAddress.country}">
             <s:selectItems var="country" value="#{countries}"
                        label="#{country.longName}" noSelectionLabel="-- Select --"/>
              <s:convertEnum/>
       </h:selectOneMenu>

If you've used another framework than Seam, there's a bit of Seam's beauty: the Seam convertEnum tag fixes JSF 1's mess of having your data classes be required to know about UIComponent. Of course this is fixed in JSF 2.x..

To display the current value in a view-only page,  you just need, for example,

  <h:outputText id="country"
      value="#{person.personalAddress.country.longName}"/ >

If you're storing Strings in the database for the enum, the data must be basically spotless for the enum converter to work, so - if you didn't have enumerating check constraints on the database from day one - you may e.g., have to "sanitize" the data a little to ensure there are no non-null but blank values in the database, or convert any lower-case values to upper case to match the enum constants. If not you'll get strange message like the famous "can't find resultList" - always check the JBoss console log for a stack trace!

These can be cleaned with SQL like this, using whatever tool you use to feed raw SQL into whatever database you're using:

   update address set country = 'CA' where country = ''
Or you could set these values to NULL.

   update address set country = upper(country)

To check the values, you can use SQL similar to this:

    select distinct(country) from address

Then it all works nicely, as it should, without any need for EntityConverter or for mixing UIComponents into your data layer. Seam rocks!
Twitter logo RSS/Atom Feed Icon
Categories Cloud