org.netbeans

Class ModuleInstaller

java.lang.Object

org.netbeans.ModuleInstaller

public abstract class ModuleInstaller
extends Object

Responsible for actually installing the contents of module JARs into the IDE. While the manager tracks which modules are enabled and their dependencies, the installer actually understands the manifest contents and is able to add layers, sections, etc. to the IDE's runtime.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ModuleInstaller() No-op constructor for subclasses.

Method Summary

Methods

Modifier and Type	Method and Description
protected void	classLoaderUp(ClassLoader cl) Tells the installer that new classloader is ready for use.
abstract void	close(List<Module> modules) Notify modules the IDE will be shut down.
Task	closeAsync(List<Module> modules) Initializes closing sequence on given modules.
abstract boolean	closing(List<Module> modules) Ask to shut down the IDE from a set of modules.
abstract void	dispose(Module m) Called when a module is being uninstalled and runtime information about it is no longer needed.
abstract void	load(List<Module> modules) Actually load some modules into the IDE.
protected Set<Dependency>	loadDependencies(String cnb) Loads dependencies cached from previous run, if possible.
Manifest	loadManifest(File jar) Scan a disabled module JAR file for its manifest contents.
abstract void	prepare(Module m) Called to ensure that a module is valid to be installed, before continuing.
void	refineClassLoader(Module m, List parents) Permit a module installer to add extra parent classloaders for a module.
void	refineDependencies(Module m, Set<Dependency> dependencies) Optionally refine the dependencies for a module.
String[]	refineProvides(Module m) Optionally adds additional token for the module.
boolean	shouldDelegateClasspathResource(String pkg) Similar to shouldDelegateResource(org.netbeans.Module, org.netbeans.Module, java.lang.String) but checks whether the system class loader should delegate to the classpath.
boolean	shouldDelegateResource(Module m, Module parent, String pkg) Optionally mask package use in a module classloader.
abstract void	unload(List<Module> modules) Unload some modules from the IDE.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ModuleInstaller

protected ModuleInstaller()

No-op constructor for subclasses.

Method Detail

prepare

public abstract void prepare(Module m)
                      throws InvalidException

Called to ensure that a module is valid to be installed, before continuing. Should examine the manifest and check its syntax (may keep cached parse information about that syntax). When this method is called, the module's classloader should be ready for use, but the system classloader will not yet contain it. It may (but need not) try to load mentioned resources from that classloader in order to catch errors early on. For some resources it may be preferable to load them lazily. If the installer indicates the module is invalid, it will not be installed. InvalidException thrown from here must include a reference to the module.

Throws:

InvalidException

dispose

public abstract void dispose(Module m)

Called when a module is being uninstalled and runtime information about it is no longer needed. The installer should remove any associated cache entries and try to release anything that might have been loaded with the module's classloader. The classloader may still be valid at this point but better not to use it.

classLoaderUp

protected void classLoaderUp(ClassLoader cl)

Tells the installer that new classloader is ready for use. This does not mean that all modules are ready to be used yet, but the classloader will be allowed to load classes from those modules already prepared.

Since:

2.32

load

public abstract void load(List<Module> modules)

Actually load some modules into the IDE. They will all have been prepared already, and their classloaders will be contained in the system classloader. It is expected to handle any resultant exceptions appropriately (e.g. skipping over a module, or skipping over that piece of a module). Where load order is significant, items should be installed in the order supplied: starting with basic modules and ending with dependent modules. Installers may choose to install all resources of a certain type (e.g. layers) from every module, then all of the next type, etc., for purposes of efficiency. Note that "loading" could really mean installing or restoring or upgrading, depending on module history.

unload

public abstract void unload(List<Module> modules)

Unload some modules from the IDE. Where unload order is significant, items should be uninstalled in the order supplied: starting with dependent modules and ending with basic modules. Module classloaders will still be in the system classloader.

closing

public abstract boolean closing(List<Module> modules)

Ask to shut down the IDE from a set of modules. Will begin with dependent and end with basic modules.

close

public abstract void close(List<Module> modules)

Notify modules the IDE will be shut down. Will begin with dependent and end with basic modules.

closeAsync

public Task closeAsync(List<Module> modules)

Initializes closing sequence on given modules. Certain operations may remain unfinished and can be carried out in parallel. A Task is returned for callers to wait till closing sequence is successfully finished.

Parameters:

modules - list of modules to close

Returns:

Since:

2.56

refineDependencies

public void refineDependencies(Module m,
                      Set<Dependency> dependencies)

Optionally refine the dependencies for a module. For example, an installer might decide to automatically add a dependency on a "stock" library module for all client modules meeting some criterion. The default implementation makes no change.

Parameters:

m - a module to possibly refine dependencies for; overriders must not call getDependencies on this module nor attempt to directly change it in any way; overriders may ask for module code name, version, etc.

dependencies - a set of Dependency's; mutable, entries may be added or removed during the dynamic scope of this call

Since:

org.netbeans.core/1 1.2

shouldDelegateResource

public boolean shouldDelegateResource(Module m,
                             Module parent,
                             String pkg)

Optionally mask package use in a module classloader. For example, an installer might decide that a module may not use a package in the application classpath because it is an unguaranteed implementation package and the module has not explicitly requested to use it.

The module system automatically excludes improper access to non-public packages (as declared via OpenIDE-Module-Public-Packages) and cross-module access to the META-INF/ directory.

The default implementation of this method permits all other package delegation.

Parameters:

m - the module requesting use of a given package

parent - the module which might possibly supply that package, or null if the possible provider is not a module (i.e. application classpath)

pkg - the name of the package in use, in the form "org/netbeans/modules/foo/" (i.e. slash-separated and ending in a slash as well)

Since:

org.netbeans.core/1 1.3

shouldDelegateClasspathResource

public boolean shouldDelegateClasspathResource(String pkg)

Similar to shouldDelegateResource(org.netbeans.Module, org.netbeans.Module, java.lang.String) but checks whether the system class loader should delegate to the classpath.

Parameters:

pkg - as in shouldDelegateResource(org.netbeans.Module, org.netbeans.Module, java.lang.String)

Returns:

true if it is acceptable to delegate to startup JARs or the JRE

Since:

org.netbeans.bootstrap/1 2.17

loadManifest

public Manifest loadManifest(File jar)
                      throws IOException

Scan a disabled module JAR file for its manifest contents. Subclasses may implement this efficiently, e.g. to use a special cache.

The default implementation simply opens the JAR and gets its manifest using the standard JRE calls.

Never called for reloadable JARs.

Parameters:

jar - a module JAR to open

Returns:

its manifest

Throws:

IOException - if the JAR cannot be opened or does not have a manifest at all

Since:

org.netbeans.core/1 1.5

See Also:

"#26786"

refineClassLoader

public void refineClassLoader(Module m,
                     List parents)

Permit a module installer to add extra parent classloaders for a module. Called during enablement of a module. The default implementation does nothing.

Parameters:

m - a module which is about to be enabled

parents - current list of ClassLoader parents; may be mutated (appended to)

Since:

org.netbeans.core/1 > 1.6

See Also:

"#27853"

refineProvides

public String[] refineProvides(Module m)

Optionally adds additional token for the module.

Parameters:

m - the module to add token to

Returns:

null or list of tokens this module provides

Since:

org.netbeans.core/1 > 1.25

See Also:

"#46833"

loadDependencies

protected Set<Dependency> loadDependencies(String cnb)

Loads dependencies cached from previous run, if possible.

Parameters:

cnb - the code name base of the module to get dependencies for

Returns:

null or set of dependencies for the module

Since:

2.18