Blogs:AndreiBadea:EnumsInAPIs - Revision history

JaroslavTulach: /* Enums in APIs */

JaroslavTulach — Sun, 09 Jan 2011 17:25:32 GMT

Enums in APIs

←Older revision		Revision as of 17:25, 9 January 2011
Line 1:		Line 1:
-	== ~~Enums~~ in APIs ==	+	== [[Enum]]s in APIs ==

	As Jesse [[Blogs:JesseGlick:OfClassesAndInterfaces\|explains]], a client API should generally use final classes, which, among other advantages, are more flexible from the API maintainer's point of view. Particularly, adding a new field or method to a final class is a backward-compatible operation. There is no risk of clash with a method or field added by the user of the API, because the user can't add anything to the class.		As Jesse [[Blogs:JesseGlick:OfClassesAndInterfaces\|explains]], a client API should generally use final classes, which, among other advantages, are more flexible from the API maintainer's point of view. Particularly, adding a new field or method to a final class is a backward-compatible operation. There is no risk of clash with a method or field added by the user of the API, because the user can't add anything to the class.

-	A particular example of a final class is an enum. It would thus appear that adding new fields to an enum is a backward-compatible operation. Or is it?	+	A particular example of a final class is an [[enum]]. It would thus appear that adding new fields to an [[enum]] is a backward-compatible operation. Or is it?

-	Let's assume the following common code where a switch statements walks over all fields of the enum:	+	Let's assume the following common code where a switch statements walks over all fields of the [[enum]]:

	<source lang="java">		<source lang="java">
Line 18:		Line 18:
	</source>		</source>

-	Ignore for the moment the fact that such code is better replaced with an instance method on the enum itself. Users tend to come up with creative ways to use your API, or could simply be working around the method missing from the API.	+	Ignore for the moment the fact that such code is better replaced with an instance method on the [[enum]] itself. Users tend to come up with creative ways to use your API, or could simply be working around the method missing from the API.

-	The <tt>assert false</tt> statement in the default branch is commonly used to ensure that all fields have been considered. However, if in the next version of the API <tt>FIELD3</tt> is added to the enum, this code could suddenly start throwing an <tt>AssertionError</tt>. Code which worked fine in the previous version breaks down in the new version, although it compiles and links successfully. So, adding fields to a public enum is a semantically incompatible change.	+	The <tt>assert false</tt> statement in the default branch is commonly used to ensure that all fields have been considered. However, if in the next version of the API <tt>FIELD3</tt> is added to the [[enum]], this code could suddenly start throwing an <tt>AssertionError</tt>. Code which worked fine in the previous version breaks down in the new version, although it compiles and links successfully. So, adding fields to a public [[enum]] is a semantically incompatible change.

-	I don't see a solution which would satisfy both the user and the provider of the API. Either the user doesn't assume that he knows which fields there are in the enum, or the provider freezes the enum once published. The latter seems to restrict the evolution of the API, so it is probably less practical. What do you think?	+	I don't see a solution which would satisfy both the user and the provider of the API. Either the user doesn't assume that he knows which fields there are in the [[enum]], or the provider freezes the [[enum]] once published. The latter seems to restrict the evolution of the API, so it is probably less practical. What do you think?

	--[[User:AndreiBadea\|AndreiBadea]] 14:08, 16 July 2008 (UTC)		--[[User:AndreiBadea\|AndreiBadea]] 14:08, 16 July 2008 (UTC)

	<comments/>		<comments/>

AndreiBadea at 14:13, 16 July 2008

AndreiBadea — Wed, 16 Jul 2008 14:13:28 GMT

←Older revision		Revision as of 14:13, 16 July 2008
Line 18:		Line 18:
	</source>		</source>

-	Ignore for the moment the fact that such code is better replaced with an instance method on the enum itself. ~~Remember, you don't own the enum, and users~~ tend to come up with creative ways to use your API.	+	Ignore for the moment the fact that such code is better replaced with an instance method on the enum itself. Users tend to come up with creative ways to use your API, or could simply be working around the method missing from the API.

	The <tt>assert false</tt> statement in the default branch is commonly used to ensure that all fields have been considered. However, if in the next version of the API <tt>FIELD3</tt> is added to the enum, this code could suddenly start throwing an <tt>AssertionError</tt>. Code which worked fine in the previous version breaks down in the new version, although it compiles and links successfully. So, adding fields to a public enum is a semantically incompatible change.		The <tt>assert false</tt> statement in the default branch is commonly used to ensure that all fields have been considered. However, if in the next version of the API <tt>FIELD3</tt> is added to the enum, this code could suddenly start throwing an <tt>AssertionError</tt>. Code which worked fine in the previous version breaks down in the new version, although it compiles and links successfully. So, adding fields to a public enum is a semantically incompatible change.

AndreiBadea at 14:08, 16 July 2008

AndreiBadea — Wed, 16 Jul 2008 14:08:36 GMT

←Older revision		Revision as of 14:08, 16 July 2008
Line 23:		Line 23:

	I don't see a solution which would satisfy both the user and the provider of the API. Either the user doesn't assume that he knows which fields there are in the enum, or the provider freezes the enum once published. The latter seems to restrict the evolution of the API, so it is probably less practical. What do you think?		I don't see a solution which would satisfy both the user and the provider of the API. Either the user doesn't assume that he knows which fields there are in the enum, or the provider freezes the enum once published. The latter seems to restrict the evolution of the API, so it is probably less practical. What do you think?
		+
		+	--[[User:AndreiBadea\|AndreiBadea]] 14:08, 16 July 2008 (UTC)

	<comments/>		<comments/>

AndreiBadea: New page: == Enums in APIs == As Jesse explains, a client API should generally use final classes, which, among other advantages, are more flexible from t...

AndreiBadea — Wed, 16 Jul 2008 14:07:22 GMT

New page: == Enums in APIs == As Jesse explains, a client API should generally use final classes, which, among other advantages, are more flexible from t...

New page

== Enums in APIs ==

As Jesse [[Blogs:JesseGlick:OfClassesAndInterfaces|explains]], a client API should generally use final classes, which, among other advantages, are more flexible from the API maintainer's point of view. Particularly, adding a new field or method to a final class is a backward-compatible operation. There is no risk of clash with a method or field added by the user of the API, because the user can't add anything to the class.

A particular example of a final class is an enum. It would thus appear that adding new fields to an enum is a backward-compatible operation. Or is it?

Let's assume the following common code where a switch statements walks over all fields of the enum:

<source lang="java">
switch (e) {
case FIELD1:
return "field1";
case FIELD2:
return "field2";
default:
assert false;
}
</source>

Ignore for the moment the fact that such code is better replaced with an instance method on the enum itself. Remember, you don't own the enum, and users tend to come up with creative ways to use your API.

The <tt>assert false</tt> statement in the default branch is commonly used to ensure that all fields have been considered. However, if in the next version of the API <tt>FIELD3</tt> is added to the enum, this code could suddenly start throwing an <tt>AssertionError</tt>. Code which worked fine in the previous version breaks down in the new version, although it compiles and links successfully. So, adding fields to a public enum is a semantically incompatible change.

I don't see a solution which would satisfy both the user and the provider of the API. Either the user doesn't assume that he knows which fields there are in the enum, or the provider freezes the enum once published. The latter seems to restrict the evolution of the API, so it is probably less practical. What do you think?

<comments/>