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

Modifier and Type	Method and 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(Locator locator) Returns the data string for the specified Locator.
static String	locatorToDataString(String locatorString) Extracts the data of the string representation of a Locator.
static String	locatorToString(Locator locator, String locatorData) Creates a string representation of a Locator object.
static InputStream	openStream(Locator locator) Obtains an input stream for the specified locator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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