Package org.openstreetmap.josm.plugins

Class PluginHandler

  • public final class PluginHandler
extends java.lang.Object
    PluginHandler is basically a collection of static utility functions used to bootstrap and manage the loaded plugins.
    Since:
    1326

    • Method Detail

      • getPlugins

        public static java.util.List<PluginInformation> getPlugins()
        Returns the list of currently installed and loaded plugins, sorted by name.
        Returns:
        the list of currently installed and loaded plugins, sorted by name
        Since:
        10982

      • getResourceClassLoaders

        public static java.util.Collection<java.lang.ClassLoader> getResourceClassLoaders()
        Returns all ClassLoaders whose resource should be searched.
        Returns:
        all ClassLoaders whose resource should be searched

      • load

        public static <S> java.util.ServiceLoader<S> load​(java.lang.Class<S> service)
        Get a ServiceLoader for the specified service. This uses getJoinedPluginResourceCL() as the class loader, so that we don't have to iterate through the ClassLoaders from getPluginClassLoaders().
        Type Parameters:
        S - The service type
        Parameters:
        service - The service class to look for
        Returns:
        The service loader
        Since:
        18833

      • filterDeprecatedPlugins

        static void filterDeprecatedPlugins​(java.awt.Component parent,
                                    java.util.Collection<java.lang.String> plugins)
        Removes deprecated plugins from a collection of plugins. Modifies the collection plugins.

        Also notifies the user about removed deprecated plugins

        Parameters:
        parent - The parent Component used to display warning popup
        plugins - the collection of plugins

      • filterUnmaintainedPlugins

        static void filterUnmaintainedPlugins​(java.awt.Component parent,
                                      java.util.Collection<java.lang.String> plugins)
        Removes unmaintained plugins from a collection of plugins. Modifies the collection plugins. Also removes the plugin from the list of plugins in the preferences, if necessary.

        Asks the user for every unmaintained plugin whether it should be removed.

        Parameters:
        parent - The parent Component used to display warning popup
        plugins - the collection of plugins

      • checkAndConfirmPluginUpdate

        public static boolean checkAndConfirmPluginUpdate​(java.awt.Component parent)
        Checks whether the locally available plugins should be updated and asks the user if running an update is OK. An update is advised if JOSM was updated to a new version since the last plugin updates or if the plugins were last updated a long time ago.
        Parameters:
        parent - the parent component relative to which the confirmation dialog is to be displayed
        Returns:
        true if a plugin update should be run; false, otherwise

      • alertMissingRequiredPlugin

        private static void alertMissingRequiredPlugin​(java.awt.Component parent,
                                               java.lang.String plugin,
                                               java.util.Set<java.lang.String> missingRequiredPlugin)
        Alerts the user if a plugin required by another plugin is missing, and offer to download them & restart JOSM
        Parameters:
        parent - The parent Component used to display error popup
        plugin - the plugin
        missingRequiredPlugin - the missing required plugin

      • downloadRequiredPluginsAndRestart

        private static void downloadRequiredPluginsAndRestart​(java.awt.Component parent,
                                                      java.util.Set<java.lang.String> missingRequiredPlugin)

      • logWrongPlatform

        private static void logWrongPlatform​(java.lang.String plugin,
                                     java.lang.String pluginPlatform)

      • alertJavaUpdateRequired

        private static void alertJavaUpdateRequired​(java.awt.Component parent,
                                            java.lang.String plugin,
                                            int requiredVersion)

      • alertJOSMUpdateRequired

        private static void alertJOSMUpdateRequired​(java.awt.Component parent,
                                            java.lang.String plugin,
                                            int requiredVersion)

      • checkLoadPreconditions

        public static boolean checkLoadPreconditions​(java.awt.Component parent,
                                             java.util.Collection<PluginInformation> plugins,
                                             PluginInformation plugin)
        Checks whether all preconditions for loading the plugin plugin are met. The current Java and JOSM versions must be compatible with the plugin and no other plugins this plugin depends on should be missing.
        Parameters:
        parent - The parent Component used to display error popup
        plugins - the collection of all loaded plugins
        plugin - the plugin for which preconditions are checked
        Returns:
        true, if the preconditions are met; false otherwise

      • checkRequiredPluginsPreconditions

        public static boolean checkRequiredPluginsPreconditions​(java.awt.Component parent,
                                                        java.util.Collection<PluginInformation> plugins,
                                                        PluginInformation plugin,
                                                        boolean local)
        Checks if required plugins preconditions for loading the plugin plugin are met. No other plugins this plugin depends on should be missing.
        Parameters:
        parent - The parent Component used to display error popup. If parent is null, the error popup is suppressed
        plugins - the collection of all processed plugins
        plugin - the plugin for which preconditions are checked
        local - Determines if the local or up-to-date plugin dependencies are to be checked.
        Returns:
        true, if the preconditions are met; false otherwise
        Since:
        5601

      • findMissingPlugins

        private static java.util.Set<java.lang.String> findMissingPlugins​(java.util.Collection<PluginInformation> plugins,
                                                                  PluginInformation plugin,
                                                                  boolean local)
        Find the missing plugin(s) for a specified plugin
        Parameters:
        plugins - The currently loaded plugins
        plugin - The plugin to find the missing information for
        local - Determines if the local or up-to-date plugin dependencies are to be checked.
        Returns:
        A set of missing plugins for the given plugin

      • getJoinedPluginResourceCL

        private static DynamicURLClassLoader getJoinedPluginResourceCL()
        Get class loader to locate resources from plugins.

        It joins URLs of all plugins, to find images, etc. (Not for loading Java classes - each plugin has a separate PluginClassLoader for that purpose.)

        Returns:
        class loader to locate resources from plugins

      • extendJoinedPluginResourceCL

        private static void extendJoinedPluginResourceCL​(java.util.Collection<PluginInformation> plugins)
        Add more plugins to the joined plugin resource class loader.
        Parameters:
        plugins - the plugins to add

      • loadPlugin

        private static void loadPlugin​(java.awt.Component parent,
                               PluginInformation plugin,
                               PluginClassLoader pluginClassLoader)
        Loads and instantiates the plugin described by plugin using the class loader pluginClassLoader.
        Parameters:
        parent - The parent component to be used for the displayed dialog
        plugin - the plugin
        pluginClassLoader - the plugin class loader

      • loadPlugins

        public static void loadPlugins​(java.awt.Component parent,
                               java.util.Collection<PluginInformation> plugins,
                               ProgressMonitor monitor)
        Loads the plugin in plugins from locally available jar files into memory.
        Parameters:
        parent - The parent component to be used for the displayed dialog
        plugins - the list of plugins
        monitor - the progress monitor. Defaults to NullProgressMonitor.INSTANCE if null.

      • generateClassloaders

        private static void generateClassloaders​(java.util.List<PluginInformation> toLoad)
        Generate classloaders for a list of plugins
        Parameters:
        toLoad - The plugins to generate the classloaders for

      • resolveDependencies

        private static void resolveDependencies​(java.util.List<PluginInformation> toLoad)
        Resolve dependencies for a list of plugins
        Parameters:
        toLoad - The plugins to resolve dependencies for

      • alertMissingPluginInformation

        private static void alertMissingPluginInformation​(java.awt.Component parent,
                                                  java.util.Collection<java.lang.String> plugins)

      • buildListOfPluginsToLoad

        public static java.util.List<PluginInformation> buildListOfPluginsToLoad​(java.awt.Component parent,
                                                                         ProgressMonitor monitor)
        Builds the list of plugins to load. Deprecated and unmaintained plugins are filtered out. This involves user interaction. This method displays alert and confirmation messages.
        Parameters:
        parent - The parent component to be used for the displayed dialog
        monitor - the progress monitor. Defaults to NullProgressMonitor.INSTANCE if null.
        Returns:
        the list of plugins to load (as set of plugin names)

      • updatePlugins

        public static java.util.Collection<PluginInformation> updatePlugins​(java.awt.Component parent,
                                                                    java.util.Collection<PluginInformation> pluginsWanted,
                                                                    ProgressMonitor monitor,
                                                                    boolean displayErrMsg)
        Updates the plugins in plugins.
        Parameters:
        parent - the parent component for message boxes
        pluginsWanted - the collection of plugins to update. Updates all plugins if null
        monitor - the progress monitor. Defaults to NullProgressMonitor.INSTANCE if null.
        displayErrMsg - if true, a blocking error message is displayed in case of I/O exception.
        Returns:
        the list of plugins to load
        Throws:
        java.lang.IllegalArgumentException - if plugins is null

      • confirmDisablePlugin

        public static boolean confirmDisablePlugin​(java.awt.Component parent,
                                           java.lang.String reason,
                                           java.lang.String name)
        Ask the user for confirmation that a plugin shall be disabled.
        Parameters:
        parent - The parent component to be used for the displayed dialog
        reason - the reason for disabling the plugin
        name - the plugin name
        Returns:
        true, if the plugin shall be disabled; false, otherwise

      • getPlugin

        public static java.lang.Object getPlugin​(java.lang.String name)
        Returns the plugin of the specified name.
        Parameters:
        name - The plugin name
        Returns:
        The plugin of the specified name, if installed and loaded, or null otherwise.

      • getPluginClassLoader

        public static PluginClassLoader getPluginClassLoader​(java.lang.String name)
        Returns the plugin class loader for the plugin of the specified name.
        Parameters:
        name - The plugin name
        Returns:
        The plugin class loader for the plugin of the specified name, if installed and loaded, or null otherwise.
        Since:
        12323

      • addDownloadSelection

        public static void addDownloadSelection​(java.util.List<DownloadSelection> downloadSelections)
        Called in the download dialog to give the plugins a chance to modify the list of bounding box selectors.
        Parameters:
        downloadSelections - list of bounding box selectors

      • installDownloadedPlugins

        public static void installDownloadedPlugins​(java.util.Collection<PluginInformation> pluginsToLoad,
                                            boolean dowarn)
        Installs downloaded plugins. Moves files with the suffix ".jar.new" to the corresponding ".jar" files.

        If dowarn is true, this methods emits warning messages on the console if a downloaded but not yet installed plugin .jar can't be be installed. If dowarn is false, the installation of the respective plugin is silently skipped.

        Parameters:
        pluginsToLoad - list of plugin informations to update
        dowarn - if true, warning messages are displayed; false otherwise
        Since:
        13294

      • isValidJar

        public static boolean isValidJar​(java.io.File jar)
        Determines if the specified file is a valid and accessible JAR file.
        Parameters:
        jar - The file to check
        Returns:
        true if file can be opened as a JAR file.
        Since:
        5723

      • findUpdatedJar

        public static java.io.File findUpdatedJar​(java.lang.String name)
        Replies the updated jar file for the given plugin name.
        Parameters:
        name - The plugin name to find.
        Returns:
        the updated jar file for the given plugin name. null if not found or not readable.
        Since:
        5601

      • refreshLocalUpdatedPluginInfo

        public static void refreshLocalUpdatedPluginInfo​(java.util.Collection<PluginInformation> updatedPlugins)
        Refreshes the given PluginInformation objects with new contents read from their corresponding jar file.
        Parameters:
        updatedPlugins - The PluginInformation objects to update.
        Since:
        5601

      • getPluginCausingException

        private static PluginProxy getPluginCausingException​(java.lang.Throwable ex)
        Replies the plugin which most likely threw the exception ex.
        Parameters:
        ex - the exception
        Returns:
        the plugin; null, if the exception probably wasn't thrown from a plugin

      • updateOrdisablePluginAfterException

        public static PluginDownloadTask updateOrdisablePluginAfterException​(java.lang.Throwable e)
        Checks whether the exception e was thrown by a plugin. If so, conditionally updates or deactivates the plugin, but asks the user first.
        Parameters:
        e - the exception
        Returns:
        plugin download task if the plugin has been updated to a newer version, null if it has been disabled or kept as it

      • getBugReportInformation

        public static java.util.Collection<java.lang.String> getBugReportInformation()
        Returns the list of loaded plugins as a String to be displayed in status report. Useful for bug reports.
        Returns:
        The list of loaded plugins

      • getInfoPanel

        public static javax.swing.JPanel getInfoPanel()
        Returns the list of loaded plugins as a JPanel to be displayed in About dialog.
        Returns:
        The list of loaded plugins (one "line" of Swing components per plugin)

      • getDeprecatedAndUnmaintainedPlugins

        public static java.util.Set<java.lang.String> getDeprecatedAndUnmaintainedPlugins()
        Returns the set of deprecated and unmaintained plugins.
        Returns:
        set of deprecated and unmaintained plugins names.
        Since:
        8938

      • removePlugins

        public static boolean removePlugins​(java.util.List<PluginInformation> deactivatedPlugins)
        Remove deactivated plugins, returning true if JOSM should restart
        Parameters:
        deactivatedPlugins - The plugins to deactivate
        Returns:
        true if there was a plugin that requires a restart
        Since:
        15508