org.flexdock.util

## Class ResourceManager

- java.lang.Object
- - org.flexdock.util.ResourceManager

-     public class ResourceManager
      extends java.lang.Object

  This class provides `static` convenience methods for resource management, including resource lookups and image, icon, and cursor creation.
  Author:
    Chris Butler

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `LIBRARY_EXTENSION` Defines the file extension used by native shared libraries on the current system.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `close(java.io.InputStream in)` Calls `close()` on the specified `InputStream`.
    `static void` | `close(java.io.OutputStream out)` Calls `close()` on the specified `OutputStream`.
    `static void` | `close(java.net.Socket socket)` Calls `close()` on the specified `Socket`.
    `static java.awt.Cursor` | `createCursor(java.lang.String url, java.awt.Point hotPoint, java.lang.String name)` Returns a `Cursor` object based on the specified resource URL.
    `static java.awt.Cursor` | `createCursor(java.net.URL imageURL, java.awt.Point hotPoint, java.lang.String name)` Returns a `Cursor` object based on the specified resource URL.
    `static javax.swing.ImageIcon` | `createIcon(java.lang.String url)` Returns an `ImageIcon` object based on the specified resource URL.
    `static java.awt.Image` | `createImage(java.lang.String url)` Returns an `Image` object based on the specified resource URL.
    `static java.awt.Image` | `createImage(java.net.URL imageLocation)` Returns an `Image` object based on the specified resource URL.
    `static org.w3c.dom.Document` | `getDocument(java.lang.String uri)` Returns a `Document` object based on the specified resource `uri`.
    `static org.w3c.dom.Document` | `getDocument(java.net.URL url)` Returns a `Document` object based on the specified resource `URL`.
    `static java.util.Properties` | `getProperties(java.lang.String uri)` Returns a `Properties` object based on the specified resource `uri`.
    `static java.util.Properties` | `getProperties(java.lang.String uri, boolean failSilent)` Returns a `Properties` object based on the specified resource `uri`.
    `static java.util.Properties` | `getProperties(java.net.URL url)` Returns a `Properties` object based on the specified resource `URL`.
    `static java.util.Properties` | `getProperties(java.net.URL url, boolean failSilent)` Returns a `Properties` object based on the specified resource `url`.
    `static java.net.URL` | `getResource(java.lang.String uri)` Performs resource lookups using the `ClassLoader` and classpath.
    `static boolean` | `isWindowsPlatform()` Returns `true` if the JVM is currently running on `Windows`; `false` otherwise.
    `static void` | `loadLibrary(java.lang.String library, java.lang.String classpathResource)` Attempts to load the specified native `library`, using `classpathResource` and the filesystem to implement several fallback mechanisms in the event the library cannot be loaded.

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

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

- - ### Field Detail

    - #### LIBRARY_EXTENSION

          public static final java.lang.String LIBRARY_EXTENSION

      Defines the file extension used by native shared libraries on the current system.

  - ### Method Detail

    - #### isWindowsPlatform

          public static boolean isWindowsPlatform()

      Returns `true` if the JVM is currently running on `Windows`; `false` otherwise.
      Returns:
        `true` if the JVM is currently running on `Windows`; `false` otherwise.

    - #### getResource

          public static java.net.URL getResource(java.lang.String uri)

      Performs resource lookups using the `ClassLoader` and classpath. This method attemps to consolidate several techniques used for resource lookup in different situations, providing a common API that works the same from standalone applications to applets to multiple-classloader container-managed applications. Returns `null` if specified resource cannot be found.
      Parameters:
        `uri` - the String describing the resource to be looked up
      Returns:
        a `URL` representing the resource that has been looked up.

    - #### createImage

          public static java.awt.Image createImage(java.lang.String url)

      Returns an `Image` object based on the specified resource URL. Does not perform any caching on the `Image` object, so a new object will be created with each call to this method.
      Parameters:
        `url` - the `String` describing the resource to be looked up
      Returns:
        an `Image` created from the specified resource URL
      Throws:
        `java.lang.NullPointerException` - if specified resource cannot be found.

    - #### createImage

          public static java.awt.Image createImage(java.net.URL imageLocation)

      Returns an `Image` object based on the specified resource URL. Does not perform any caching on the `Image` object, so a new object will be created with each call to this method.
      Parameters:
        `imageLocation` - the `URL` indicating where the image resource may be found.
      Returns:
        an `Image` created from the specified resource URL
      Throws:
        `java.lang.NullPointerException` - if specified resource cannot be found.

    - #### createIcon

          public static javax.swing.ImageIcon createIcon(java.lang.String url)

      Returns an `ImageIcon` object based on the specified resource URL. Uses the `ImageIcon` constructor internally instead of dispatching to `createImage(String url)`, so `Image` objects are cached via the `MediaTracker`.
      Parameters:
        `url` - the `String` describing the resource to be looked up
      Returns:
        an `ImageIcon` created from the specified resource URL
      Throws:
        `java.lang.NullPointerException` - if specified resource cannot be found.

    - #### createCursor

          public static java.awt.Cursor createCursor(java.net.URL imageURL,
                                     java.awt.Point hotPoint,
                                     java.lang.String name)

      Returns a `Cursor` object based on the specified resource URL. Throws a `NullPointerException` if specified resource cannot be found. Dispatches to `createImage(URL imageLocation)`, so `Image` objects are not cached via the`MediaTracker`.
      Parameters:
        `imageURL` - the `URL` indicating where the image resource may be found.
        `hotPoint` - the X and Y of the large cursor's hot spot. The hotSpot values must be less than the Dimension returned by getBestCursorSize().
        `name` - a localized description of the cursor, for Java Accessibility use.
      Returns:
        a `Cursor` created from the specified resource URL
      Throws:
        `java.lang.NullPointerException` - if specified resource cannot be found.
        `java.lang.IndexOutOfBoundsException` - if the hotSpot values are outside

    - #### createCursor

          public static java.awt.Cursor createCursor(java.lang.String url,
                                     java.awt.Point hotPoint,
                                     java.lang.String name)

      Returns a `Cursor` object based on the specified resource URL. Throws a `NullPointerException` if specified resource cannot be found. Dispatches to `createImage(String url)`, so `Image` objects are not cached via the`MediaTracker`.
      Parameters:
        `url` - the `String` describing the resource to be looked up
        `hotPoint` - the X and Y of the large cursor's hot spot. The hotSpot values must be less than the Dimension returned by getBestCursorSize().
        `name` - a localized description of the cursor, for Java Accessibility use.
      Returns:
        a `Cursor` created from the specified resource URL
      Throws:
        `java.lang.NullPointerException` - if specified resource cannot be found.
        `java.lang.IndexOutOfBoundsException` - if the hotSpot values are outside

    - #### loadLibrary

          public static void loadLibrary(java.lang.String library,
                         java.lang.String classpathResource)

      Attempts to load the specified native `library`, using `classpathResource` and the filesystem to implement several fallback mechanisms in the event the library cannot be loaded. This method should provide seamless installation and loading of native libraries from within the classpath so that native libraries may be packaged within the relavant library JAR, rather than requiring separate user installation of the native libraries into the system `$PATH`.

      If the specified `library` is `null`, then this method returns with no action taken.

      This method will first attempt to call `System.loadLibrary(library)`. If this call is successful, then the method will exit here. If an `UnsatisfiedLinkError` is encountered, then this method attempts to locate a FlexDock-specific filesystem resource for the native library, called the "FlexDock Library".

      The FlexDock Library will reside on the filesystem under the user's home directory with the path `${user.home}/flexdock/${library}${native.lib.extension}`. Thus, if this method is called with an argument of `"foo"` for the library, then under windows the FlexDock Library should be `C:\Documents and Settings\${user.home}\flexdock\foo.dll`. Under any type of Unix system, the FlexDock library should be `/home/${user.home}/flexdock/foo.so`.

      If the FlexDock Library exists on the filesystem, then this method will attempt to load it by calling `System.load(String filename)` with the FlexDock Library's absolute path. If this call is successful, then the method exits here.

      If the FlexDock Library cannot be loaded, then the specified `classpathResource` is checked. If `classpathResource` is `null`, then there is no more information available to attempt to resolve the requested library and this method throws the last `UnsatisfiedLinkError` encountered.

      If `classpathResource` is non-`null`, then an `InputStream` to the specified resource is resolved from the class loader. The contents of the `InputStream` are read into a `byte` array and written to disk as the FlexDock Library file. The FlexDock Library is then loaded with a call to `System.load(String filename)` with the FlexDock Library's absolute path. If the specified `classpathResource` cannot be resolved by the class loader, if any errors occur during this process of extracting and writing to disk, or if the resulting FlexDock Library file cannot be loaded as a native library, then this method throws an appropriate `UnsatisfiedLinkError` specific to the situation that prevented the native library from loading.

      Note that because this method may extract resources from the classpath and install to the filesystem as a FlexDock Library, subsequent calls to this method across JVM sessions will find the FlexDock Library on the filesystem and bypass the extraction process.

      Parameters:
        `library` - the native library to load
        `classpathResource` - the fallback location within the classpath from which to extract the desired native library in the event it is not already installed on the target system
      Throws:
        `java.lang.UnsatisfiedLinkError` - if the library cannot be loaded

    - #### getDocument

          public static org.w3c.dom.Document getDocument(java.lang.String uri)

      Returns a `Document` object based on the specified resource `uri`. This method resolves a `URL` from the specified `String` via `getResource(String uri)` and dispatches to `getDocument(URL url)`. If the specified `uri` is `null`, then this method returns `null`.
      Parameters:
        `uri` - the `String` describing the resource to be looked up
      Returns:
        a `Document` object based on the specified resource `uri`
      See Also:
        `getResource(String)`, `getDocument(URL)`

    - #### getDocument

          public static org.w3c.dom.Document getDocument(java.net.URL url)

      Returns a `Document` object based on the specified resource `URL`. This method will open an `InputStream` to the specified `URL` and construct a `Document` instance. If any `Exceptions` are encountered in the process, this method returns `null`. If the specified `URL` is `null`, then this method returns `null`.
      Parameters:
        `url` - the `URL` describing the resource to be looked up
      Returns:
        a `Document` object based on the specified resource `URL`

    - #### getProperties

          public static java.util.Properties getProperties(java.lang.String uri)

      Returns a `Properties` object based on the specified resource `uri`. This method resolves a `URL` from the specified `String` via `getResource(String uri)` and dispatches to `getProperties(URL url, boolean failSilent)` with an argument of `false` for `failSilent`. If the specified `uri` is `null`, then this method will print a stack trace for the ensuing `NullPointerException` and return `null`.
      Parameters:
        `uri` - the `String` describing the resource to be looked up
      Returns:
        a `Properties` object based on the specified resource `uri`.
      See Also:
        `getResource(String)`, `getProperties(URL, boolean)`

    - #### getProperties

          public static java.util.Properties getProperties(java.lang.String uri,
                                           boolean failSilent)

      Returns a `Properties` object based on the specified resource `uri`. This method resolves a `URL` from the specified `String` via `getResource(String uri)` and dispatches to `getProperties(URL url, boolean failSilent)`, passing the specified `failSilent` parameter. If the specified `uri` is `null`, this method will return `null`. If `failSilent` is `false`, then the ensuing `NullPointerException's` stacktrace will be printed to the `System.err` before returning.
      Parameters:
        `uri` - the `String` describing the resource to be looked up
        `failSilent` - `true` if no errors are to be reported to the `System.err` before returning; `false` otherwise.
      Returns:
        a `Properties` object based on the specified resource `uri`.
      See Also:
        `getResource(String)`, `getProperties(URL, boolean)`

    - #### getProperties

          public static java.util.Properties getProperties(java.net.URL url)

      Returns a `Properties` object based on the specified resource `URL`. This method dispatches to `getProperties(URL url, boolean failSilent)`, with an argument of `false` for `failSilent`. If the specified `uri` is `null`, this method will print the ensuing `NullPointerException` stack tracke to the `System.err` and return `null`.
      Parameters:
        `url` - the `URL` describing the resource to be looked up
      Returns:
        a `Properties` object based on the specified resource `url`.
      See Also:
        `getProperties(URL, boolean)`

    - #### getProperties

          public static java.util.Properties getProperties(java.net.URL url,
                                           boolean failSilent)

      Returns a `Properties` object based on the specified resource `url`. If the specified `uri` is `null`, this method will return `null`. If any errors are encountered during the properties-load process, this method will return `null`. If `failSilent` is `false`, then the any encoutered error stacktraces will be printed to the `System.err` before returning.
      Parameters:
        `url` - the `URL` describing the resource to be looked up
        `failSilent` - `true` if no errors are to be reported to the `System.err` before returning; `false` otherwise.
      Returns:
        a `Properties` object based on the specified resource `url`.

    - #### close

          public static void close(java.io.InputStream in)

      Calls `close()` on the specified `InputStream`. Any `Exceptions` encountered will be printed to the `System.err`. If `in` is `null`, then no `Exception` is thrown and no action is taken.
      Parameters:
        `in` - the `InputStream` to close
      See Also:
        `InputStream.close()`

    - #### close

          public static void close(java.io.OutputStream out)

      Calls `close()` on the specified `OutputStream`. Any `Exceptions` encountered will be printed to the `System.err`. If `out` is `null`, then no `Exception` is thrown and no action is taken.
      Parameters:
        `out` - the `OutputStream` to close
      See Also:
        `OutputStream.close()`

    - #### close

          public static void close(java.net.Socket socket)

      Calls `close()` on the specified `Socket`. Any `Exceptions` encountered will be printed to the `System.err`. If `socket` is `null`, then no `Exception` is thrown and no action is taken.
      Parameters:
        `socket` - the `Socket` to close
      See Also:
        `Socket.close()`