org.openide.modules
Class ModuleInstall

java.lang.Object
  extended byorg.openide.util.SharedClassObject
      extended byorg.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()
           
 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)
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 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()

 

Built on May 3 2007.  |  Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.