Page History

Java language enumeration types have an ordinal() method , which that returns the numerical position of each enumeration constant in its class declaration. Wiki MarkupThe _Java Language Specification_ \[[JLS 2005|AA. Bibliography#JLS 05]\] [§8.9, "Enums"|http://java.sun.com/docs/books/jls/third_edition/html/classes.html#8.9] does not specify the use of {{ordinal()}} in programs. However, using the {{ordinal()}} method to derive the value associated with an enum constant is error-prone and should be avoided. unmigrated-wiki-markup

According to the Java API \[[API 2006|AA. Bibliography#API 06]\], {{public final int ordinal()}}:API, Class Enum<E extends Enum<E>> [API 2011], public final int ordinal()

returns Returns the ordinal of the enumeration constant (its position in its enum declaration, where the initial constant is assigned an ordinal of zero). Most programmers will have no use for this method. It is designed for use by sophisticated enum-based data structures, such as EnumSet and EnumMap.

The Java Language Specification, §8.9, "Enums" [JLS 2013], does not specify the use of ordinal() in programs. However, attaching external significance to the ordinal() value of an enum constant is error prone and should be avoided for defensive programming.

Noncompliant Code Example

This noncompliant code example declares enum Hydrocarbon and uses its ordinal() method to provide the result of the getNumberOfCarbons() method.:

enum Hydrocarbon {
  METHANE, ETHANE, PROPANE, BUTANE, PENTANE,
  HEXANE, HEPTANE, OCTANE, NONANE, DECANE;

  public int getNumberOfCarbons() {
    return ordinal() + 1;
  }
}

While Although this noncompliant code example worksbehaves as expected, its maintenance is susceptible likely to vulnerabilitiesbe problematic. If the enum constants were reordered, the getNumberOfCarbongetNumberOfCarbons() method would return incorrect values. AlsoFurthermore, BENZENE - which also has 6 carbons - cannot be added without violating the current enum designadding an additional BENZENE constant to the model would break the invariant assumed by the getNumberOfCarbons() method because benzene has six carbons, but the ordinal value 6 is already taken by HEXANE.

Compliant Solution

In this compliant solution, enum constants are explicitly associated with the corresponding integer values for the number of carbon atoms they contain.:

enum Hydrocarbon {
  METHANE(1), ETHANE(2), PROPANE(3), BUTANE(4), PENTANE(5),
  HEXANE(6), BENZENE(6), HEPTANE(7), OCTANE(8), NONANE(9), 
  DECANE(10);

  private final int numberOfCarbons;

  Hydrocarbon(int carbons) { this.numberOfCarbons = carbons; }

  public int getNumberOfCarbons() {
    return numberOfCarbons;
  }
}

Risk Assessment

The getNumberOfCarbons() method no longer uses the ordinal() to discover the number of carbon atoms for each value. Different enum constants may be associated with the same value, as shown for HEXANE and BENZENE. Furthermore, this solution lacks any dependence on the order of the enumeration; the getNumberOfCarbons() method would continue to work even if the enumeration were reordered.

Applicability

It is acceptable to use the ordinals associated with an enumerated type when the order of the enumeration constants is standard and extra constants cannot be added. For example, the use of ordinals is permitted with the following enumerated type:

public enum Day { SUNDAY, MONDAY, TUESDAY, WEDNESDAY, 
                  THURSDAY, FRIDAY, SATURDAY }

In general, use Use of ordinals to derive integer values reduces the program's maintainability and can lead to errors in the program.

Related Guidelines

C Secure Coding Standard: "INT09-C. Ensure enumeration constants map to unique values"

C++ Secure Coding Standard: "INT09-CPP. Ensure enumeration constants map to unique values"

Bibliography

Bibliography

...

Image Added Image Added Image AddedDCL02-J. Enable compile-time type checking of varargs types      01. Declarations and Initialization (DCL)      DCL04-J. Prevent class initialization cycles