Enum

From APIDesign

Java has been enhanced with enums in version 1.5. The Enums greatly simplify and standardize the way one can express the enumerated types in Java. However since their introduction I was not sure how suitable they are for API Design (I was not the only one, see few year's old Andrei's post). Today I finished one Enum related API change for NetBeans, and I felt all the pain. I guess I understand now what is wrong with Enums in APIs.

Growing Set

Designing API in proper way is about having prepared evolution plan in advance. One way of evolving an Enum is to enlarge the set of its constants. As Andrei points out adding new enum constant is not strictly semantically BackwardCompatible, but this evolution path has been well thought in advance when Enums were designed.

Each switch statement (over an Enum) needs to have default branch. In case new constants are added, the code ends up in there. The behaviour may slightly change with newer versions, the default branch may be used more and more often, but overall, there are no surprises. Neither on API publisher, neither on API consumer side.

Infinite Set

The real problem starts when you find out that finite amount is not enough, then the Java Enum design starts to stay in the way.

This is not as rare situation as you may think. Often one starts with Singleton instance and evolves it to multiple instances in subsequent releases of the API. Doing the same with Enum is impossible.

There are online sources of modules in NetBeans applications. They can be classified according to their stability to Standard, Beta and Community. Over time it turned out that such classification is too restrictive and I got a request to allow users of the API to define their own stability categories together with associated icons. Easy task, one may think. Basically just add new Factory method, right?

Well, it would be an easy task. If the stability category class was not originally declared as Enum!

But nobody is allowed to dynamically create instances of Enums. It is forbidden by Java compiler. Even resolving to reflection does not help, as the Constructor.newInstance has a special check for Enum subclasses and throws an exception. No luck.

What can one do? Stop extending the Enum class? But that is horribly backward incompatible! Before that people could assign instances of the class to Enum variables. Or use EnumSet with instances of that class. After stopping to extend the Enum marker class, nothing like this is no longer possible.

Options? At most to provide AlternativeBehavior.