Skip navigation links
org.netbeans.bootstrap/1 2.103

Bootstrap
Friend, Private or Third Party

See: Description

Bootstrap 
Package Description
org.netbeans  

The heart of NetBeans Runtime Container. Handles lifecycle of installed modules and OSGi bundles.

What is New (see all changes)?

Use Cases

Invalidating Caches

NetBeans Module system is optimized to eliminate useless I/O operations on start (as a result the embedded OSGi container is fastest on the planet -- with respect to application start up time). This is achieved by caching information known to have been needed in previous starts and using it rather than obtaining it again from the module JAR files.

There are various caches (like all-layers.dat, all-manifests.dat, all-resources.dat, netigso-bundles, etc. ) provided by the module system or by other subsystems of the application. Together, working in orchestration, they eliminate the need to touch the disk (which is very slow operation especially during morning launch). Btw. there is a test which verifies the caching system really works -- it is recommended for each product built on top of NetBeans Platform to copy and adjust it to verify the caches are really used.

Of course, the caches may get out of date, for example when an external tool modifies the installation layout. How can the system detect whether the caches are valid and still be usable? The only way to verify the caches are 100% correct is to regenerate them and compare whether the cached bits are the same. However that would be terribly slow and defeat the whole purpose of using caches.

As such we have the lastModified API. Every cluster (as enumerated by netbeans.dirs and netbeans.home properties) is supposed to contain such file. Whenever an external tool changes something inside some cluster, it is supposed to touch the file and change its timestamp. That will tell the system that caches are invalid (as their timestamps will become older than newest .lastModified file).

Generating Shared Cache

The caches (as introduced in invalidating caches section) are optimized to reflect the state of previous start. However that means, the very first start runs without them. This may not be a problem (if the start follows immediately after installation), however in multi user environment (when the installation is done by administrator), the first start may be slow.

To mitigate that the system offers support for shared caches. As part of installation, one can also copy certain cache files into the shared location. Those files will then be used on a first start of the system (when the user directory is empty).

To generate the shared cache files start NetBeans with an empty, temporary user directory and then copy the desired files into first cluster directory:

$ netbeans --userdir /tmp/nb -J-Dnetbeans.close=true -J-Dorg.netbeans.core.WindowSystem.show=false
$ cd /tmp/nb
$ zip -r $INSTALL/$first_netbeans_dirs_dir/var/cache/populate.zip var/cache/netigso
$ cp var/cache/* $INSTALL/$first_netbeans_dirs_dir/var/cache
$ rm -r /tmp/nb/
         

The meaning of populate.zip and list of known cache files is described here. Additional modules and subsystems may add new files however. The ultimate knowledge is available only to those who understand overall product installation structure.

Patch classes

In case one wants to modify other classes before they get loaded into the VM, one can register its own Agent-Class and then be called whenever another class is defined. The behavior matches as closely as possible the one provided by JDK instrument package. To patch bytecode of other classes register your class in manifest and in its static agentmain method add your own ClassFileTransformer which will then be consulted whenever new classes are loaded.

# following line should be in manifest of your module
Agent-Class: your.pkg.Transformer             

// this should be your class
package your.pkg;
public class Transformer implements ClassFileTransformer {
    public static void agentmain(String args, Instrumentation i) {
        i.addTransformer(new Transformer());
    }
             
    public byte[] transform(
        ClassLoader loader, String className, Class classBeingRedefined, 
        ProtectionDomain protectionDomain, byte[] classfileBuffer
    ) {
        // do your transformation
    }
}

The implementation tries to be as complient as possible with the original JDK's specification, but some differences are inevitable. For example the classBeingRedefined parameter in the previous example is always null as NetBeans runtime container does not have access to the class instance that is being defined yet.

Module Fragments

This is a specific case of Patch Classes use-case. To maintain binary compatibility when removing methods from API classes, the "removed" implementation is actually moved to a special class, which becomes a superclass of the original API class. Such special classes should be separated into a 'compat' module, which is only loaded in presence of old clients.

The compat module should declare it is a fragment of the original API module in its MANIFEST.MF

OpenIDE-Module-Fragment-Host: orignal.module.codename
            

which ensures contents of the compat module will be loaded using classloader of the 'fragment host' module. The compat module will not get its own classloader. The special class itself should be marked using PatchFor annotation, which causes it will be patched as superclass and inserted into the inheritance chain.

Exported Interfaces

This table lists all of the module exported APIs with defined stability classifications. It is generated based on answers to questions about the architecture of the module. Read them all...
Group of java interfaces
Interface NameIn/OutStabilitySpecified in What Document?
ExceptionAnnotatableUsingLogRecordsExportedFriend

To support classification of exceptions and also annotation of exceptions with logging levels and additional localized messages, logged exceptions and their initCause's are searched for implementation of Callable<LogRecord[]>. If an exception implements this interface, the call() method is called and returned LogRecords then scanned for messages, levels, etc.

Group of java.io.File interfaces
Interface NameIn/OutStabilitySpecified in What Document?
nbexecExportedStable ...//netbeans.apache.org/projects/platform/articles/installation.html

lock-fileExportedPrivate

The lock file ${netbeans.user}/lock will have file permissions changed to go-rwx for safety on Unix systems (requires presence of chmod)

nbexec.exeExportedStable ...//netbeans.apache.org/projects/platform/articles/installation.html

ClassPath-CompositionExportedPrivate

Bootstrap code creates a class loader to load the rest of the core from. The bootstrap code is loaded from the Java application class loader, using the classpath lib/*.jar.

Dynamic-ClassPath-CompositionExportedFriend

After creating bootstrap classpath another low level set of JARs is loaded with a new classloader from core/*.jar directories in each clusters.

imported-markerExportedFriend

${netbeans.user}/var/imported is used to identify whether a userdir has already been updated or it still needs an update. Can be created by installer if no update check should be performed, no other code is supposed to realy on this file.

license-check-marker-fileExportedFriend

${netbeans.user}/var/license_accepted and ${nbcluster.dir}/var/license_accepted are used to identify whether user accepted license.

.lastModifiedExportedUnder Development

To speedup testing that module caches are up-to-date, the system recognizes special file inside of each cluster. If .lastModified file is present in a cluster, then the content of the cluster is not scanned any more deeply and instead the time stamp of the file is used as last modification for the whole content of the cluster.

This API is primarily intended for use by installer and RPM packagers and also autoupdate, that are supposed to create such file, as soon as they finish modifications to any cluster.

This file is ignored when accessing user directory, as it is expected that user can modify it, while the user usually does not have access permision or need to modify the shared installation clusters.

cached.lastModifiedExportedPrivate

If the .lastModified file is not present in cluster directory, it is recomputed on startup and stored in $userdir/var/cache/lastModified/$clustername. This file and its content is meant just for private consumption of the IDE.

installation.cacheExportedFriend

Installer can speed NetBeans IDE start by generating caches when the installation is over. Such caches are stored in the installation, in first cluster listed by netbeans.dirs (or in a location specified by netbeans.fallback.cache property, if available) and have the same layout as user caches (including here in described caches like all-resources.dat, as well as caches provided by other subsystems like netigso-bundles) in the user directory - e.g. they are under var/cache.

If a file var/cache/populate.zip is found, its content is unzipped into user directory (if it is empty).

all-resources.datExportedFriend

To speedup class loading during startup, the system keeps a cache of resources needed during startup in var/cache/all-resources.dat. If the cache is valid, it is loaded during startup and class and resource loading requests are redirected there.

The file is binary and shouldn't be modified by other code than org.netbeans.Archive. The file content uses magic header and versioning to allow evolution of its (private) format. The location is however well known for purposes of installer.

all-files.datExportedFriend

Rather than seeking on disk and using access OS call uselessly to find that some file is not present, the layout of files under the clusters is recorded in var/cache/all-files.data.

The file is binary and its format is private. The location is however well known for purposes of installer.

all-layers.datExportedFriend

Modules register their functionality into the system using layers. To avoid parsing and merging of content of these files on each start, the system creates a cached, binary representation of the layers structure in var/cache/all-layers.dat and var/cache/all-local-layers.dat.

The file is binary and its format is private. The location is however well known for purposes of installer.

all-clusters.datExportedFriend

Lists relative paths of clusters (those defined by netbeans.home and netbeans.dirs) for which the cache has been created. This is an important file in the shared cache as it helps to ensure the set of clusters has not changed since the cache has been generated.

The file is binary and its format is private. The location is however well known for purposes of installer.

all-installer.datExportedFriend

Additional information about modules (like deprecation message, etc.) is stored in var/cache/all-installer.dat to avoid the need to parse it out on each start.

The file is binary and its format is private. The location is however well known for purposes of installer.

all-manifests.datExportedFriend

Graph of dependencies between modules, sorted startup order, state of modules is stored in var/cache/all-manifests.dat to avoid the need to compute this information on every start.

The file is binary and its format is private. The location is however well known for purposes of installer.

all-modules.datExportedFriend

Pre-parsed content of config/Modules/*.xml is cached in var/cache/all-modules.dat.

The file is binary and its format is private. The location is however well known for purposes of installer.

package-attrs.datExportedFriend

Cache of various attributes of packages (vendor, spec & impl version, etc.) is stored in var/cache/package-attrs.dat. This file is often almost empty to signal such information is not provided by any module.

The file is binary and its format is private. The location is however well known for purposes of installer.

localeVariantsExportedFriend

File var/cache/localeVariants contains information about used branding and L10N files for each module. Avoids checking for locale/xyz_cs_CZ.jar files when (for example) only English L10N are present.

The file is binary and its format is private. The location is however well known for purposes of installer.

One can control creation of the all-resources.dat file in the user directory via org.netbeans.core.update.all.resources property.

Group of property interfaces
Interface NameIn/OutStabilitySpecified in What Document?
java.util.logging.Level.1973ExportedDeprecated

LogRecords sent to registered logger may be marked as those intended for user. This can be done by logging with level which has intValue() == 1973. Localized message of such log records is then shown in a special dialog. This behaviour is supported for backward compatibility, but in fact it is deprecated. The preferred way is to directly show dialog using DialogDisplayer.

NetBeans-IDE-DevExportedPrivate

The registry key Software\netbeans.org\NetBeans IDE\Dev Default user directory, unless --userdir is given. The name of this registry key is brandable, as is its default value. [Windows only]

SplashOnByDefaultExportedUnder Development

can be true or false, allows some applications build on top of the platform to disable splash by default

Group of systemproperty interfaces
Interface NameIn/OutStabilitySpecified in What Document?
netbeans.exception.alert.min.levelExportedUnder Development

Minimum integer level that triggers the blinking icon signaling an exceptional state. By default 900 - e.g. WARNING.

netbeans.exception.report.min.levelExportedUnder Development

Minimum integer level that triggers the dialog with exception. By default 900 with assertions on and 1001 without them.

netbeans.mainclassExportedFriend

Main Java class for bootstrap code to start (currently org.netbeans.core.startup.Main). Might be used by alternate launchers.

netbeans.homeExportedUnder Development

NetBeans installation directory (where the launcher is).

netbeans.user.dirExportedUnder Development

If this property is provided, it is used as the current working directory regardless of the value of user.dir.

netbeans.dirsExportedFriend

Additional secondary NetBeans installation directories as proposed in installation structure design document.

netbeans.fallback.cacheExportedFriend

Alternative location of NetBeans fallback cache generated during installation (see installation cache for description of the files layout). If the property is set to none, then the fallback cache check is completely disabled.

netbeans.classpathExportedFriend

Classpath to prepend to core loader (normally just lib/*.jar). Possibly useful for testing infrastructure etc.

netbeans.systemclassloader.patchesExportedUnder Development

By setting this system property to a classpath (list of directories and JARs separated by the normal path separator) you may append to the system class loader.

netbeans.patches.cnbExportedUnder Development

By setting a system property to "netbeans.patches." + module.getCodeNameBase() one can influence installed modules without changing the build. Format is -Dnetbeans.patches.org.nb.mods.foo=/path/to.file.jar:/path/to/dir.

netbeans.importclassExportedFriend

There is a special support for importing the settings from previous versions. As only the product itself knows about what to import and where this cannot be done directly in the launcher, but we need at a well defined moment (user directory is missing and no modules have been initialized yet) to call the product to ask the user and do the actual copy of userdir.

After all core/*.jar files has been initialized and the user dir has not yet been updated (see bellow) the launcher checks for value of netbeans.importclass system property and if provided it loads that class and invokes its main method (in AWT thread) and if no exception is thrown it marks the userdir as already upgraded.

netbeans.accept_license_classExportedFriend

Before first usage of IDE user must accept license. If user does not install IDE by installer (user must accept license during installation) user must accept license during IDE first start.

Launcher calls method showLicensePanel of netbeans.acceptlicenseclass if license was not yet accepted by user and it is necessary to show license in dialog to user.

netbeans.logger.consoleExportedFriend

Controls whether to log messages to the console, or just to the log file.

org.netbeans.CLIHandlerExportedPrivate

Setting this property to less than zero value enables logging of what is going on in the CLIHandler - e.g. in the code that locks user directory and handles processing of command line options. Use -J-Dorg.netbeans.CLIHandler=-1 to send the logging to System.err.

org.netbeans.CLIHandler.serverExportedUnder Development

One can disable the CLI server (listening on commands from subsequent invocations) by setting property org.netbeans.CLIHandler.server to false.

org.netbeans.core.systemfilesystem.customExportedFriend

Contains class name of a class that can serve as provider of the writable layer of the system file system. The class must be a subclass of org.openide.filesystems.FileSystem and have public default constructor. Morevoer the class denoted by the property must be on the classpath.

netbeans.security.nocheckExportedUnder Development

By default NetBeans prevent certain operations like System.exit. One can disable this behavior by providing -Dnetbeans.security.nocheck=true. Since version 2.47 such property also allows the SecurityManager to be replaced by another.

sun.awt.datatransfer.timeoutExportedUnder Development

Specifies the amount of milliseconds the call to getContent() method of ExClipboard waits to synchronize with system clipboard. Defaults to 1000ms.

netbeans.ignore.dupmoduleExportedUnder Development

By default ModuleManager throws DuplicateException when an attempt is made to load an already loaded module. One can change this behavior by providing -Dnetbeans.ignore.dupmodule=true since version 2.63. When -Dnetbeans.ignore.dupmodule=true is provided, attempt of duplicate loading is logged instead of throwing DuplicateException.

org.netbeans.PatchByteCode.disableExportedFriend

For backward compatibility, the NetBeans startup code performs bytecode manipulation such as making marked methods public or injecting code that was deprecated and removed from the NetBeans codebase. For debugging, or simply in order to disable preprocessing, patching may be disabled. Note that older modules, which were not recompiled against the released version's sources may become broken, if bytecode patching is disabled.

Group of logger interfaces
Interface NameIn/OutStabilitySpecified in What Document?
org.netbeans.ProxyClassLoaderExportedPrivate

This logger logs at WARNING level about accessing resources from the default package.

Group of cli interfaces
Interface NameIn/OutStabilitySpecified in What Document?
--jdkhomeExportedUnder Development

JDK (or perhaps JRE) installation directory.

--clustersExportedUnder Development

The list of clusters to intialize the system from. Is used to set the value of netbeans.dirs.

--userdirExportedUnder Development

User directory, if not the default.

-JWHATEVERExportedUnder Development

Pass option WHATEVER to the JVM.

--cpExportedUnder Development

-cp:a and -cp:p append and prepend to the startup classpath; deprecated except for special purposes such as installing a custom look & feel.

--uiExportedUnder Development

Specify a look & feel. The same as --laf. To make human life easier simple translation was added to convert L&F ID to L&F class name for known L&Fs.
  • Metal is translated to javax.swing.plaf.metal.MetalLookAndFeel
  • GTK is translated to com.sun.java.swing.plaf.gtk.GTKLookAndFeel
  • Nimbus is translated to com.sun.java.swing.plaf.nimbus.NimbusLookAndFeel
  • Windows is translated to com.sun.java.swing.plaf.windows.WindowsLookAndFeel
  • Aqua is translated to apple.laf.AquaLookAndFeel

--lafExportedUnder Development

Specify a look & feel. The same as --ui.

--bootclassExportedUnder Development

Alternative main class used to initialize the system.

--fontsizeExportedDeprecated

Specify base fontsize. Deprecated in favor of using themes which is much more general. But this is a convenient quick settings, handy for projection screens and so on.

--localeExportedUnder Development

Specify system locale.

--brandingExportedUnder Development

Specify application branding.

--nologgingExportedPrivate

Do not write a log file.

--nosplashExportedFriend

Do not show the splash screen.

--noguiExportedFriend

Do not show any GUI at all.

--reloadExportedUnder Development

Reload a test module.

Group of lookup interfaces
Interface NameIn/OutStabilitySpecified in What Document?
lookup.org.netbeans.CLIHandlerExportedFriend

Instances of org.netbeans.CLIHandler are found using services lookup in the "dynamic classpath loader" (i.e. startup classpath plus ${netbeans.home}/core/*.jar).

org.netbeans.ModuleFactoryExportedFriend

Instances of org.netbeans.ModuleFactory are found using services lookup in the "dynamic classpath loader" (i.e. startup classpath plus ${netbeans.home}/core/*.jar). ModuleFactory can be used to create alternative module implementations.

CoreBridgeExportedPrivate

The communication between core.jar and rest of the platform code in org-netbeans-core.jar is handled thru handled thru CoreBridge calls.

RunLevelExportedFriend

Additional callbacks from core.jar after the module system is started are done using RunLevel interface. Currently it starts window system.

java.util.logging.HandlerExportedFriend

There is a communication bridge between the default logging handler registered by core/startup and the UI handler in core that presents certain log records in the UI.

Implementation Details

Where are the sources for the module?

The sources for the module are in the Apache Git repositories or in the GitHub repositories.

What do other modules need to do to declare a dependency on this one, in addition to or instead of a plain module dependency?

XXX no answer for deploy-dependencies

Read more about the implementation in the answers to architecture questions.

Skip navigation links
org.netbeans.bootstrap/1 2.103