Revision as of 10:31, 2 September 2014 by Sdedic (Talk | contribs)

This page gives an overview of changes in core NetBeans platform libraries for the purpose of API change review process. The change aims to remove or reduce dependencies on AWT and Swing API and desktop environment concepts in general, so that NetBeans Platform APIs can be used in non-GUI environment (commandline, embedded, J2EE, ...)

Related issues:


Utilities API

The org.openide.utilities API contains not only system-related or general-purpose utilities, but also a few of AWT- or Swing-bound utils. While useful for a traditional desktop application, they are unnecessary for a J2EE server application. Worse, if the runtime attempts to initialize UI components and peers in a headless or J2EE environment, exceptions and errors can occur, as there may be no display to work with. The separation will allow commandline and/or server-deployed components to use useful utilities without unnecessary or erroneous initialization on startup.

Utilities API can be split into two parts:

  • openide.util.base - threading, collections and structures, lookup, XML, preferences, I/O, weak ref support
  • openide.util - the traditional API set, depends on openide.util.base

As a part of the split effort, deprecated APIs remain in the old openide.util module; the offspring util.base should be free of deprecated features. As a rule of thumb, openide.util.base must not instantiate or initialize any nontrivial Swing or AWT classes (notable exception is the java.swing.event.ChangeListener).

The following classes/packages were identified as desktop-related:

  • util.actions - entire package
  • AsyncGUIJob, AsyncInitSupport - threading for GUI components
  • ContextAwareAction, ContextGlobalProvider - action UI support
  • ImageUtilities, [part of] Utilities, UtilitiesCompositeActionMap - works directly with Swing/AWT GUI APIs
  • UserCancelException, UserQuestionException - design tied to synchronous execution of UI desktop thread
  • HelpCtx - TBD
  • NetworkSettings - TBD

Deprecated classes:

  • Queue, SharedClassObject


Mutex has a support for EDT in its APIs, since there's an EVENT declared Mutex instance. The EDT is not available in headless applications and usage of Mutex.EVENT could lead to a deadlock of the caller (if the EDT queue is not processed). Therefore, the Mutex is changed to locate the MutexEventProvider from the default Lookup; it is expected that an implementation is present. The desktop-oriented openide.util module provides the usual implementation. JEE or commandline environment is expected to provide an implementation which throws an error to alert the developer.


Creating threads in JEE environment should be controlled by the container. The RequestProcessor should get some thread provider from the platform core implementation and rely on it to create threads or allocate them from a thread pool. This change will be designed and reviewed separately.

Backwards compatibility

Classes are not repackaged. Both openide.util and openide.util.base use the same package, so old clients have still access to the complete set of APIs of former openide.util module. Methods, which have been moved to openide.util.base (i.e. from Utilities to BaseUtilities class) will be preserved using delegation from the original class.

Module auto-deps feature will be used to inject openide.util.base dependency to older clients, so the moved classes remain accessible for linking. Module authors are encouraged to clean up dependencies, and migrate from Utilities to BaseUtilities wherever possible.

Filesystems API

FileSystems API contains very few references to Swing-related concepts, most intrusive is FileSystem.getActions(), which had been deprecated in 8.0.1. Still, FileSystem API library contains an implementation which eventually brings in Swing objects. Filesystem library also defined FileChooserBuilder class, which is a pure UI/desktop concept. This class should be moved to a new module, openide.filesystems.nb

As a part of this cleanup, legacy APIs are removed:

  • FileSystemCapability
  • FileSystem.getCapability, .setCapability
  • FileSystem.Environment
  • EnvironmentNotSupportedException

SharedClassObject usage

SharedClassObject from (legacy) openide.util module is used in a special handling of instanceCreate attribute. Instances of SCO are created using a special API rather than the new operator. But SharedClassObject was deprecated and (see the Utilities API changes) left in the legacy module. A new SPI, CustomInstanceFactory is provided. CustomInstanceFactories registered in the default Lookup are used to create an instance of an object. First Factory that provides an instance wins, ordering can be specified in Lookup registration.

Backwards compatibility

While some classes and methods are physically removed from the source, it was required to preserve runtime compatibility of older plugins. A special module, openide.filesystems.compat8 is created to provide compatibility mode with 8.0.1 NetBeans release. This module uses bytecode patching to inject the removed methods at the runtime. Using module-auto-deps feature, the compatibility module is activated if some enabled module depends on older version of FileSystem API.

Execution API

Removal of FileSystemCapability provokes removal of dependent methods in Execution API: createRepositoryPath

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