org.gjt.sp.jedit
Class PluginJAR

java.lang.Object
  extended by org.gjt.sp.jedit.PluginJAR

public class PluginJAR
extends java.lang.Object

Loads and unloads plugins.

JAR file contents

When loading a plugin, jEdit looks for the following resources: For a plugin to actually do something once it is resident in memory, it must contain a class whose name ends with Plugin. This class, known as the plugin core class must extend EditPlugin and define a few required properties, otherwise it is ignored.

Dynamic and deferred loading

Unlike in prior jEdit versions, jEdit 4.2 and later allow plugins to be added and removed to the resident set at any time using the jEdit.addPluginJAR(String) and jEdit.removePluginJAR(PluginJAR,boolean) methods. Furthermore, the plugin core class might not be loaded until the plugin is first used. See EditPlugin.start() for a full description.

Since:
jEdit 4.2pre1
See Also:
jEdit.getProperty(String), jEdit.getPlugin(String), jEdit.getPlugins(), jEdit.getPluginJAR(String), jEdit.getPluginJARs(), jEdit.addPluginJAR(String), jEdit.removePluginJAR(PluginJAR,boolean), ActionSet, DockableWindowManager, OptionPane, PluginJAR, ServiceManager

Nested Class Summary
static class PluginJAR.PluginCacheEntry
          Used by the DockableWindowManager and ServiceManager to handle caching.
 
Constructor Summary
PluginJAR(java.io.File file)
          Creates a PluginJAR object which is not necessarily loaded, but can be later.
 
Method Summary
 void activatePlugin()
          Loads the plugin core class.
 void activatePluginIfNecessary()
          Should be called after a new plugin is installed.
 boolean checkDependencies()
          Returns true if all dependencies are satisified, false otherwise.
 void deactivatePlugin(boolean exit)
          Unloads the plugin core class.
static java.lang.String findPlugin(java.lang.String className)
          Unlike getPlugin(), will return a PluginJAR that is not yet loaded, given its classname.
 PluginJAR.PluginCacheEntry generateCache()
           
 ActionSet getActions()
          Deprecated. Call getActionSet() instead
 ActionSet getActionSet()
          Returns the plugin's action set for the jEdit action context jEdit.getActionContext().
 ActionSet getBrowserActionSet()
          Returns the plugin's action set for the file system browser action context VFSBrowser.getActionContext().
 java.lang.String getCachePath()
          Returns the full path name of this plugin's summary file.
 JARClassLoader getClassLoader()
          Returns the plugin's class loader.
static java.util.Set<java.lang.String> getDependencySet(java.lang.String className)
           
 java.lang.String[] getDependentPlugins()
           
 java.net.URL getDockablesURI()
          Returns the location of the plugin's dockables.xml file.
 java.io.File getFile()
          Returns a file pointing to the plugin JAR.
 java.lang.String getPath()
          Returns the full path name of this plugin's JAR file.
 EditPlugin getPlugin()
          Returns the plugin core class for this JAR file.
static PluginJAR.PluginCacheEntry getPluginCache(PluginJAR plugin)
           
 java.util.Set<java.lang.String> getRequiredJars()
          Returns the required jars of this plugin.
 java.lang.String[] getResources()
           
 java.net.URL getServicesURI()
          Returns the location of the plugin's services.xml file.
 java.util.zip.ZipFile getZipFile()
          Returns the plugin's JAR file, opening it if necessary.
static PluginJAR load(java.lang.String path, boolean loadDependents)
          Loads a plugin, and its dependent plugins if necessary.
 java.lang.String toString()
           
static void transitiveClosure(java.lang.String[] dependents, java.util.List<java.lang.String> listModel)
          If plugin A is needed by B, and B is needed by C, we want to tell the user that A is needed by B and C when they try to unload A.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PluginJAR

public PluginJAR(java.io.File file)
Creates a PluginJAR object which is not necessarily loaded, but can be later.

See Also:
load(String, boolean)
Method Detail

load

public static PluginJAR load(java.lang.String path,
                             boolean loadDependents)
Loads a plugin, and its dependent plugins if necessary.

Since:
jEdit 4.3pre7

getPath

public java.lang.String getPath()
Returns the full path name of this plugin's JAR file.


findPlugin

public static java.lang.String findPlugin(java.lang.String className)
Unlike getPlugin(), will return a PluginJAR that is not yet loaded, given its classname.

Parameters:
className - a class name
Returns:
the JARpath of the first PluginJAR it can find which contains this className, or null if not found.
Since:
4.3pre7

getCachePath

public java.lang.String getCachePath()
Returns the full path name of this plugin's summary file. The summary file is used to store certain information which allows loading of the plugin's resources and core class to be deferred until the plugin is first used. As long as a plugin is using the jEdit 4.2 plugin API, no extra effort is required to take advantage of the summary cache.


getDependencySet

public static java.util.Set<java.lang.String> getDependencySet(java.lang.String className)
Parameters:
className - of a plugin that we wish to load
Returns:
an ordered set of JARpaths that contains the plugins that need to be (re)loaded, in the correct order.

getFile

public java.io.File getFile()
Returns a file pointing to the plugin JAR.


getClassLoader

public JARClassLoader getClassLoader()
Returns the plugin's class loader.


getZipFile

public java.util.zip.ZipFile getZipFile()
                                 throws java.io.IOException
Returns the plugin's JAR file, opening it if necessary.

Throws:
java.io.IOException
Since:
jEdit 4.2pre1

getActions

public ActionSet getActions()
Deprecated. Call getActionSet() instead


getActionSet

public ActionSet getActionSet()
Returns the plugin's action set for the jEdit action context jEdit.getActionContext(). These actions are loaded from the actions.xml file; see ActionSet. .

Since:
jEdit 4.2pre1

getBrowserActionSet

public ActionSet getBrowserActionSet()
Returns the plugin's action set for the file system browser action context VFSBrowser.getActionContext(). These actions are loaded from the browser.actions.xml file; see ActionSet. .

Since:
jEdit 4.2pre1

checkDependencies

public boolean checkDependencies()
Returns true if all dependencies are satisified, false otherwise. Also if dependencies are not satisfied, the plugin is marked as "broken".


getRequiredJars

public java.util.Set<java.lang.String> getRequiredJars()
Returns the required jars of this plugin.

Returns:
the required jars of this plugin
Since:
jEdit 4.3pre12

transitiveClosure

public static void transitiveClosure(java.lang.String[] dependents,
                                     java.util.List<java.lang.String> listModel)
If plugin A is needed by B, and B is needed by C, we want to tell the user that A is needed by B and C when they try to unload A.

Parameters:
dependents - a set of plugins which we wish to disable
listModel - a set of plugins which will be affected, and will need to be disabled also.

getDependentPlugins

public java.lang.String[] getDependentPlugins()

getPlugin

public EditPlugin getPlugin()
Returns the plugin core class for this JAR file. Note that if the plugin has not been activated, this will return an instance of EditPlugin.Deferred. If you need the actual plugin core class instance, call activatePlugin() first. If the plugin is not yet loaded, returns null

Since:
jEdit 4.2pre1

activatePlugin

public void activatePlugin()
Loads the plugin core class. Does nothing if the plugin core class has already been loaded. This method might be called on startup, depending on what properties are set. See EditPlugin.start(). This method is thread-safe.

Since:
jEdit 4.2pre1

activatePluginIfNecessary

public void activatePluginIfNecessary()
Should be called after a new plugin is installed.

Since:
jEdit 4.2pre2

deactivatePlugin

public void deactivatePlugin(boolean exit)
Unloads the plugin core class. Does nothing if the plugin core class has not been loaded. This method can only be called from the AWT event dispatch thread!

Since:
jEdit 4.2pre3
See Also:
EditPlugin.stop()

getDockablesURI

public java.net.URL getDockablesURI()
Returns the location of the plugin's dockables.xml file.

Since:
jEdit 4.2pre1

getServicesURI

public java.net.URL getServicesURI()
Returns the location of the plugin's services.xml file.

Since:
jEdit 4.2pre1

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getPluginCache

public static PluginJAR.PluginCacheEntry getPluginCache(PluginJAR plugin)

getResources

public java.lang.String[] getResources()

generateCache

public PluginJAR.PluginCacheEntry generateCache()
                                         throws java.io.IOException
Throws:
java.io.IOException