Package org.gjt.sp.jedit

Class 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:
    • A file named actions.xml defining plugin actions. Only one such file per plugin is allowed. See ActionSet for syntax.
    • A file named browser.actions.xml defining file system browser actions. Only one such file per plugin is allowed. See ActionSet for syntax.
    • A file named dockables.xml defining dockable windows. Only one such file per plugin is allowed. See DockableWindowManager for syntax.
    • A file named services.xml defining additional services offered by the plugin, such as virtual file systems. Only one such file per plugin is allowed. See ServiceManager for syntax.
    • File with extension .props containing name/value pairs separated by an equals sign. A plugin can supply any number of property files. Property files are used to define plugin men items, plugin option panes, as well as arbitriary settings and strings used by the plugin. See EditPlugin for information about properties used by jEdit. See java.util.Properties for property file syntax.
    • Since jEdit 5.0, files named lang_[language_iso_code].properties are localization files. If one of those files match the current language, jEdit will load it. If a label is missing in the localization file, it will be loaded from the other .props files. Those files will be ignored by jEdit's versions older than 5.0 and do not cause any problem See jEdit's localization wiki
    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

      Nested Classes 
      Modifier and Type Class Description
      static class  PluginJAR.PluginCacheEntry
      Used by the DockableWindowManager and ServiceManager to handle caching.

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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 getActionSet()
      Returns the plugin's action set for the jEdit action context jEdit.getActionContext().
      java.lang.String[] getAllDependentPlugins()  
      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> getDependencies​(java.lang.String classname)
      Returns a list of dependencies by searching the plugin properties.
      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.util.Collection<java.lang.String> getFiles()
      Get the files listed in this plugin and return full paths to them
      java.util.Collection<java.lang.String> getJars()
      Get the jars listed in this plugin and return full paths to them
      static java.util.Set<java.lang.String> getOptionalDependencies​(java.lang.String classname)
      Returns a list of optional dependencies by searching the plugin properties.
      java.lang.String[] getOptionallyDependentPlugins()  
      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)  
      static PluginJAR.PluginCacheEntry getPluginCacheEntry​(java.lang.String path)
      Returns the cache entry for an installed but not loaded 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.
      boolean init()  
      static PluginJAR load​(java.lang.String path, boolean loadDependents)
      Loads a plugin, and its dependent plugins if necessary.
      static java.util.Collection<java.lang.String> parseJarsFilesString​(java.lang.String path, java.lang.String jarsString)
      parse the files listed in plugin.CLASSNAME.jars or plugin.CLASSNAME.files and return full paths to each file of the list.
      static java.util.Collection<java.lang.String> parseJarsFilesStringNames​(java.lang.String jarsString)
      parse the files listed in plugin.CLASSNAME.jars or plugin.CLASSNAME.files and return them as a collection
      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.
      void uninit​(boolean exit)  

      • 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

      • parseJarsFilesString

        public static java.util.Collection<java.lang.String> parseJarsFilesString​(java.lang.String path,
                                                                          java.lang.String jarsString)
        parse the files listed in plugin.CLASSNAME.jars or plugin.CLASSNAME.files and return full paths to each file of the list.
        Since:
        jEdit 5.3pre1

      • parseJarsFilesStringNames

        public static java.util.Collection<java.lang.String> parseJarsFilesStringNames​(java.lang.String jarsString)
        parse the files listed in plugin.CLASSNAME.jars or plugin.CLASSNAME.files and return them as a collection
        Since:
        jEdit 5.3pre1

      • getJars

        public java.util.Collection<java.lang.String> getJars()
        Get the jars listed in this plugin and return full paths to them
        Returns:
        jars full paths or empty collection if plugin is null
        Since:
        jEdit 5.3pre1

      • getFiles

        public java.util.Collection<java.lang.String> getFiles()
        Get the files listed in this plugin and return full paths to them
        Returns:
        files full paths or empty collection if plugin is null
        Since:
        jEdit 5.3pre1

      • 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

      • 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

      • getDependencies

        @Nonnull
public static java.util.Set<java.lang.String> getDependencies​(java.lang.String classname)
                                                       throws java.lang.IllegalArgumentException
        Returns a list of dependencies by searching the plugin properties.
        Parameters:
        classname - The classname of a plugin
        Returns:
        A list of classnames of plugins the plugin depends on.
        Throws:
        java.lang.IllegalArgumentException

      • getOptionalDependencies

        public static java.util.Set<java.lang.String> getOptionalDependencies​(java.lang.String classname)
                                                               throws java.lang.IllegalArgumentException
        Returns a list of optional dependencies by searching the plugin properties.
        Parameters:
        classname - The classname of a plugin
        Returns:
        A list of classnames of plugins the plugin optionally depends on.
        Throws:
        java.lang.IllegalArgumentException

      • 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()
        Returns:
        an array of plugin names that have a hard dependency on this plugin

      • getOptionallyDependentPlugins

        public java.lang.String[] getOptionallyDependentPlugins()
        Returns:
        an array of plugin names that have an optional dependency on this plugin

      • getAllDependentPlugins

        public java.lang.String[] getAllDependentPlugins()
        Returns:
        an array of plugin names that have a dependency or an optional dependency on this plugin, this returns a combination of getDependentPlugins and getOptionallyDependentPlugins.

      • 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

      • getPluginCacheEntry

        public static PluginJAR.PluginCacheEntry getPluginCacheEntry​(java.lang.String path)
                                                      throws java.io.IOException
        Returns the cache entry for an installed but not loaded plugin. There is no need to use this method if the plugin is loaded.
        Parameters:
        path - path to the the plugin jar
        Returns:
        cache entry or null
        Throws:
        java.io.IOException - if jEdit cannot generate cache
        Since:
        jEdit 5.3pre1

      • init

        public boolean init()

      • uninit

        public void uninit​(boolean exit)

      • getResources

        public java.lang.String[] getResources()