Class LocatorUtils


  • public final class LocatorUtils
    extends Object

    A helper class for locating resources.

    This class provides functionality for locating resources like configuration files, which can be specified in multiple ways:

    • as absolute URLs.
    • as absolute or relative files.
    • as resources in the application's class path.
    • through Locator objects.

    Version:
    $Id: LocatorUtils.java 211 2012-07-10 19:49:13Z oheger $
    Author:
    Oliver Heger
    • Method Detail

      • fileURL

        public static URL fileURL​(File file)
        Returns the URL for the given file. This is a convenience method that takes care for transforming the file to an URI and the URI eventually to a URL. If a null parameter is passed in, result will also be null.
        Parameters:
        file - the file to be transformed
        Returns:
        the corresponding URL
        Throws:
        LocatorException - if the transformation fails
      • locateResource

        public static URL locateResource​(String resource,
                                         ClassLoader cl)
        Tries to locate a resource in the class path using the specified class loader. If the ClassLoader parameter is not null, this class loader is tried first. If this fails, this method tries the context, the default, and the system class loader (in this order) to find the resource in the class path. Search stops as soon as the resource is found.
        Parameters:
        resource - the name of the resource
        cl - the class loader to use for looking up the resource (can be null)
        Returns:
        the URL to the resource or null if it cannot be resolved
        Since:
        1.2
      • locateResource

        public static URL locateResource​(String resource)
        Tries to locate a resource in the class path. No specific class loader is provided, so this method tries the context, the default, and the system class loader (in this order) to find the resource in the class path.
        Parameters:
        resource - the name of the resource
        Returns:
        the URL to the resource or null if it cannot be resolved
        See Also:
        locateResource(String, ClassLoader)
      • locateURL

        public static URL locateURL​(String url)
        Locates a file using a string, which can be either a full URL or a file name. Some variants are tried until a valid resource can be found.
        Parameters:
        url - the URL of the file to be located
        Returns:
        the full URL to this file or null if it cannot be found
      • locate

        public static URL locate​(String url,
                                 String name,
                                 ClassLoader cl)
        Locates a resource either from a URL or a class path resource, returning null if the resource cannot be resolved. This method combines the methods locateURL() and locateResource(). If a URL is defined, it is tried to be resolved. If this fails and a resource name is defined, this name is tried to be resolved. If both parameters are defined and valid, the URL takes precedence. If both attempts fail, the result is null. If a ClassLoader is specified, it is used during class path lookup as described at locateResource(String, ClassLoader).
        Parameters:
        url - specifies a URL
        name - specifies a resource name
        cl - an optional class loader for the class path lookup
        Returns:
        the resolved URL or null if the resource cannot be resolved
        Since:
        1.2
      • locate

        public static URL locate​(String url,
                                 String name)
        Locates a resource either from a URL or a class path resource (using a default class loader), returning null if the resource cannot be resolved.
        Parameters:
        url - specifies a URL
        name - specifies a resource name
        Returns:
        the resolved URL or null
        See Also:
        locate(String, String, ClassLoader)
      • locateEx

        public static URL locateEx​(String url,
                                   String name,
                                   ClassLoader cl)
        Locates a resource either from a URL or a class path resource, throwing an exception if the resource cannot be resolved. This is analogous to locate(), but a failing lookup causes a LocatorException.
        Parameters:
        url - specifies a URL
        name - specifies a resource name
        cl - an optional class loader for the class path lookup
        Returns:
        the resolved URL
        Throws:
        LocatorException - if the resource cannot be resolved
        Since:
        1.2
      • locateEx

        public static URL locateEx​(String url,
                                   String name)
        Locates a resource either from a URL or a class path resource (using a default class loader), throwing an exception if the resource cannot be resolved.
        Parameters:
        url - specifies a URL
        name - specifies a resource name
        Returns:
        the resolved URL
        Throws:
        LocatorException - if the resource cannot be resolved
        See Also:
        locateEx(String, String, ClassLoader)
      • openStream

        public static InputStream openStream​(Locator locator)
                                      throws IOException
        Obtains an input stream for the specified locator. This method will query the different methods of the locator until a result is found. From this result a stream will be created. The locator's methods are invoked in the following order (until a non null result is obtained):
        1. getInputStream()
        2. getFile()
        3. getURL()
        Parameters:
        locator - the locator
        Returns:
        the input stream for this locator
        Throws:
        IOException - if an IO error occurs
        LocatorException - if the locator throws an exception or no valid values are returned
      • locatorToString

        public static String locatorToString​(Locator locator,
                                             String locatorData)
        Creates a string representation of a Locator object. This string contains the fully qualified class name of the Locator (class), its identity hash code ( hash), and the data passed to this method (data, which is locator specific). It has the following form: class@hash[ data ]. The concrete Locator implementations in this package use this method in the implementation of their toString() method.
        Parameters:
        locator - the Locator to be transformed to a string (must not be null)
        locatorData - the data of this locator
        Returns:
        a string representation for this Locator
        Throws:
        IllegalArgumentException - if the locator is null
      • locatorToDataString

        public static String locatorToDataString​(String locatorString)
        Extracts the data of the string representation of a Locator. Strings created by the locatorToString() method contain some information specific to the Locator object involved, especially its identity hash code. This complicates things, for instance in unit tests, when locators that are equal should produce equal string representations. In such cases this method can be used. It produces a string containing only the class name (not fully qualified) and the data of the locator. The relevant parts are extracted from the given string, which must conform to the format produced by the locatorToString() method.
        Parameters:
        locatorString - the string for the locator (as generated by locatorToString())
        Returns:
        the data string extracted
        Throws:
        IllegalArgumentException - if the passed in string is null or does not conform to the expected format
        See Also:
        locatorToString(Locator, String)
      • locatorToDataString

        public static String locatorToDataString​(Locator locator)
        Returns the data string for the specified Locator. This is a short cut of locatorToDataString(locator.toString(). The toString() implementation of the locator must produce strings conforming to the format of locatorToString().
        Parameters:
        locator - the locator to be transformed into a string
        Returns:
        the data string for this locator
        Throws:
        IllegalArgumentException - if the locator is null or has an invalid string representation