|
|
| Line 1: |
Line 1: |
| − | 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. | + | This page was used to capture notes and discussions about API evolution guidelines in Java 5. These notes have now been folded into a new revision of the [[Evolving Java-based APIs]] document, so this page is no longer needed. |
| − | | + | |
| − | == 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 [[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 14:36, 31 October 2006
This page was used to capture notes and discussions about API evolution guidelines in Java 5. These notes have now been folded into a new revision of the Evolving Java-based APIs document, so this page is no longer needed.
Back to API Central
