org.crosswire.common.util

## Class CWClassLoader

- java.lang.Object
- - java.lang.ClassLoader
  - - org.crosswire.common.util.CWClassLoader

-     public final class CWClassLoader
      extends ClassLoader

  CWClassLoader extends the regular class loader by using looking in more places. This is needed so that ResourceBundle can find resources that are not held in the same package as the class. This is expressed as a list of locations, called homes, that the program will look in.
  Author:
    DM Smith
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `CWClassLoader.PrivilegedLoader<T>` PrivilegedLoader creates a CWClassLoader if it is able to obtain java security permissions to do so.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static URI[]` | `homes` Notion of a project's home from where additional resources can be found.
    `private Class<?>` | `owner` The class to which the resources belong

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CWClassLoader()` Creates a class loader that finds resources for the calling class that may not be in the class' package.
    `CWClassLoader(Class<?> resourceOwner)` Creates a class loader that finds resources for the supplied class that may not be in the class' package.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private String` | `adjustPackageSearch(String aSearch)` Prefix the search with a package prefix, if not already.
    `private String` | `adjustPathSearch(String aSearch)` Change all but a leading '/' to '.'
    `static URI` | `findHomeResource(String search)` Look for the resource in the home directories, returning the first readable file.
    `URL` | `findResource(String search)`
    `ClassLoader` | `getClassLoader()` Pick the best class loader
    `static URI` | `getHome(int i)` If the application has set the homes, it will return the application's requested home directory, otherwise it returns null.
    `static CWClassLoader` | `instance()` Creates a privileged class loader that finds resources for the calling class that may not be in the class' package.
    `static CWClassLoader` | `instance(Class<?> resourceOwner)` Creates a privileged class loader that finds resources for the supplied class that may not be in the class' package.
    `private static ClassLoader` | `pickLoader(ClassLoader loader1, ClassLoader loader2)` Returns 'true' if 'loader2' is a delegation child of 'loader1' [or if 'loader1'=='loader2'].
    `static void` | `setHome(URI[] newHomes)` Establish the applications home directory from where additional resources can be found.

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

      `clearAssertionStatus, defineClass, defineClass, defineClass, defineClass, definePackage, findClass, findLibrary, findLoadedClass, findResources, findSystemClass, getClassLoadingLock, getPackage, getPackages, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, loadClass, registerAsParallelCapable, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners`

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

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

- - ### Field Detail

    - #### owner

          private Class<?> owner

      The class to which the resources belong

    - #### homes

          private static URI[] homes

      Notion of a project's home from where additional resources can be found.

  - ### Constructor Detail

    - #### CWClassLoader

          CWClassLoader(Class<?> resourceOwner)

      Creates a class loader that finds resources for the supplied class that may not be in the class' package. You can use this within base classes by passing getClass() to load resources for a derived class.
      Parameters:
        `resourceOwner` - is the owner of the resource

    - #### CWClassLoader

          CWClassLoader()

      Creates a class loader that finds resources for the calling class that may not be in the class' package. Use this only within classes that are directly looking up their resources.

  - ### Method Detail

    - #### instance

          public static CWClassLoader instance(Class<?> resourceOwner)

      Creates a privileged class loader that finds resources for the supplied class that may not be in the class' package. You can use this within base classes by passing getClass() to load resources for a derived class.
      Parameters:
        `resourceOwner` - is the owner of the resource
      Returns:
        the CrossWire Class Loader

    - #### instance

          public static CWClassLoader instance()

      Creates a privileged class loader that finds resources for the calling class that may not be in the class' package. Use this only within classes that are directly looking up their resources.
      Returns:
        the CrossWire Class Loader

    - #### findResource

          public URL findResource(String search)

      Overrides:
        `findResource` in class `ClassLoader`

    - #### adjustPackageSearch

          private String adjustPackageSearch(String aSearch)

      Prefix the search with a package prefix, if not already. Skip a leading '/' if present.
      Parameters:
        `aSearch` - the search to adjust
      Returns:
        the adjusted search

    - #### adjustPathSearch

          private String adjustPathSearch(String aSearch)

      Change all but a leading '/' to '.'
      Parameters:
        `aSearch` - the search to adjust
      Returns:
        the adjusted search

    - #### getClassLoader

          public ClassLoader getClassLoader()

      Pick the best class loader
      Returns:
        the class loader

    - #### pickLoader

          private static ClassLoader pickLoader(ClassLoader loader1,
                               ClassLoader loader2)

      Returns 'true' if 'loader2' is a delegation child of 'loader1' [or if 'loader1'=='loader2']. Of course, this works only for classloaders that set their parent pointers correctly. 'null' is interpreted as the primordial loader [i.e., everybody's parent].
      Parameters:
        `loader1` - a class loader to consider
        `loader2` - a class loader to consider
      Returns:
        one of the class loaders

    - #### getHome

          public static URI getHome(int i)

      If the application has set the homes, it will return the application's requested home directory, otherwise it returns null.
      Parameters:
        `i` - get the i-th home
      Returns:
        Returns the home.

    - #### setHome

          public static void setHome(URI[] newHomes)

      Establish the applications home directory from where additional resources can be found. URL is expected to end with the directory name, not '/'.
      Parameters:
        `newHomes` - The home to set.

    - #### findHomeResource

          public static URI findHomeResource(String search)

      Look for the resource in the home directories, returning the first readable file.
      Parameters:
        `search` - must be non-null, non-empty
      Returns:
        the URI of the home of the resource