Version compatibility of Commons Collections
This page details the compatibility of different collections releases.
There are two types of compatibility discussed here, source and binary.
-
Two versions are source compatible when application code can be compiled
against either version successfully. The compilation may result in deprecation warnings
but that is perfectly acceptable.
When code is source incompatible, it fails to compile, thus this type of incompatibility is easy to find.
-
Two versions are binary compatible when application code compiled against
one version will run using the other version without recompilation.
This is much more difficult to test for, and follows quite complicated rules from the
Java language.
Releases of commons collections aim to be source and binary compatible within minor versions,
and to avoid breakages as much as possible between major versions.
Commons collections 3.0 is source compatible with version 2.1 and 2.0 with the exception
of classes previously deprecated in 2.0/2.1 (which were removed in 3.0).
Commons collections 3.0 is binary compatible with version 2.1 and 2.0
except for certain methods on one class.
As the release was a major version, this is permitted, however it was unintentional and an error.
The problem is in the IteratorUtils class (see methods below).
(Strictly speaking, there are some minor incompatibilities on other classes, but these
changes were deliberate and have not caused any known issues.)
It is not possible to make v2.1 and v3.0 compatible without further binary incompatibility.
The chosen solution is to provide a workaround by releasing v2.1.1 and v3.1.
The following deprecations must be resolved in v2.1.1 to allow compatibility with v3.1.
- Deprecated
IteratorUtils.arrayIterator(...) -
use new ArrayIterator(...) instead
- Deprecated
IteratorUtils.singletonIterator(...) -
use new SingletonIterator(...) instead
- Deprecated
IteratorUtils.emptyIterator() -
use EmptyIterator.INSTANCE instead
- Deprecated
IteratorUtils.emptyListIterator() -
use EmptyListIterator.INSTANCE instead
- Deprecated
IteratorUtils.EMPTY_ITERATOR -
use EmptyIterator.INSTANCE instead
- Deprecated
IteratorUtils.EMPTY_LIST_ITERATOR -
use EmptyIterator.INSTANCE instead
For the future, a new tool clirr is being developed
to help spot binary incompatibility before release.
|