Introduction

This document lists changes made to the Diff APIs. Please ask on the nbdev@netbeans.org mailing list if you have any questions about the details of a change, or are wondering how to convert existing code to be compatible.

In general the NetBeans core API team has several responsibilities:

  1. Avoid incompatible changes to the APIs whenever possible. This refers to both literal incompatibilities to the signatures of accessible API classes (including both source compatibility and binary compatibility, which sometimes differ); and semantic incompatibilities, for example changes in threading behavior of a method call.
  2. Document all API changes, incompatible or compatible, in this document, with proper explanation of the change and timestamp, and document the changes at the same time the actual change is made.
  3. Maintain API documentation so that it is up-to-date with respect to the actual APIs, both in prose documentation and Javadoc. When an API feature is ambiguously described, clarify the documentation to state precisely what it is expected to do; it is acceptable to specify that some aspect of its behavior is undefined, provided this is explicitly documented. If a feature is publicly accessible only for unavoidable technical reasons, document that this is so, and who is permitted to actually make use of it.
  4. Annotate new APIs with their time of addition: in Javadoc using the @since tag, or as appropriate in prose. The annotation should include both the date, and the current OpenIDE specification version, to make it easy for module authors to depend on the new API.
  5. Announce API changes on the mailing list; incompatible changes must be announced in advance to give any users of the old API a chance to veto the change.
  6. Be prepared to publicly explain the meaning and intended use of an API feature, and defend changes to it if requested.
  7. Assist anyone posting to the mailing list in fixing their code to be compatible with a change, if this is necessary and desired.
  8. Provide a workaround to restore compatibility for a previously incompatible API change, if this is requested on the mailing list and deemed feasible.
  9. Minimize the size of the APIs by rejecting compatible changes which substantially increase complexity and are not strictly needed.
  10. Attempt to maintain an API design which permits interesting and useful changes to be compatible.
  11. Attempt to cluster incompatible changes into infrequent batches of changes, specified and discussed well in advance, to be applied when making a new major release of the IDE. This should be done to remove previously deprecated features with a longstanding better alternative, and otherwise to enhance the clarity, consistency, and flexibility of the APIs.
  12. Make changes only on the trunk, not stabilization branches. When an API change is required in a stabilization branch to support an important bug fix, explicitly mention that in this document. (Bug fixes to API-related code not affecting its signature or documented semantics may be made at any time.)
  13. Increase the OpenIDE specification version listed in the core whenever a compatible API change is made, if some module is also being changed to take advantage of a newer API. The module should then list a dependency on the newer specification version in its manifest, to ensure that the newer version of the module is not accidentally run on an API-older core. Confirm that the specification version is also bumped up both before and after a branch is made which affects the APIs, to ensure that API changes can be cleanly ordered relative to branch points.

What do the Dates Mean?

The supplied dates indicate when the API change was made, on the CVS trunk. From this you can generally tell whether the change should be present in a given build or not; for trunk builds, simply whether it was made before or after the change; for builds on a stabilization branch, whether the branch was made before or after the given date. In some cases corresponding API changes have been made both in the trunk and in an in-progress stabilization branch, if they were needed for a bug fix; this ought to be marked in this list.


Index of APIs

Incompatible changes by date

Fuller descriptions of all changes can be found below (follow links).

Not all deprecations are listed here, assuming that the deprecated APIs continue to essentially work. For a full deprecation list, please consult the Javadoc.

All changes by date

Changes by version

These API specification versions may be used to indicate that a module requires a certain API feature in order to function. For example, if you see here a feature you need which is labelled 1.20, your manifest should contain in its main attributes the line:

OpenIDE-Module-Module-Dependencies: org.netbeans.modules.diff/1 > 1.20

Changes by affected class


Details of all changes by API and date


Diff API

Show compact diff with netbeans.diff.default.compact system property

May 2 '18; API spec. version: 1.52; made by: emi
Added the system property netbeans.diff.default.compact which instructs the default DiffControllerProvider to show only the graphical diff (instead of the tabbed pane with the graphical and textual diffs).

Enhanced UI in diff views

Mar 4 '10; API spec. version: 1.27; made by: ovrabec
Adding new methods to the API/SPI which create a Diff Controller capable of providing a diff view with enhanced UI.

New DiffController API

Jul 7 '09; API spec. version: 1.19; made by: tstupka
Adding PatchUtils.java to the API. Contains two new methods - isPatch(patchFile) and applyPatch(patchFile, contextFile)

New DiffController API

Apr 17 '07; API spec. version: 1.18; made by: msandor
DiffController class is a successor to DiffView interface that provides more features.

StreamSource extended

Feb 21 '07; API spec. version: 1.17; made by: msandor
StreamSource provides more ways of defining the source (a FileObject) and can declare its editability.

DiffView interface added

May 23 '05; API spec. version: 1.13; made by: mentlicher
A controler interface, that allows to programmatically control the diff component.

StreamSource class added

Apr 24 '02; API spec. version: 1.4; made by: mentlicher
Class, that is used as a source of named streams for diff and merge stuff.

The Diff APIs created

Feb 18 '02; API spec. version: 1.3; made by: mentlicher
The base classes adedd.

Merge API

MergeVisualizer class added

Apr 24 '02; API spec. version: 1.5; made by: mentlicher
Service, that is used to resolve merge collisions.