org.flexdock.util
Class ResourceManager

java.lang.Object
  extended by 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
static java.lang.String LIBRARY_EXTENSION
          Defines the file extension used by native shared libraries on the current system.
 
Method Summary
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 theMediaTracker.

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 theMediaTracker.

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()