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