org.crosswire.common.util

## Class PluginUtil

- java.lang.Object
- - org.crosswire.common.util.PluginUtil

-     public final class PluginUtil
      extends Object

  A plugin maps one or more implementations to an interface or abstract class via a properties file whose suffix is "plugin". When there is more than one implementation, one is marked as a default.
  Author:
    DM Smith
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static String` | `DEFAULT` The string for default implementations
    `static String` | `EXTENSION_PLUGIN` Extension for properties files
    `private static org.slf4j.Logger` | `log` The log stream

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `PluginUtil()` Prevent instantiation

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <T> T` | `getImplementation(Class<T> clazz)` Get and instantiate the preferred implementor of some interface or abstract class.
    `static <T> Class<T>` | `getImplementor(Class<T> clazz)` Get the preferred implementor of some interface or abstract class.
    `static <T> Class<T>[]` | `getImplementors(Class<T> clazz)` Get the known implementors of some interface or abstract class.
    `static <T> Map<String,Class<T>>` | `getImplementorsMap(Class<T> clazz)` Get a map of known implementors of some interface or abstract class.
    `static <T> PropertyMap` | `getPlugin(Class<T> clazz)` Get and load a plugin file by looking it up as a resource.

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

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

- - ### Field Detail

    - #### EXTENSION_PLUGIN

          public static final String EXTENSION_PLUGIN

      Extension for properties files
      See Also:
        Constant Field Values

    - #### DEFAULT

          private static final String DEFAULT

      The string for default implementations
      See Also:
        Constant Field Values

    - #### log

          private static final org.slf4j.Logger log

      The log stream

  - ### Constructor Detail

    - #### PluginUtil

          private PluginUtil()

      Prevent instantiation

  - ### Method Detail

    - #### getImplementors

          public static <T> Class<T>[] getImplementors(Class<T> clazz)

      Get the known implementors of some interface or abstract class. This is currently done by looking up a plugin file by the name of the given class, and assuming that values are implementors of said class. Those that are not are warned, but ignored.
      Type Parameters:
        `T` - the implementor's type
      Parameters:
        `clazz` - The class or interface to find implementors of.
      Returns:
        The list of implementing classes.

    - #### getImplementorsMap

          public static <T> Map<String,Class<T>> getImplementorsMap(Class<T> clazz)

      Get a map of known implementors of some interface or abstract class. This is currently done by looking up a plugins file by the name of the given class, and assuming that values are implementors of said class. Those that are not are warned, but ignored. The reply is in the form of a map of keys=strings, and values=classes in case you need to get at the names given to the classes in the plugin file.
      Type Parameters:
        `T` - the implementor's type
      Parameters:
        `clazz` - The class or interface to find implementors of.
      Returns:
        The map of implementing classes.
      See Also:
        `getImplementors(Class)`

    - #### getImplementor

          public static <T> Class<T> getImplementor(Class<T> clazz)
                                         throws IOException,
                                                ClassNotFoundException,
                                                ClassCastException

      Get the preferred implementor of some interface or abstract class. This is currently done by looking up a plugins file by the name of the given class, and assuming that the "default" key is an implementation of said class. Warnings are given otherwise.
      Type Parameters:
        `T` - the implementor's type
      Parameters:
        `clazz` - The class or interface to find an implementation of.
      Returns:
        The configured implementing class.
      Throws:
        `MalformedURLException` - if the plugin file can not be found
        `IOException` - if there is a problem reading the found file
        `ClassNotFoundException` - if the read contents are not found
        `ClassCastException` - if the read contents are not valid
      See Also:
        `getImplementors(Class)`

    - #### getImplementation

          public static <T> T getImplementation(Class<T> clazz)
                                     throws MalformedURLException,
                                            ClassCastException,
                                            IOException,
                                            ClassNotFoundException,
                                            InstantiationException,
                                            IllegalAccessException

      Get and instantiate the preferred implementor of some interface or abstract class.
      Type Parameters:
        `T` - the implementor's type
      Parameters:
        `clazz` - The class or interface to find an implementation of.
      Returns:
        The configured implementing class.
      Throws:
        `MalformedURLException` - if the plugin file can not be found
        `IOException` - if there is a problem reading the found file
        `ClassNotFoundException` - if the read contents are not found
        `ClassCastException` - if the read contents are not valid
        `InstantiationException` - if the new object can not be instantiated
        `IllegalAccessException` - if the new object can not be instantiated
      See Also:
        `getImplementors(Class)`

    - #### getPlugin

          public static <T> PropertyMap getPlugin(Class<T> clazz)
                                       throws IOException

      Get and load a plugin file by looking it up as a resource.
      Type Parameters:
        `T` - the implementor's type
      Parameters:
        `clazz` - The name of the desired resource
      Returns:
        The found and loaded plugin file
      Throws:
        `IOException` - if the resource can not be loaded
        `MissingResourceException` - if the resource can not be found