Package net.sf.jguiraffe.locators
Class LocatorUtils
- java.lang.Object
-
- net.sf.jguiraffe.locators.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 Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static URL
fileURL(File file)
Returns the URL for the given file.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.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.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.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.static URL
locateResource(String resource)
Tries to locate a resource in the class path.static URL
locateResource(String resource, ClassLoader cl)
Tries to locate a resource in the class path using the specified class loader.static URL
locateURL(String url)
Locates a file using a string, which can be either a full URL or a file name.static String
locatorToDataString(String locatorString)
Extracts the data of the string representation of aLocator
.static String
locatorToDataString(Locator locator)
Returns the data string for the specifiedLocator
.static String
locatorToString(Locator locator, String locatorData)
Creates a string representation of aLocator
object.static InputStream
openStream(Locator locator)
Obtains an input stream for the specified locator.
-
-
-
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 theClassLoader
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 resourcecl
- 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 methodslocateURL()
andlocateResource()
. 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 aClassLoader
is specified, it is used during class path lookup as described atlocateResource(String, ClassLoader)
.- Parameters:
url
- specifies a URLname
- specifies a resource namecl
- 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 URLname
- 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 tolocate()
, but a failing lookup causes aLocatorException
.- Parameters:
url
- specifies a URLname
- specifies a resource namecl
- 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 URLname
- 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):getInputStream()
getFile()
getURL()
- Parameters:
locator
- the locator- Returns:
- the input stream for this locator
- Throws:
IOException
- if an IO error occursLocatorException
- 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 aLocator
object. This string contains the fully qualified class name of theLocator
(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 concreteLocator
implementations in this package use this method in the implementation of theirtoString()
method.- Parameters:
locator
- theLocator
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 aLocator
. Strings created by thelocatorToString()
method contain some information specific to theLocator
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 thelocatorToString()
method.- Parameters:
locatorString
- the string for the locator (as generated bylocatorToString()
)- 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 specifiedLocator
. This is a short cut oflocatorToDataString(locator.toString()
. ThetoString()
implementation of the locator must produce strings conforming to the format oflocatorToString()
.- 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
-
-