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 final org.slf4j.Logger`
  `LOG`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `PluginRepository(Configuration conf)`

- ## Method Summary

  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 Details

  - ### LOG

    protected static final org.slf4j.Logger LOG

- ## Constructor Details

  - ### PluginRepository

    public PluginRepository(Configuration conf) throws RuntimeException
    Parameters:
      `conf` - a populated `Configuration`
    Throws:
      `RuntimeException` - if a fatal runtime error is encountered

- ## Method Details

  - ### 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