Not all public classes and methods in the base-*.jar 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.

29.1.1. What is backwards compatibility?

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:

Binary compatibility

Pre-existing Client binaries must link and run with new releases of the Component without recompiling.

For example:

• 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.

Contract compatibility

API changes must not invalidate formerly legal Client code.

For example:

• We cannot change the implementation of a method to do things differently than before. For example, allow null as a return value when it was not allowed before.

	Note
	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.

Source code compatibility

This is not an important matter and is not always possible to achieve. In most cases, the problems are easy to fix. Example:

• Adding a class may break a plug-in or client that import classes with .* if the same class name exists in another package.