ModuleInstall (NetBeans APIs) - NetBeans API Javadoc 4.1.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.openide.modules
Class ModuleInstall

java.lang.Object
  org.openide.util.SharedClassObject
      org.openide.modules.ModuleInstall

All Implemented Interfaces:: Externalizable, Serializable

public class ModuleInstall
extends SharedClassObject

Provides hooks for a custom module that may be inserted into the IDE. This interface should be implemented by the main class of a module.

Simple modules will likely not need a main class--just a few entries in the manifest file. Even modules with a main class need not do anything in it that is already covered by manifest entries; only additional special functionality need be handled here.

Specify this class in the manifest file with OpenIDE-Module-Install.

Modules wishing to keep state associated with the installation of the module may do so by implementing not only this class but also Externalizable. In this case, they are responsible for reading and writing their own state properly (probably using ObjectOutput.writeObject(java.lang.Object) and ObjectInput.readObject()). Note that state which is logically connected to the user's configuration of the module on a possibly project-specific basis should not be stored this way, but rather using a system option. (Even if this information is not to be displayed, it should still be stored as hidden properties of the system option, so as to be switched properly during project switches.) Storing externalizable state in a ModuleInstall is deprecated.

See Also:: Serialized Form

Constructor Summary

ModuleInstall()


Method Summary

protected boolean clearSharedData()
          Indicate whether the shared data of the last existing instance of this class should be cleared when that instance is finalized.

void close()
          Called when all modules agreed with closing and the IDE will be closed.

boolean closing()
          Called when the IDE is about to exit.

void installed()
          Deprecated. Better to check specific aspects of the module's installation. For example, a globally installed module might be used in several user directories. Only the module itself can know whether its special installation tasks apply to some part of the global installation, or whether they apply to the module's usage in the current user directory. For this reason, implementing this method cannot be guaranteed to have useful effects.

void restored()
          Called when an already-installed module is restored (during IDE startup).

void uninstalled()
          Called when the module is uninstalled (from a running IDE).

void updated(int release, String specVersion)
          Deprecated. Better to check specific aspects of the module's installation. For example, a globally installed module might be used in several user directories. Only the module itself can know whether its special installation tasks apply to some part of the global installation, or whether they apply to the module's usage in the current user directory. For this reason, implementing this method cannot be guaranteed to have useful effects.

void validate()
          Called when a module is being considered for loading.

Methods inherited from class org.openide.util.SharedClassObject

addNotify, addPropertyChangeListener, equals, finalize, findObject, findObject, firePropertyChange, getLock, getProperty, hashCode, initialize, putProperty, putProperty, readExternal, removeNotify, removePropertyChangeListener, reset, writeExternal, writeReplace

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ModuleInstall

public ModuleInstall()

Method Detail

validate

public void validate()
              throws IllegalStateException

Called when a module is being considered for loading. (This would be before installed(), restored(), or updated(int, java.lang.String) are called.) If something is critically wrong with the module (missing ad-hoc dependency, missing license key, etc.) then IllegalStateException may be thrown to prevent it from being loaded (preferably with a localized annotation). The default implementation does nothing. The module cannot assume much about when this method will be called; specifically it cannot rely on layers or manifest sections to be ready, nor for the module's classloader to exist in the system class loader (so if loading bundles, icons, and so on, specifically pass in the class loader of the install class rather than relying on the default modules class loader).

Throws:: IllegalStateException
Since:: 1.24

installed

public void installed()

Deprecated. Better to check specific aspects of the module's installation. For example, a globally installed module might be used in several user directories. Only the module itself can know whether its special installation tasks apply to some part of the global installation, or whether they apply to the module's usage in the current user directory. For this reason, implementing this method cannot be guaranteed to have useful effects.

Called when the module is first installed into the IDE. Should perform whatever setup functions are required. The default implementation calls restored.

Typically, would do one-off functions, and then also call restored().

restored

public void restored()

Called when an already-installed module is restored (during IDE startup). Should perform whatever initializations are required.

Note that it is possible for module code to be run before this method is called, and that code must be ready nonetheless. For example, data loaders might be asked to recognize a file before the module is "restored". For this reason, but more importantly for general performance reasons, modules should avoid doing anything here that is not strictly necessary - often by moving initialization code into the place where the initialization is actually first required (if ever). This method should serve as a place for tasks that must be run once during every startup, and that cannot reasonably be put elsewhere.

Basic programmatic services are available to the module at this stage - for example, its class loader is ready for general use, any objects registered declaratively to lookup (e.g. system options or services) are ready to be queried, and so on.

updated

public void updated(int release,
                    String specVersion)

Called when the module is loaded and the version is higher than by the previous load The default implementation calls restored().

Parameters:: release - The major release number of the old module code name or -1 if not specified.; specVersion - The specification version of the this old module.

uninstalled

public void uninstalled()

Called when the module is uninstalled (from a running IDE). Should remove whatever functionality from the IDE that it had registered.

closing

public boolean closing()

Called when the IDE is about to exit. The default implementation returns true. The module may cancel the exit if it is not prepared to be shut down.

Returns:: true if it is ok to exit the IDE

close

public void close()

Called when all modules agreed with closing and the IDE will be closed.

clearSharedData

protected boolean clearSharedData()

Description copied from class: SharedClassObject

Indicate whether the shared data of the last existing instance of this class should be cleared when that instance is finalized. Subclasses may perform additional tasks on finalization if desired. This method should be overridden in lieu of SharedClassObject.finalize().

The default implementation returns true. Classes which have precious shared data may want to return false, so that all instances may be finalized, after which new instances will pick up the same shared variables without requiring a recalculation.

Overrides:: clearSharedData in class SharedClassObject

Returns:: true if all shared data should be cleared, false if it should stay in memory