org.netbeans
Class ModuleManager

java.lang.Object
  org.openide.modules.Modules
      org.netbeans.ModuleManager

public final class ModuleManager
extends Modules

Manages a collection of modules. Must use mutex() to access its important methods.

Field Summary

static String	PROP_CLASS_LOADER
static String	PROP_ENABLED_MODULES
static String	PROP_MODULES

Constructor Summary

ModuleManager(ModuleInstaller installer, Events ev)
Create a manager, initially with no managed modules.

Method Summary

void	addPropertyChangeListener(PropertyChangeListener l) Add a change listener.
Module	create(File jar, Object history, boolean reloadable, boolean autoload) Deprecated. since org.netbeans.core/1 1.3
Module	create(File jar, Object history, boolean reloadable, boolean autoload, boolean eager) Create a module from a JAR and add it to the managed set.
Module	createBundle(File jar, Object history, boolean reloadable, boolean autoload, boolean eager, int startLevel) Create a module from a JAR representing an OSGi bundle and adds it to the managed set.
Module	createFixed(Manifest mani, Object history, ClassLoader loader) Create a fixed module (e.g.
Module	createFixed(Manifest mani, Object history, ClassLoader loader, boolean autoload, boolean eager) Create a fixed module (e.g.
void	delete(Module m) Remove a module from the managed set.
void	disable(Module m) Disable a single module.
void	disable(Set<Module> modules) Disable a set of modules together.
void	enable(Module m) Enable a single module.
void	enable(Set<Module> modules) Enable a set of modules together.
Module	get(String codeNameBase) Convenience method to find a module by name.
ClassLoader	getClassLoader() Get a classloader capable of loading from any of the enabled modules or their declared extensions.
Set<Module>	getEnabledModules() Get a set of modules managed which are currently enabled.
Events	getEvents() Access for ManifestSection.
Set<Module>	getModuleInterdependencies(Module m, boolean reverse, boolean transitive) Deprecated. Use getModuleInterdependencies(Module, boolean, boolean, boolean) instead.
Set<Module>	getModuleInterdependencies(Module m, boolean reverse, boolean transitive, boolean considerNeeds) Get a set of modules depended upon or depending on this module.
Lookup	getModuleLookup() Retrieve set of modules in Lookup form.
Set<Module>	getModules() Get a set of Modules being managed.
Mutex	mutex() Get a locking mutex for this module installer.
Mutex.Privileged	mutexPrivileged() Classes in this package can, if careful, use the privileged form.
ModuleInfo	ownerOf(Class<?> clazz)
void	refineClassLoader(Module m, List parents) Used by Module to communicate with the ModuleInstaller re.
void	releaseModuleManifests() Release storage for all module manifests.
void	reload(Module m) Reload a module.
void	removePropertyChangeListener(PropertyChangeListener l) Remove a change listener.
void	replaceJaveleonModule(Module module, Module newModule) Only for use with Javeleon modules.
boolean	shouldDelegateResource(Module m, Module parent, String pkg) Use by OneModuleClassLoader to communicate with the ModuleInstaller re.
boolean	shutDown() Try to shut down the system.
boolean	shutDown(Runnable midHook) Try to shut down the system.
List<Module>	simulateDisable(Set<Module> modules) Simulate what would happen if a set of modules were to be disabled.
List<Module>	simulateEnable(Set<Module> modules) Simulate what would happen if a set of modules were to be enabled.
List<Module>	simulateJaveleonReload(Module moduleToReload) Only for use from Javeleon code.

Methods inherited from class org.openide.modules.Modules

getDefault

Methods inherited from class java.lang.Object

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

Field Detail

PROP_MODULES

public static final String PROP_MODULES

See Also:

Constant Field Values

PROP_ENABLED_MODULES

public static final String PROP_ENABLED_MODULES

See Also:

Constant Field Values

PROP_CLASS_LOADER

public static final String PROP_CLASS_LOADER

See Also:

Constant Field Values

Constructor Detail

ModuleManager

public ModuleManager(ModuleInstaller installer,
                     Events ev)

Create a manager, initially with no managed modules. The handler for installing modules is given. Also the sink for event messages must be given.

Method Detail

getEvents

public final Events getEvents()

Access for ManifestSection.

Since:

JST-PENDING needed by ManifestSection

mutex

public final Mutex mutex()

Get a locking mutex for this module installer. All calls other than adding or removing property change listeners, or getting the module lookup, called on this class must be done within the scope of this mutex (with read or write access as appropriate). Methods on ModuleInfo need not be called within it; methods specifically on Module do need to be called within it (read access is sufficient). Note that property changes are fired with read access already held for convenience. Please avoid entering the mutex from "sensitive" threads such as the event thread, the folder recognizer/lookup thread, etc., or with other locks held (such as the Children mutex), especially when entering the mutex as a writer: actions such as enabling modules in particular can call arbitrary foreign module code which may do a number of strange things (including consuming a significant amount of time and waiting for other tasks such as lookup or data object recognition). Use the request processor or the IDE's main startup thread or the execution engine to be safe.

mutexPrivileged

public final Mutex.Privileged mutexPrivileged()

Classes in this package can, if careful, use the privileged form.

Since:

JST-PENDING this had to be made public as the package is now split in two

releaseModuleManifests

public void releaseModuleManifests()

Release storage for all module manifests.

See Also:

Module.releaseManifest()

addPropertyChangeListener

public final void addPropertyChangeListener(PropertyChangeListener l)

Add a change listener. Only the declared properties will be fired, and they are not guaranteed to be fired synchronously with the change (currently they are not in fact, for safety). The change events are not guaranteed to provide an old and new value, so you will need to use the proper getter methods. When the changes are fired, you are inside the mutex with read access.

removePropertyChangeListener

public final void removePropertyChangeListener(PropertyChangeListener l)

Remove a change listener.

getModuleLookup

public Lookup getModuleLookup()

Retrieve set of modules in Lookup form. The core top manager should install this into the set of available lookups. Will fire lookup events when the set of modules changes (not for enabling/disabling/etc.). No other subsystem should make any attempt to provide an instance of ModuleInfo via lookup, so an optimization could be to jump straight to this lookup when ModuleInfo/Module is requested.

getModules

public Set<Module> getModules()

Get a set of Modules being managed. No two contained modules may at any time share the same code name base.

See Also:

PROP_MODULES

getEnabledModules

public final Set<Module> getEnabledModules()

Get a set of modules managed which are currently enabled. Convenience method only.

See Also:

PROP_ENABLED_MODULES

get

public final Module get(String codeNameBase)

Convenience method to find a module by name. Returns null if there is no such managed module.

ownerOf

public ModuleInfo ownerOf(Class<?> clazz)

Specified by:

ownerOf in class Modules

getModuleInterdependencies

@Deprecated
public Set<Module> getModuleInterdependencies(Module m,
                                                         boolean reverse,
                                                         boolean transitive)

Deprecated. Use getModuleInterdependencies(Module, boolean, boolean, boolean) instead.

getModuleInterdependencies

public Set<Module> getModuleInterdependencies(Module m,
                                              boolean reverse,
                                              boolean transitive,
                                              boolean considerNeeds)

Get a set of modules depended upon or depending on this module.

Note that provide-require/need dependencies are listed alongside direct dependencies; a module with a required token is considered to depend on all modules providing that token (though in fact only one is needed to enable it).

Illegal cyclic dependencies are omitted.

Parameters:

m - a module to start from; may be enabled or not, but must be owned by this manager

reverse - if true, find modules depending on this module; if false, find modules this module depends upon

transitive - if true, these dependencies are considered transitively as well

considerNeeds - if true, dependencies of type Dependency.TYPE_NEEDS are considered

Returns:

a set (possibly empty) of modules managed by this manager, never including m

Since:

org.netbeans.bootstrap/1 > 2.48

getClassLoader

public ClassLoader getClassLoader()

Get a classloader capable of loading from any of the enabled modules or their declared extensions. Normally used as Thread.getContextClassLoader(). Thread-safe.

See Also:

PROP_CLASS_LOADER

replaceJaveleonModule

public void replaceJaveleonModule(Module module,
                                  Module newModule)

Only for use with Javeleon modules.

create

@Deprecated
public Module create(File jar,
                                Object history,
                                boolean reloadable,
                                boolean autoload)
              throws IOException,
                     DuplicateException

Deprecated. since org.netbeans.core/1 1.3

Throws:

IOException

DuplicateException

See Also:

create(File,Object,boolean,boolean,boolean)

create

public Module create(File jar,
                     Object history,
                     boolean reloadable,
                     boolean autoload,
                     boolean eager)
              throws IOException,
                     DuplicateException

Create a module from a JAR and add it to the managed set.

Will initially be disabled. To make sure all available eager modules get enabled, just call: enable(org.netbeans.Module)(Collections.emptySet())

May throw an IOException if the JAR file cannot be opened for some reason, or is malformed.

If there is already a module of the same name managed, throws a duplicate exception. In this case you may wish to delete the original and try again.

You must give it some history object which can be used to provide context for where the module came from and whether it has been here before.

You cannot request that a module be both autoload and eager.

Throws:

IOException

DuplicateException

createBundle

public Module createBundle(File jar,
                           Object history,
                           boolean reloadable,
                           boolean autoload,
                           boolean eager,
                           int startLevel)
                    throws IOException,
                           DuplicateException

Create a module from a JAR representing an OSGi bundle and adds it to the managed set. Behavior is the same as create(java.io.File, java.lang.Object, boolean, boolean, boolean) just adds additional start level info.

Parameters:

startLevel - an OSGi start level. Zero indicates, no changes to default level.

Throws:

InvalidException - if the JAR does not represent an OSGi bundle

IOException

DuplicateException

Since:

2.43

createFixed

public Module createFixed(Manifest mani,
                          Object history,
                          ClassLoader loader)
                   throws InvalidException,
                          DuplicateException

Create a fixed module (e.g. from classpath). Will initially be disabled.

Throws:

InvalidException

DuplicateException

createFixed

public Module createFixed(Manifest mani,
                          Object history,
                          ClassLoader loader,
                          boolean autoload,
                          boolean eager)
                   throws InvalidException,
                          DuplicateException

Create a fixed module (e.g. from classpath) with optional autoload and eager flags. Will initially be disabled.

Throws:

InvalidException

DuplicateException

Since:

2.7

refineClassLoader

public void refineClassLoader(Module m,
                              List parents)

Used by Module to communicate with the ModuleInstaller re. classloader.

shouldDelegateResource

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

Use by OneModuleClassLoader to communicate with the ModuleInstaller re. masking.

delete

public void delete(Module m)
            throws IllegalArgumentException

Remove a module from the managed set. Must be disabled first. Must not be a "fixed" module.

Throws:

IllegalArgumentException

reload

public void reload(Module m)
            throws IllegalArgumentException,
                   IOException

Reload a module. This could make a fresh copy of its JAR file preparing to enable it with different contents; at least it will rescan the manifest. It must currently be disabled and not "fixed", and it will stay disabled after this call; to actually reinstall it requires a separate call. It may or may not actually be marked "reloadable", but for greatest reliability it should be. Besides actually reloading the contents, any cached information about failed dependencies or runtime problems with the module is cleared so it may be tried again.

Throws:

IllegalArgumentException

IOException

enable

public final void enable(Module m)
                  throws IllegalArgumentException,
                         InvalidException

Enable a single module. Must have satisfied its dependencies. Must not be an autoload module, when supported.

Throws:

IllegalArgumentException

InvalidException

See Also:

enable(Set)

disable

public final void disable(Module m)
                   throws IllegalArgumentException

Disable a single module. Must not be required by any enabled modules. Must not be an autoload module, when supported.

Throws:

IllegalArgumentException

See Also:

disable(Set)

enable

public void enable(Set<Module> modules)
            throws IllegalArgumentException,
                   InvalidException

Enable a set of modules together.

Must have satisfied their dependencies (possibly with one another).

Must not contain autoload nor eager modules. Might contain fixed modules (they can only be installed once of course). Other modules may become enabled automatically according to simulateEnable(java.util.Set).

It is permissible to pass in modules which in fact at runtime cannot satisfy their package dependencies, or which ModuleInstaller.prepare(org.netbeans.Module) rejects on the basis of missing contents. In such a case InvalidException will be thrown and nothing will be installed. The InvalidException in such a case should contain a reference to the offending module.

Throws:

IllegalArgumentException

InvalidException

disable

public void disable(Set<Module> modules)
             throws IllegalArgumentException

Disable a set of modules together.

Must not be required by any enabled modules (except one another).

Must not contain autoload nor eager modules. Must not contain fixed modules. Other modules may become disabled automatically according to simulateDisable(java.util.Set).

Throws:

IllegalArgumentException

simulateEnable

public List<Module> simulateEnable(Set<Module> modules)
                            throws IllegalArgumentException

Simulate what would happen if a set of modules were to be enabled. None of the listed modules may be autoload modules, nor eager, nor currently enabled, though they may be fixed (if they have not yet been enabled). It may happen that some of them do not satisfy their dependencies. It may also happen that some of them require other, currently disabled, modules to be enabled in order for them to be enabled. It may further happen that some currently disabled eager modules could be enabled as a result of these modules being enabled. The returned set is the set of all modules that actually could be enabled. It will include the requested modules, minus any that cannot satisfy their dependencies (even on each other), plus any managed but currently disabled modules that would need to be enabled (including autoload modules required by some listed module but not by any currently enabled module), plus any eager modules which can be enabled with the other enablements (and possibly any autoloads needed by those eager modules). Where a requested module requires some token, either it will not be included in the result (in case the dependency cannot be satisfied), or it will, and all modules providing that token which can be included will be included, even if it would suffice to choose only one - unless a module providing that token is already enabled or in the requested list, in which case just the requested module will be listed. Modules are returned in an order in which they could be enabled (where base modules are always enabled before dependent modules). Note that the returned list might include modules which in fact cannot be enabled either because some package dependencies (which are checked only on a live classloader) cannot be met; or ModuleInstaller.prepare(org.netbeans.Module) indicates that the modules are not in a valid format to install; or creating the module classloader fails unexpectedly.

Throws:

IllegalArgumentException

simulateJaveleonReload

public List<Module> simulateJaveleonReload(Module moduleToReload)
                                    throws IllegalArgumentException

Only for use from Javeleon code.

Throws:

IllegalArgumentException

simulateDisable

public List<Module> simulateDisable(Set<Module> modules)
                             throws IllegalArgumentException

Simulate what would happen if a set of modules were to be disabled. None of the listed modules may be autoload modules, nor eager, nor currently disabled, nor fixed. The returned set will list all modules that would actually be disabled, meaning the listed modules, plus any currently enabled but unlisted modules (including autoloads) that require some listed modules, plus any autoloads which would no longer be needed as they were only required by modules otherwise disabled. Provide-require pairs count for purposes of disablement: if the set of requested modules includes all remaining enabled providers of some token, and modules requiring that token will need to be disabled as well. Modules are returned in an order in which they could be disabled (where dependent modules are always disabled before base modules).

Throws:

IllegalArgumentException

shutDown

public boolean shutDown()

Try to shut down the system. First all modules are asked if they wish to close, in the proper order. Assuming they say yes, then they are informed of the close. Returns true if they all said yes.

shutDown

public boolean shutDown(Runnable midHook)

Try to shut down the system. First all modules are asked if they wish to close, in the proper order. Assuming they say yes, a hook is run, then they are informed of the close. If they did not agree to close, the hook is not run.

Parameters:

midHook - a hook to run before closing modules if they agree to close

Returns:

true if they all said yes and the module system is now shut down

Since:

org.netbeans.core/1 1.11