Enum - Revision history

JaroslavTulach: /* Rewrite Cookbook */

2011-01-12T22:12:38Z

Rewrite Cookbook

←Older revision		Revision as of 22:12, 12 January 2011
Line 65:		Line 65:
	</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 ==

JaroslavTulach: /* Growing Set */

2011-01-12T22:06:54Z

Growing Set

←Older revision		Revision as of 22:06, 12 January 2011
Line 5:		Line 5:
	[[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 ==

JaroslavTulach: /* The Enum Problem */

2011-01-11T13:09:54Z

The Enum Problem

←Older revision		Revision as of 13:09, 11 January 2011
Line 71:		Line 71:
	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">
Line 79:		Line 81:
	</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/>

JaroslavTulach: /* The Enum Problem */

2011-01-11T13:07:02Z

The Enum Problem

←Older revision		Revision as of 13:07, 11 January 2011
Line 71:		Line 71:
	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">

JaroslavTulach at 13:05, 11 January 2011

2011-01-11T13:05:01Z

←Older revision		Revision as of 13:05, 11 January 2011
Line 55:		Line 55:
	</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'':

JaroslavTulach: /* Rewrite Cookbook */

2011-01-11T13:03:32Z

Rewrite Cookbook

←Older revision		Revision as of 13:03, 11 January 2011
Line 42:		Line 42:
	}		}
	</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">

JaroslavTulach: /* Rewrite Cookbook */

2011-01-11T13:02:07Z

Rewrite Cookbook

←Older revision		Revision as of 13:02, 11 January 2011
Line 42:		Line 42:
	}		}
	</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.
		+
		+	<source lang="java">
		+	public enum OldCategory implements NewCategory {
		+	public String getDisplayName();
		+	public static NewCategory create(String name);
		+	}
		+
		+	public interface NewCategory {
		+	public String getDisplayName();
		+	}
		+	</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''.

	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 ==

94.113.131.113: /* The Enum Problem */

2011-01-10T18:43:35Z

The Enum Problem

←Older revision		Revision as of 18:43, 10 January 2011
Line 58:		Line 58:
	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:
		+
		+	<source lang="java">
		+	/** If the K class is enum, the map is effective, otherwise it is just regular HashMap
		+	*/
		+	public static <K,V> Map<K,V> Collections.efficientMap(Class<K> keys, Class<V> values)
		+	</source>

	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/>

94.113.131.113: /* Rewrite Cookbook */

2011-01-10T18:38:42Z

Rewrite Cookbook

←Older revision		Revision as of 18:38, 10 January 2011
Line 25:		Line 25:
	==== 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	+	<source lang="java">
-	~~# 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();
		+	}
		+
		+	public class NewCategory {
		+	private NewCategory() {}
		+
		+	public String getDisplayName();
		+
		+	public static NewCategory fromOld(OldCategory from);
		+	public OldCategory toOld();
		+
		+	public static NewCategory create(String name);
		+	}
		+	</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''.
		+
		+	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">
		+	// old method
		+	public OldCategory getCategory();
		+	// new method
		+	public NewCategory getBetterCategory();
		+	</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, so I would need to design new interface. Introducing the [[AlternativeBehavior]] is transitive change - just to point out the complexity.

JaroslavTulach: /* The Enum Problem */

2011-01-10T08:37:57Z

The Enum Problem

←Older revision		Revision as of 08:37, 10 January 2011
Line 36:		Line 36:
	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/>