Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Notes on Evolving APIs in Java 5"
(→Generics) |
|||
| Line 3: | Line 3: | ||
== Generics == | == Generics == | ||
| − | Generics do not exist in the binary | + | Generics do not exist in the binary signature of a class. Thus, binary compatibility of a class containing generics is reduced to compatibility of the [[http://java.sun.com/docs/books/jls/third_edition/html/typesValues.html#108979 erasure]] of the generic types. General rule: the left-most bound of a generic type within API can never be changed. Bounds other than the left-most bound can be weakened without sacrificing compatibility. |
| + | == Enumerations == | ||
| + | |||
| + | An enumeration is just a class, and each constant is an anonymous instance of that class. Thus, all binary compatibility rules for classes also apply to enumerations. If an enumeration declares public fields or methods, they are considered API. Unlike normal classes, clients cannot subclass enums, so protected methods and fields on an enumeration are not considered API. | ||
| + | |||
| + | It is possible that clients rely on the order in which enumerations are defined, because this order is exposed in the values() method generated by the compiler. Thus while reordering enumeration constants is a binary compatible change, it is a change that breaks contract compatibility [question: is enumeration constant order part of the implicit contract of an enumeration?]. | ||
| + | |||
| + | Adding enumeration constants, methods, or fields to an API enumeration is not a breaking change. | ||
---- | ---- | ||
Back to [[API Central]] | Back to [[API Central]] | ||
Revision as of 10:32, 18 October 2006
This page captures notes and discussions about API evolution guidelines in Java 5. The eventual output of these notes will be an update to the Evolving Java-based APIs document.
Generics
Generics do not exist in the binary signature of a class. Thus, binary compatibility of a class containing generics is reduced to compatibility of the [erasure] of the generic types. General rule: the left-most bound of a generic type within API can never be changed. Bounds other than the left-most bound can be weakened without sacrificing compatibility.
Enumerations
An enumeration is just a class, and each constant is an anonymous instance of that class. Thus, all binary compatibility rules for classes also apply to enumerations. If an enumeration declares public fields or methods, they are considered API. Unlike normal classes, clients cannot subclass enums, so protected methods and fields on an enumeration are not considered API.
It is possible that clients rely on the order in which enumerations are defined, because this order is exposed in the values() method generated by the compiler. Thus while reordering enumeration constants is a binary compatible change, it is a change that breaks contract compatibility [question: is enumeration constant order part of the implicit contract of an enumeration?].
Adding enumeration constants, methods, or fields to an API enumeration is not a breaking change.
Back to API Central