Bug 97517

*** Issue 95773 has been marked as a duplicate of this issue. ***

Remaining DrawLayer implementation found in full IDE build:

org.netbeans.editor.DrawLayerFactory$AnnotationLayer
org.netbeans.modules.web.core.syntax.deprecated.ELDrawLayerFactory$ELLayer

There are no DrawLayer implementations in the standard/full IDE distro:
http://hg.netbeans.org/jet-main/rev/75249473d038
http://hg.netbeans.org/jet-main/rev/6ce37a7ad394
http://hg.netbeans.org/jet-main/rev/f1d489954827

Integrated into 'main-golden', will be available in build *200912111937* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main/rev/75249473d038
User: Vita Stejskal <vstejskal@netbeans.org>
Log: #97517 - replacing the old DrawLayer implementation for visualizing editor annotations with AnnotationsHighlighting layer based on Highlighting SPI

Created attachment 92739 [details]
Removing DrawLayer & co from the public API

The attached patch removes DrawLayer and related classes/methods from the public API exposed by editor.lib module. It also updates several other modules in Netbeans trunk codebase that were still using some of the removed stuff and also removes several obsolete modules from the build cluster configs.

I'd like to ask for reviewing the following changes:

DrawLayer & co has long time been deprecated and superseded by Highlighting SPI (1). The attached patch decommissions the API and removes it from public packages exposed by editor.lib module. Here are some more details:

A. The patch moves DrawLayer and related code from the public packages in editor.lib to private ones. However the code itself (eg. DrawEngine) is still used for rendering text in Netbeans editor. It is likely to be completely removed when issue #121357 is implemented (New Editor View Hierarchy).

B. The effect of this change on modules in Netbeans distribution (both trunk and contrib) is minimal. All the affected modules were updated to make sure that 'ant -Dcluster.config=experimental build-nozip' passes successfully. Here is the summary of affected modules and actions taken to resolve the problem:

  editor - non-functional calls the deprecated API -> calls deleted
  java.editor.lib - contains obsolete JavaDrawLayerFactory.JavaLayer -> deleted
  web.core.syntax - contains obsolete ELDrawLayerFactory.ELLayer -> deleted
  xml.text - contains dead code in XMLKit -> deleted

  spi.debugger.ui  - uses the deprecated API to remove the caret row
                     highlighting layer from the stack
                   -> updated to use Highlighting SPI
  debugger.jpda.ui - ditto
  python.debugger  - ditto
  form             - ditto

  editor.highlights - ide cluster; deprecated and no longer used
                    -> removing from the cluster, won't compile
  contrib/gsf.tools - experimental cluster; devtools for the old GSF framework,
                      obsolete and nobody uses it
                    -> removing from the cluster, won't compile

  contrib/cnd.fortran - not in any cluster -> untouched, won't compile
  contrib/editor.oldlibbridge - not in any cluster -> untouched, won't compile
  contrib/fixtabs - not in any cluster -> untouched, won't compile
  contrib/php.devtools - not in any cluster -> untouched, won't compile

C. There is somewhat related stuff in NbDocument class, which has been deprecated even longer than DrawLayer & co. NbDocument defines 'style' constants and methods for adding/removing these styles. A long time ago styles were used for marking editor lines when a breakpoint was added/removed and a compilation error was detected on a line. Breakpoints are now handled through Annotations and errors/warnings through Highlighting SPI in combination with Annotations. I leave the fate of this API in the very capable hands of the openide.text module owners.

D. Although this is an incompatible change and as such requires increasing the major module version of editor.lib, I think that doing so would cause unnecessary inconvenience for many module owners. Judging by the state of the Netbeans codebase the editor.lib module is used by many modules and the vast majority of them no longer use DrawLayer & co. Increasing the major version will force owners of all upstream modules to recompile their modules even though they could very well function in their existing form.

Therefore I'm asking for permition to just push the changes without increasing the major version of editor.lib and deal with potential linkage errors as they come (if they come).

E. The patch does not contain updated apichanges.xml, increased spec versions for editor.lib and the other affected modules. I'll do that before pushing the changes. I'll also double check that tests can be built.

Thanks for the review.

[1] http://bits.netbeans.org/dev/javadoc/org-netbeans-modules-editor-lib2/org/netbeans/spi/editor/highlighting/package-summary.html

To part C - if there is anything in NbDocument which you think should be deprecated which is not already, please do so. I think the things you mentioned are already deprecated. At some point they ought to be deleted.

To part D - my inclination is to be safe and consistent and increment the major release version even if the number of affected non-netbeans.org modules is expected to be small. (The number of affected netbeans.org modules is probably irrelevant since you will be updating all of them anyway.) Much better to require a few minutes' work from a module developer than risk having NoClassDefFoundError's be thrown in user installations.

(In reply to comment #7)
> To part C - if there is anything in NbDocument which you think should be
> deprecated which is not already, please do so. I think the things you mentioned
> are already deprecated. At some point they ought to be deleted.

Ok, in addition I'll deprecate the style name constants (eg. BREAKPOINT_STYLE_NAME, etc). The rest of the class looks ok.


> 
> To part D - my inclination is to be safe and consistent and increment the major
> release version even if the number of affected non-netbeans.org modules is
> expected to be small. (The number of affected netbeans.org modules is probably
> irrelevant since you will be updating all of them anyway.) Much better to
> require a few minutes' work from a module developer than risk having
> NoClassDefFoundError's be thrown in user installations.

Ok, I'll increase the major version number then. I assume, I'll also have to update dependencies of all modules using editor.lib and more importantly increase their spec versions in order to push them through AUCs. Correct?

Btw. 'ant build-test-dist' passes successfully with the attached patch.

Thanks

(In reply to comment #8)
> I'll also have to
> update dependencies of all modules using editor.lib and more importantly
> increase their spec versions in order to push them through AUCs. Correct?

Correct.

Created attachment 92845 [details]
Updated patch - module changes, deps and versions updated

Attaching an updated patch for trunk - it's the same as the previous one plus deprecations in NbDocument, editor.lib has now major-ver=2 and spec-ver=2.1, all module deps updated and spec versions of affected modules incremented. I'll also attach similar patch for contrib modules.

Created attachment 92846 [details]
Patch for contrib modules

This patch updates module dependencies and increments spec versions of contrib modules affected by the removal of DrawLayer & co API.

If there is no objection I'd like to push the changes tomorrow (23rd Dec).

Thanks for the review. I'll push the changes in contrib as soon as the trunk changes are propagated from jet-main.

http://hg.netbeans.org/jet-main/rev/f1fdee5a67f3

Changes from jet-main got merged into main-silver, changes in contrib pushed:
http://hg.netbeans.org/main/contrib/rev/782b785cbb7a

Integrated into 'main-golden', will be available in build *200912280201* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)
Changeset: http://hg.netbeans.org/main/rev/f1fdee5a67f3
User: Vita Stejskal <vstejskal@netbeans.org>
Log: #97517: removing DrawLayer & co from public API

(In reply to comment #14)
> Changes from jet-main got merged into main-silver, changes in contrib pushed:
> http://hg.netbeans.org/main/contrib/rev/782b785cbb7a

Many many thanks, Honzo.