</source>

</source>

In my case, this was exactly what I had to do. Only with one problem. The [[enum]] was in signature of an interface, and I could not change that compatibly. I had to design new interface. Introducing the [[AlternativeBehavior]] is transitive change - just to point out the complexity.

In my case, this was exactly what I had to do. Only with one problem. The [[enum]] was in signature of an interface, and I could not change that compatibly. I had to design new interface. Introducing the [[AlternativeBehavior|alternatives]] is transitive change - just to point out the complexity.

== The [[Enum]] Problem ==

== The [[Enum]] Problem ==

[[Good]] [[API]] design is about having [[evolution]] plan prepared in advance. One way of evolving an [[Enum]] is to enlarge the set of its constants. As [[Blogs:AndreiBadea:EnumsInAPIs|Andrei points out]] adding new [[enum]] constant is not strictly semantically [[BackwardCompatible]], but this [[evolution]] path has been well thought in advance when [[Enum]]s were designed.

[[Good]] [[API]] design is about having [[evolution]] plan prepared in advance. One way of evolving an [[Enum]] is to enlarge the set of its constants. As [[Blogs:AndreiBadea:EnumsInAPIs|Andrei points out]] adding new [[enum]] constant is not strictly semantically [[BackwardCompatible]], but this [[evolution]] path has been well thought in advance when [[Enum]]s 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. There are going to be some changes in newer versions - the ''default'' branch may be used more and more often, but overall, there are no surprises. Both sides of the [[API]] contract - the publisher as well as consumer - are ready for this kind of [[evolution]].

Each switch statement (over an [[Enum]]) needs to have ''default'' branch. In case new constants are added, the code ends up in there. There are going to be some changes in newer versions - the ''default'' branch may be used more and more often, but overall, there are no surprises. Both sides of the [[API]] contract - the publisher as well as consumer - are (sort of) ready for this kind of [[evolution]].

== Infinite Set ==

== Infinite Set ==

Shall [[Enum]] be used when designing [[API]]s? Probably yes, but only with care. One has to be aware that it is almost impossible to switch from its finite set of values to infinite number of instances in future.

Shall [[Enum]] be used when designing [[API]]s? Probably yes, but only with care. One has to be aware that it is almost impossible to switch from its finite set of values to infinite number of instances in future.

The root cause of the problems seem to be the existence of a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html Enum] super class that every [[enum]] automatically inherits from. Knowing all I know now, it would be better to use [[DelegationAndComposition]] rather than inheritance. If the compiler emitted code which inherits directly from '''Object''', it would be much easier to replace the keyword '''enum''' in class definition by keyword '''class''', while remaining compatible (one would need to implement few methods manually and make sure serialization works). With approach like this, it would be harder to properly type [http://download.oracle.com/javase/6/docs/api/java/util/EnumMap.html EnumMap], but who needs proper types in this case anyway? It would be enough to have [[factory]] method to support the same use case:

The root cause of the problems seem to be the existence of a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html Enum] super class that every [[enum]] automatically inherits from. Knowing all I know now, it would be better to use [[DelegationAndComposition]] rather than inheritance. If the compiler emitted code which inherits directly from '''Object''', it would be much easier to replace the keyword '''enum''' in class definition by keyword '''class''', while remaining compatible (one would need to implement few methods manually and make sure serialization works).

 

I know only one reason why the [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html Enum] superclass is handy. It is possible to properly type [http://download.oracle.com/javase/6/docs/api/java/util/EnumMap.html EnumMap]. But who needs proper types in this case anyway? It would be enough to have [[factory]] method to support the same use case:

<source lang="java">

<source lang="java">

</source>

</source>

The [[Enum]] design as of [[Java]] 5 is associated with significant [[evolution]] flaws. When designing [[API]]s, use [[Enum]]s with care!

In summary: The [[Enum]] design as of [[Java]] 5 is associated with significant [[evolution]] flaws caused by artificial requirement to extend a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html super class]. Thus, when designing [[API]]s, use [[Enum]]s with care!

<comments/>

<comments/>

Shall [[Enum]] be used when designing [[API]]s? Probably yes, but only with care. One has to be aware that it is almost impossible to switch from its finite set of values to infinite number of instances in future.

Shall [[Enum]] be used when designing [[API]]s? Probably yes, but only with care. One has to be aware that it is almost impossible to switch from its finite set of values to infinite number of instances in future.

The root cause of the problems seem to be the existence of a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html Enum] super class that every [[enum]] automatically inherits from. Knowing all I know now, it would be better to use [[DelegationAndComposition]] rather than inheritance. If the compiler emitted code which inherits directly from '''Object''', it would be much easier to replace the keyword '''enum''' in class definition by keyword '''class''', while remaining compatible. With approach like this, it would be harder to properly type [http://download.oracle.com/javase/6/docs/api/java/util/EnumMap.html EnumMap], but who needs proper types in this case anyway? It would be enough to have [[factory]] method to support the same use case:

The root cause of the problems seem to be the existence of a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html Enum] super class that every [[enum]] automatically inherits from. Knowing all I know now, it would be better to use [[DelegationAndComposition]] rather than inheritance. If the compiler emitted code which inherits directly from '''Object''', it would be much easier to replace the keyword '''enum''' in class definition by keyword '''class''', while remaining compatible (one would need to implement few methods manually and make sure serialization works). With approach like this, it would be harder to properly type [http://download.oracle.com/javase/6/docs/api/java/util/EnumMap.html EnumMap], but who needs proper types in this case anyway? It would be enough to have [[factory]] method to support the same use case:

<source lang="java">

<source lang="java">

</source>

</source>

Too bad this cannot be done with classes! [[Java]] classes can have just one superclass and in case of [[enum]]s it is restricted to ''java.lang.Enum''.

Too bad this cannot be done with classes! [[Java]] classes can have just one superclass. In the case of [[enum]]s the superclass is restricted to [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html Enum].

In any case, the problem does not stop with the definition of ''NewCategory''. One also needs to duplicate all the methods that accept or return the ''OldCategory'' with their new versions that deals with ''NewCategory'':

In any case, the problem does not stop with the definition of ''NewCategory''. One also needs to duplicate all the methods that accept or return the ''OldCategory'' with their new versions that deals with ''NewCategory'':

}

}

</source>

</source>

Some people may prefer to define ''NewCategory'' as [[Java]] interface. I don't like usage of [[Java]] interfaces for [[ClientAPI]] as there are problems associated with [[ExtendingInterfaces|extending such interfaces]], but in this case pure [[Java]] interface is the only option if one wants to retrofit the ''OldCategory'' to implement the new interface as well.

Some people may prefer to define ''NewCategory'' as [[Java]] interface. I don't like usage of [[Java]] interfaces for [[ClientAPI]] as there are problems associated with [[ExtendingInterfaces|extending such interfaces]], but in this case pure [[Java]] interface is the only option if one wants to retrofit the ''OldCategory'' to implement the new interface as well (and get rid of ''fromOld'' and ''toOld'' conversion methods).

<source lang="java">

<source lang="java">

}

}

</source>

</source>

Some people may prefer to define ''NewCategory'' as [[Java]] interface. Then it is possible to retrofit the ''OldCategory'' to implement this interface as well. Too bad this cannot be done with classes! [[Java]] classes can have just one superclass and in case of [[enum]]s it is restricted to ''java.lang.Enum''.

Some people may prefer to define ''NewCategory'' as [[Java]] interface. I don't like usage of [[Java]] interfaces for [[ClientAPI]] as there are problems associated with [[ExtendingInterfaces|extending such interfaces]], but in this case pure [[Java]] interface is the only option if one wants to retrofit the ''OldCategory'' to implement the new interface as well.

 

 

 

Too bad this cannot be done with classes! [[Java]] classes can have just one superclass and in case of [[enum]]s it is restricted to ''java.lang.Enum''.

In any case, the problem does not stop with the definition of ''NewCategory''. One also needs to duplicate all the methods that accept or return the ''OldCategory'' with their new versions that deals with ''NewCategory'':

In any case, the problem does not stop with the definition of ''NewCategory''. One also needs to duplicate all the methods that accept or return the ''OldCategory'' with their new versions that deals with ''NewCategory'':

<source lang="java">

<source lang="java">

// old method

// old method

public OldCategory getCategory();

public OldCategory findMoreStable(OldCategory...);

// new method

// new method

public NewCategory getBetterCategory();

public NewCategory findMoreStable(NewCategory...);

</source>

</source>

In my case, this was exactly what I had to do. Only with one problem. The [[enum]] was in signature of an interface, and I could not change that compatibly, so I would need to design new interface. Introducing the [[AlternativeBehavior]] is transitive change - just to point out the complexity.

In my case, this was exactly what I had to do. Only with one problem. The [[enum]] was in signature of an interface, and I could not change that compatibly. I had to design new interface. Introducing the [[AlternativeBehavior]] is transitive change - just to point out the complexity.

== The [[Enum]] Problem ==

== The [[Enum]] Problem ==

Shall [[Enum]] be used when designing [[API]]s? Probably yes, but only with care. One has to be aware that it is almost impossible to switch from its finite set of values to infinite number of instances in future.

Shall [[Enum]] be used when designing [[API]]s? Probably yes, but only with care. One has to be aware that it is almost impossible to switch from its finite set of values to infinite number of instances in future.

The root cause of the problems seem to be the existence of a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html super class] that every [[enum]] automatically inherits from. Knowing all I know now, it would be better to use [[DelegationAndComposition]] rather than inheritance. If the compiler emitted code which inherits directly from '''Object''', it would be much easier to replace the ''enum'' in class definition by ''class'', while remaining compatible. With approach like this, it would be harder to properly type [http://download.oracle.com/javase/6/docs/api/java/util/EnumMap.html EnumMap], but who needs proper types in this case anyway? It would be enough to have ''Collections.efficientMap(Class<?> keys, Class<?> values)'' [[factory]] method to support the same use case.

The root cause of the problems seem to be the existence of a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html Enum] super class that every [[enum]] automatically inherits from. Knowing all I know now, it would be better to use [[DelegationAndComposition]] rather than inheritance. If the compiler emitted code which inherits directly from '''Object''', it would be much easier to replace the keyword '''enum''' in class definition by keyword '''class''', while remaining compatible. With approach like this, it would be harder to properly type [http://download.oracle.com/javase/6/docs/api/java/util/EnumMap.html EnumMap], but who needs proper types in this case anyway? It would be enough to have [[factory]] method to support the same use case:

 

public static <K,V> Map<K,V> Collections.efficientMap(Class<K> keys, Class<V> values)

The [[Enum]] design as of [[Java]] 5 is associated with significant [[evolution]] flaws. When designing [[API]]s, use [[Enum]]s with care!

The [[Enum]] design as of [[Java]] 5 is associated with significant [[evolution]] flaws. When designing [[API]]s, use [[Enum]]s with care!

<comments/>

<comments/>

==== Rewrite Cookbook ====

==== Rewrite Cookbook ====

Options? At most to provide [[AlternativeBehavior]]:

Options? Not many. Most promissing is to provide [[AlternativeBehavior|alternatives]] by creating new type to represent the same functionality:

# design new type to represent the new functionality

# optionally change the [[enum]] definition to implement the type (but then the type has to be [[Java]] interface, it cannot be a class!)

public enum OldCategory {

# duplicate all the methods that deal with the [[enum]] to also accept or produce the new type (this has to be done transitively)

public String getDisplayName();

 

 

 

 

Some people may prefer to define ''NewCategory'' as [[Java]] interface. Then it is possible to retrofit the ''OldCategory'' to implement this interface as well. Too bad this cannot be done with classes! [[Java]] classes can have just one superclass and in case of [[enum]]s it is restricted to ''java.lang.Enum''.

 

In any case, the problem does not stop with the definition of ''NewCategory''. One also needs to duplicate all the methods that accept or return the ''OldCategory'' with their new versions that deals with ''NewCategory'':

public OldCategory getCategory();

In my case, this was exactly what I had to do. Only with one problem. The [[enum]] was in signature of an interface, and I could not change that compatibly, so I would need to design new interface. Introducing the [[AlternativeBehavior]] is transitive change - just to point out the complexity.

In my case, this was exactly what I had to do. Only with one problem. The [[enum]] was in signature of an interface, and I could not change that compatibly, so I would need to design new interface. Introducing the [[AlternativeBehavior]] is transitive change - just to point out the complexity.

Shall [[Enum]] be used when designing [[API]]s? Probably yes, but only with care. One has to be aware that it is almost impossible to switch from its finite set of values to infinite number of instances in future.

Shall [[Enum]] be used when designing [[API]]s? Probably yes, but only with care. One has to be aware that it is almost impossible to switch from its finite set of values to infinite number of instances in future.

The root cause of the problems seem to be the existence of a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html super class] that every [[enum]] automatically inherits from. Knowing all I know now, it would be better to use [DelegationAndComposition]] rather than inheritance. If the compiler emitted code which inherits directly from '''Object''', it would be much easier to replace the ''enum'' in class definition by ''class'', while remaining compatible. With approach like this, it would be harder to properly type [http://download.oracle.com/javase/6/docs/api/java/util/EnumMap.html EnumMap], but who needs proper types in this case anyway? It would be enough to have ''Collections.efficientMap(Class<?> keys, Class<?> values)'' [[factory]] method to support the same use case.

The root cause of the problems seem to be the existence of a marker [http://download.oracle.com/javase/6/docs/api/java/lang/Enum.html super class] that every [[enum]] automatically inherits from. Knowing all I know now, it would be better to use [[DelegationAndComposition]] rather than inheritance. If the compiler emitted code which inherits directly from '''Object''', it would be much easier to replace the ''enum'' in class definition by ''class'', while remaining compatible. With approach like this, it would be harder to properly type [http://download.oracle.com/javase/6/docs/api/java/util/EnumMap.html EnumMap], but who needs proper types in this case anyway? It would be enough to have ''Collections.efficientMap(Class<?> keys, Class<?> values)'' [[factory]] method to support the same use case.

The [[Enum]] design as of [[Java]] 5 is associated with significant [[evolution]] flaws. When designing [[API]]s, use [[Enum]]s with care!

The [[Enum]] design as of [[Java]] 5 is associated with significant [[evolution]] flaws. When designing [[API]]s, use [[Enum]]s with care!

<comments/>

<comments/>