Package org.apache.nutch.plugin

## Class PluginRepository

- java.lang.Object
- - org.apache.nutch.plugin.PluginRepository

- All Implemented Interfaces:
    `URLStreamHandlerFactory`

      public class PluginRepository
      extends Object
      implements URLStreamHandlerFactory

  The plugin repository is a registry of all plugins.

  At system boot up a repository is built by parsing the manifest files of all plugins. Plugins that require other plugins which do not exist are not registered. For each plugin a plugin descriptor instance will be created. The descriptor represents all meta information about a plugin. So a plugin instance will be created later when it is required, this allow lazy plugin loading.

  As protocol-plugins need to be registered with the JVM as well, this class also acts as an `URLStreamHandlerFactory` that registers with the JVM and supports all the new protocols as if they were native. Details of how the JVM creates URLs can be seen in the API documentation for the URL constructor.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected static org.slf4j.Logger` | `LOG` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PluginRepository​(Configuration conf)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `URLStreamHandler` | `createURLStreamHandler​(String protocol)` | Invoked whenever a `URL` needs to be instantiated.
    `void` | `finalize()` | Deprecated.
    `static PluginRepository` | `get​(Configuration conf)` | Get a cached instance of the `PluginRepository`
    `Class<?>` | `getCachedClass​(PluginDescriptor pDescriptor, String className)` |
    `ExtensionPoint` | `getExtensionPoint​(String pXpId)` | Returns a extension point identified by a extension point id.
    `Object[]` | `getOrderedPlugins​(Class<?> clazz, String xPointId, String orderProperty)` | Get ordered list of plugins.
    `PluginDescriptor` | `getPluginDescriptor​(String pPluginId)` | Returns the descriptor of one plugin identified by a plugin id.
    `PluginDescriptor[]` | `getPluginDescriptors()` | Returns all registed plugin descriptors.
    `Plugin` | `getPluginInstance​(PluginDescriptor pDescriptor)` | Returns an instance of a plugin.
    `static void` | `main​(String[] args)` | Loads all necessary dependencies for a selected plugin, and then runs one of the classes' main() method.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### LOG

          protected static final org.slf4j.Logger LOG

  - ### Constructor Detail

    - #### PluginRepository

          public PluginRepository​(Configuration conf)
                           throws RuntimeException

      Parameters:
        `conf` - a populated `Configuration`
      Throws:
        `RuntimeException` - if a fatal runtime error is encountered

  - ### Method Detail

    - #### get

          public static PluginRepository get​(Configuration conf)

      Get a cached instance of the `PluginRepository`
      Parameters:
        `conf` - a populated `Configuration`
      Returns:
        a cached instance of the plugin repository

    - #### getPluginDescriptors

          public PluginDescriptor[] getPluginDescriptors()

      Returns all registed plugin descriptors.
      Returns:
        PluginDescriptor[]

    - #### getPluginDescriptor

          public PluginDescriptor getPluginDescriptor​(String pPluginId)

      Returns the descriptor of one plugin identified by a plugin id.
      Parameters:
        `pPluginId` - a pluginId for which the descriptor will be retrieved
      Returns:
        PluginDescriptor

    - #### getExtensionPoint

          public ExtensionPoint getExtensionPoint​(String pXpId)

      Returns a extension point identified by a extension point id.
      Parameters:
        `pXpId` - an extension point id
      Returns:
        a extentsion point

    - #### getPluginInstance

          public Plugin getPluginInstance​(PluginDescriptor pDescriptor)
                                   throws PluginRuntimeException

      Returns an instance of a plugin. Plugin instances are cached. So a plugin exist only as one instance. This allow a central management of plugin's own resources.

      After creating the plugin instance the startUp() method is invoked. The plugin use a own classloader that is used as well by all instance of extensions of the same plugin. This class loader use all exported libraries from the dependent plugins and all plugin libraries.

      Parameters:
        `pDescriptor` - a `PluginDescriptor` for which to retrieve a `Plugin` instance
      Returns:
        a `Plugin` instance
      Throws:
        `PluginRuntimeException` - if there is a fatal runtime plugin error

    - #### finalize

          @Deprecated
          public void finalize()
                        throws Throwable

      Deprecated.
      Attempts to shut down all activated plugins.
      Overrides:
        `finalize` in class `Object`
      Throws:
        `Throwable`
      See Also:
        JEP 421: Deprecate Finalization for Removal, `Object.finalize()`

    - #### getCachedClass

          public Class<?> getCachedClass​(PluginDescriptor pDescriptor,
                                         String className)
                                  throws ClassNotFoundException

      Throws:
        `ClassNotFoundException`

    - #### getOrderedPlugins

          public Object[] getOrderedPlugins​(Class<?> clazz,
                                            String xPointId,
                                            String orderProperty)

      Get ordered list of plugins. Filter and normalization plugins are applied in a configurable "pipeline" order, e.g., if one plugin depends on the output of another plugin. This method loads the plugins in the order defined by orderProperty. If orderProperty is empty or unset, all active plugins of the given interface and extension point are loaded.
      Parameters:
        `clazz` - interface class implemented by required plugins
        `xPointId` - extension point id of required plugins
        `orderProperty` - property name defining plugin order
      Returns:
        array of plugin instances

    - #### main

          public static void main​(String[] args)
                           throws Exception

      Loads all necessary dependencies for a selected plugin, and then runs one of the classes' main() method.
      Parameters:
        `args` - plugin ID (needs to be activated in the configuration), and the class name. The rest of arguments is passed to the main method of the selected class.
      Throws:
        `Exception` - if there is an error running this Class

    - #### createURLStreamHandler

          public URLStreamHandler createURLStreamHandler​(String protocol)

      Invoked whenever a `URL` needs to be instantiated. Tries to find a suitable extension and allows it to provide a `URLStreamHandler`.

      This is done by several attempts:
      - Find a protocol plugin that implements the desired protocol. If found, instantiate it so eventually the plugin can install a `URLStreamHandler` through a static hook.
      - If the plugin specifies a `URLStreamHandler` in its `plugin.xml` manifest, return an instance of this `URLStreamHandler`. Example:

              ...
              <implementation id="org.apache.nutch.protocol.foo.Foo" class="org.apache.nutch.protocol.foo.Foo">
                  <parameter name="protocolName" value="foo"/>
                  <parameter name="urlStreamHandler" value="org.apache.nutch.protocol.foo.Handler"/>
              </implementation>
              ...

      - If all else fails, return null. This will fallback to the JVM's method of evaluating the system property `java.protocol.handler.pkgs`.
      Specified by:
        `createURLStreamHandler` in interface `URLStreamHandlerFactory`
      Returns:
        the URLStreamHandler found, or null.
      See Also:
        `URL`, NUTCH-2429