Not all public classes and methods in the
files and other JAR files shipped with BASE are considered as
Public API. This is important knowledge
since we will always try to maintain backwards compatibility
for classes that are part of the public API. For other
classes, changes may be introduced at any time without
notice or specific documentation. In other words:
|Only use the public API when developing plug-ins and extensions|
This will maximize the chance that your code will continue to work with the next BASE release. If you use the non-public API you do so at your own risk.
See the BASE API javadoc for information about
what parts of the API that contributes to the public API.
Methods, classes and other elements that have been tagged as
@deprecated should be considered as part of the internal API
and may be removed in a subsequent release without warning.
Keeping the backwards compatibility is an aim only. It may not always be possible. See Appendix I, API changes that may affect backwards compatibility to read more about changes that have been introduced by each release that may affect existing code.
There is a great article about this subject on http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs. This is what we will try to comply with. If you do not want to read the entire article, here are some of the most important points:
Pre-existing Client binaries must link and run with new releases of the Component without recompiling.
We cannot change the number or types of parameters to a method or constructor.
We cannot add or change methods to interfaces that are intended to be implemented by plug-in or client code.
API changes must not invalidate formerly legal Client code.
We cannot change the implementation of a method to do
things differently than before. For example, allow
as a return value when it was not allowed before.
Sometimes there is a very fine line between what is considered a bug and what is considered a feature. For example, if the actual implementation does not do what the javadoc says, do we change the code or do we change the documentation? This has to be considered from case to case and depends on the age of the code and if we expect plug-ins and clients to be affected by it or not.