(Difference between revisions)
Line 140: Line 140:
TODO: there could be a better name for <code>projectuiapi.base</code>
TODO: there could be a better name for <code>projectuiapi.base</code>
== Debugger Modules ==
Debugger already consist of modules that are intended for non-UI code and modules intended for UI. However, some modules intended for non-UI contains also swing dependent code. Specifically <code>debugger.jpda</code> and <code>debugger.jpda.projects</code>. These need to be refactored and the UI stuff moved to appropriate UI modules.
Modules without UI:
* <code>api.debugger</code>
* <code>api.debugger.jpda</code>
* <code>lib.v8debug</code>
Modules with UI:
* <code>spi.viewmodel</code>
* <code>spi.debugger.ui</code>
* <code>debugger.jpda.ui</code>
* <code>debugger.jpda.visual</code>

Revision as of 17:03, 25 November 2014

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.

XML Tools API (api.xml)

The org.netbeans.api.xml.cookies and org.netbeans.spi.xml.cookies packages were moved into a new api.xml.ui module to remove dependency on the openide.loaders.

Execution API

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

Classpath APIs (api.java.classpath)

The ClassLoaderFactory interface was added into the org.netbeans.spi.java.classpath package to remove direct dependency of ClassPath on NbClassLoader.

Java Platform

While the Java Platform module contains classes describing and managing a platform, it also provides an api/spi to customise or install a platform and which is UI (Swing/AWT) dependent and unusable in a J2EE server application.

The module can be split in two parts:

  • java.platform
    • cleaned up from UI (Swing/AWT) dependent logic
    • provides general platform management and info about java platforms
    • introduced internal spi - org.netbeans.modules.java.platform.implspi
  • java.platform.ui
    • UI (Swing/AWT) dependent
    • will provide the platform customiser and install functionality

where the new java.platform.ui depends on java.platform

External Libraries (project.libraries)

The LibrariesCustomizer, LibraryChooser and LibraryCustomizerContext were moved into a new module project.libraries.ui to remove dependency on the swing and awt.


Project API (projectapi)

The ProjectManager is now injected by a new SPI ProjectManagerImplementation allowing different implementations of the ProjectManager API. The ProjectManager.mutex(Project+) was added to remove contention on unrelated projects. The ProjectUtil.getInformation(Project) uses ProjectInformationProvider SPI to remove dependency on ImageUtilities.

Ant-Based Project Support

Is mostly UI independent but comes with a fracture of UI (Swing/AWT) dependent file choosing and customiser features, which can be easily extracted into a separate module, so that the ant based project infrastructure becomes usable in a J2EE server application.

The module can be split in two parts:

  • project.ant
    • cleaned up from UI (Swing/AWT) dependent features
    • the interesting part of the ant based project infrastructure
  • project.ant.ui
    • UI (Swing/AWT) dependent
    • will provide some file choosing and customiser features

where the new project.ant.ui depends in project.ant

The ReferenceHelper.getLibraryChooserImportHandler() methods were moved into org.netbeans.spi.project.support.ant.ui.CustomizerUtilities in the project.ant.ui to remove a dependency of project.ant on project.libraries.ui

Handling of UserQuestionException and some other UI related functionality was to interwoven in the projects code base and had to be externalized via an spi - see project.spi.intern and its usage in project.ant

Java Project

Functionality separable in to logical parts either depending, or not depending on Swing/AWT

The module can be split in two parts:

  • java.project
    • sources classpath, lookup and java platform related
    • no dependency on UI (Swing/AWT)
  • java.project.ui
    • JavaRunner api/spi depends via Execution API on the UI related InputOutput API
    • big chunk of UI depenedent utilities in o.n.spi.java.project.support.ui

where the new java.project.ui depends on java.project

Project UI API

Provides api/spi used by other modules cleaned up from Swing/AWT dependencies (e.g. java.project, project.ant).

The necessary classes are separable into a new module which also doesn't pull in any Swing/AWT dependencies.

The module can be split in two parts:

  • projectuiapi.base
    • mainly classes related to OpenProjects, ProjectGroups, ProjectProblems
    • no dependency on UI (Swing/AWT)
  • projectuiapi
    • big chunk of UI depenedent utilities in o.n.spi.java.project.support.ui

where projectuiapi depends on projectuiapi.base

TODO: there could be a better name for projectuiapi.base

Debugger Modules

Debugger already consist of modules that are intended for non-UI code and modules intended for UI. However, some modules intended for non-UI contains also swing dependent code. Specifically debugger.jpda and debugger.jpda.projects. These need to be refactored and the UI stuff moved to appropriate UI modules.

Modules without UI:

  • api.debugger
  • api.debugger.jpda
  • lib.v8debug

Modules with UI:

  • spi.viewmodel
  • spi.debugger.ui
  • debugger.jpda.ui
  • debugger.jpda.visual
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