Package org.flexdock.util

Class 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 Description
      static java.lang.String LIBRARY_EXTENSION
      Defines the file extension used by native shared libraries on the current system.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method 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()