Editor Settings Upgrade

(Transition Guide For Modules Wishing To Shed The Old Editor Settings)

We have finally updated the editor settings infrastructure to stop using deprecated Options API, namely the infamous BaseOptions and Settings classes. Since the Options API was exposed through the editor APIs to clients many modules are affected by this change.

Are my modules affected?

There are several ways how you can easily find out if your module depends on a deprecated API. The easiest way is to look in the properties of your module's project, go to the 'Libraries' node and look at your module's dependencies. Names of deprecated modules are crossed in the list. There are three modules specifically related to this change that you should look for:

  • Editor Settings Prior 6.1 Separation
  • Editor Code Completion Prior 6.1 Separation
  • Settings Options API

Another way is to run Netbeans and look in its log file. All modules that depend on a deprecated module are mentioned at the beginning of the log file alongside with the code-name-base of the deprecated module.

If your module is not in Netbeans main repository you should check your project.xml and manifest.mf if they declare dependency on old versions of editor or editor.lib modules:

  • org.netbeans.modules.editor.lib < 1.27
  • org.netbeans.modules.editor < 1.41

If your module depends on specification versions smaller than those listed above it may not compile against the latest Netbeans platform and its binary version (when loaded in Netbeans) will automatically get injected extra dependencies on 'Editor Settings Prior 6.1 Separation' and 'Editor Code Completion Prior 6.1 Separation' modules.

Why was the old Code Completion API deprecated too?

Although the old Code Completion API has nothing to do with settings, it's been semi-deprecated for ages and so while we were cleaning things up we separated and deprecated the old Code Completion API as well. Surprisingly, there are still modules using some of its classes. How they work is beyond our comprehension.

My modules are affected, but why should I care anyway?

In general it is a good idea to keep your modules up-to-date and replace deprecated APIs with their newer equivalents. Usually there is a good reason for deprecating an API and some of the obvious benefits can be better performance, less complexity, more features, etc.

In this particular case there is one more thing to all this - the old editor settings infrastructure does not work! In the old concept all editor settings were tied to an implementation class of the EditorKit and each language support module was supposed to have one.

With the increasing number of languages, language embedding features and frameworks like GSF and Schliemann this turned out to be not so practical and we had to shift towards something else. The new settings infrastructure is based on mime types and MimeLookup. The main problem is that these two concepts do not map 1:1, because in general there can be multiple mime types (languages) using the same EditorKit implementation (eg. all GSF and Schliemann base languages, but also all XML based languages). For all these languages the old concept is broken and all languages from each of those groups must share the same copy of editor settings.

How do I update my modules?

It's simple, if your module is in Netbeans main repository open it in Netbeans IDE, go to its properties and remove dependencies on the three settings related API modules that we've deprecated:

  • Editor Settings Prior 6.1 Separation
  • Editor Code Completion Prior 6.1 Separation
  • Settings Options API

Close the properties dialog and compile your module. Chances are that your module will compile without a problem. If it doesn't, you will have to go through the errors and rewrite the code that is using the old API classes. This may sound scary, but in most cases it's going to be pretty straightforward. Just follow the detailed guidelines.

If your module is not in Netbeans main repository try to compile it against the latest Netbeans platform. If it compiles fine just update your module's dependencies on editor and editor.lib modules to match latest specification versions of these two modules. If your module does not compile you will have to rewrite your code to get rid of the old API classes according to the guidelines.

We tried to make things as much backwards compatible as was practical and we also tried to make sure that the transition guidelines actually work. For that we converted all modules in the basic IDE cluster and removed their dependencies on the deprecated APIs. However, if you find out that something that you have been using can't be rewritten please send an email to dev (at) editor (dot) netbeans (dot) org and we will help you. Obviously, if you get otherwise stuck and the guidelines don't help please send a question to the alias as well.

How much time approximately will I need to update my modules?

It depends on the complexity of your code. When we were rewriting modules from the basic IDE cluster we were able to update 2-5 modules in one day. So, estimating one day for one module should be a generous time for both updating and testing your changes.

What happens if I don't update my modules?

It's hard to say without knowing what your module does. We tried to preserve backwards compatibility and tested common functionality in the full Netbeans IDE build to make sure that nothing is seriously broken. So, in general, if your module compiles it should also work as before. Please note that this actually means that it may still be broken in the same way as it was before.

I want to update my modules, but have no time in this release? Can I do it later?

Sure. The old APIs were deprecated and moved to deprecated autoload modules, which means that they are still available and should work. We know that people have their schedules and it would be unfair to give you an extra work when we are already half way through the release cycle. So, if you can't really make it this release please queue it up for the next one.

My modules compile and run, but I suddenly get errors in my tests, why?

If the errors come from code, which loads things from MimeLookup and they don't seem to be there then the problem is likely to be in your test dependencies. For the new editor infrastructure to work it is essential to have org.netbeans.modules.editor.mimelookup.impl and org.netbeans.modules.editor.settings.storage modules. These two modules are 'eager' autoloads and in the IDE they are loaded through the 'Requires', 'Provides' tokens. Unfortunately, Netbeans testing infrastructure does not support these tokens, which is why you have to list the modules explicitly even when your tests compile fine.

It should be enough to add the following two test dependencies. In some exotic test setups this may not work, in which case please ask on dev (at) editor (dot) netbeans (dot) org.

Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo