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:
- 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
@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.
-
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
release33 branch 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
release330 branch was made on Nov 23 '01 for use in
the NetBeans 3.3 release.
-
The
release32 branch 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
release31 branch was made on Nov 7 '00 for use in
the NetBeans 3.1 release.
-
The
boston branch 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
postfcs
branch, 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).
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.
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
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).
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.
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)
Apr 17 '07; API spec. version: 1.18; made by: msandor
DiffController class is a successor to DiffView interface that provides more features.
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.
May 23 '05; API spec. version: 1.13; made by: mentlicher
A controler interface, that allows to programmatically control the
diff component.
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.
Feb 18 '02; API spec. version: 1.3; made by: mentlicher
The base classes adedd.
Apr 24 '02; API spec. version: 1.5; made by: mentlicher
Service, that is used to resolve merge collisions.