Introduction
This document lists changes made to the Diff
APIs. Please ask on the [email protected] 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:
- 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.
- 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.
- 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.
-
Annotate new APIs with their time of addition: in Javadoc using
the
@sincetag, 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. - 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.
- Be prepared to publicly explain the meaning and intended use of an API feature, and defend changes to it if requested.
- Assist anyone posting to the mailing list in fixing their code to be compatible with a change, if this is necessary and desired.
- Provide a workaround to restore compatibility for a previously incompatible API change, if this is requested on the mailing list and deemed feasible.
- Minimize the size of the APIs by rejecting compatible changes which substantially increase complexity and are not strictly needed.
- Attempt to maintain an API design which permits interesting and useful changes to be compatible.
- 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.
- 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.)
- 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.
-
The
release33branch was made on Nov 23 '01 for use in the NetBeans 3.3.1 release, and later for development of Forte for Java (codename Orion). -
The
release330branch was made on Nov 23 '01 for use in the NetBeans 3.3 release. -
The
release32branch was made on Mar 10 '01 for use in the NetBeans 3.2 release, and later for NetBeans 3.2.1 and Forte for Java 3.0. -
The
release31branch was made on Nov 7 '00 for use in the NetBeans 3.1 release. -
The
bostonbranch was made on Jun 29 '00 and used for betas and the FCS of Forte for Java 2.0. A number of API changes made after this date have in fact been incorporated into the branch. -
All changes listed here were made after the
postfcsbranch, which produced the Forte for Java 8xx series builds (1.0.x FCS and betas) and also the NetBeans 3.0 release. So they do not apply to these builds; this version of the change list was started immediately after this branch was made (early Feb '00).
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.
All changes by date
- (May 2 '18) Show compact diff with netbeans.diff.default.compact system property
- (Mar 4 '10) Enhanced UI in diff views
- (Jul 7 '09) New DiffController API
- (Apr 17 '07) New DiffController API
- (Feb 21 '07) StreamSource extended
- (May 23 '05) DiffView interface added
- (Apr 24 '02) StreamSource class added
- (Apr 24 '02) MergeVisualizer class added
- (Feb 18 '02) The Diff APIs created
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
- (1.52) Show compact diff with netbeans.diff.default.compact system property
- (1.27) Enhanced UI in diff views
- (1.19) New DiffController API
- (1.18) New DiffController API
- (1.17) StreamSource extended
- (1.13) DiffView interface added
- (1.5) MergeVisualizer class added
- (1.4) StreamSource class added
- (1.3) The Diff APIs created
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: emiAdded 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: ovrabecAdding 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: tstupkaAdding 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: msandorDiffController class is a successor to DiffView interface that provides more features.
StreamSource extended
Feb 21 '07; API spec. version: 1.17; made by: msandorStreamSource 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: mentlicherA controler interface, that allows to programmatically control the diff component.
StreamSource class added
Apr 24 '02; API spec. version: 1.4; made by: mentlicherClass, 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: mentlicherThe base classes adedd.
Merge API
MergeVisualizer class added
Apr 24 '02; API spec. version: 1.5; made by: mentlicherService, that is used to resolve merge collisions.