org.apache.tools.ant.launch

Class Locator

public final class Locator extends Object

The Locator is a utility class which is used to find certain items in the environment. It is used at boot time in the launcher, and cannot make use of any of Ant's other classes. This is a surprisingly brittle piece of code, and has had lots of bugs filed against it. running ant off a network share can cause Ant to fail use File.toURI().toURL().toExternalForm() Locator implementation not encoding URI strings properly: spaces in paths It also breaks Eclipse 3.3 Betas Exception if installation path has spaces Be very careful when making changes to this class, as a break will upset a lot of people.

Since: Ant 1.6

Field Summary
static StringERROR_NOT_FILE_URI
Error string used when an invalid uri is seen
static StringURI_ENCODING
encoding used to represent URIs
Method Summary
static StringdecodeUri(String uri)
Decodes an Uri with % characters.
static StringencodeURI(String path)
Encodes an Uri with % characters.
static URLfileToURL(File file)
Convert a File to a URL.
static StringfromJarURI(String uri)
Crack a JAR URI.
static StringfromURI(String uri)
Constructs a file path from a file: URI.
static FilegetClassSource(Class c)
Find the directory or jar file the class has been loaded from.
static URL[]getLocationURLs(File location)
Get an array of URLs representing all of the jar files in the given location.
static URL[]getLocationURLs(File location, String[] extensions)
Get an array of URLs representing all of the files of a given set of extensions in the given location.
static FilegetResourceSource(ClassLoader c, String resource)
Find the directory or jar a given resource has been loaded from.
static FilegetToolsJar()
Get the File necessary to load the Sun compiler tools.

Field Detail

ERROR_NOT_FILE_URI

public static final String ERROR_NOT_FILE_URI
Error string used when an invalid uri is seen

URI_ENCODING

public static final String URI_ENCODING
encoding used to represent URIs

Method Detail

decodeUri

public static String decodeUri(String uri)
Decodes an Uri with % characters. The URI is escaped

Parameters: uri String with the uri possibly containing % characters.

Returns: The decoded Uri

Throws: UnsupportedEncodingException if UTF-8 is not available

Since: Ant 1.7

encodeURI

public static String encodeURI(String path)
Encodes an Uri with % characters. The URI is escaped

Parameters: path String to encode.

Returns: The encoded string, according to URI norms

Throws: UnsupportedEncodingException if UTF-8 is not available

Since: Ant 1.7

fileToURL

public static URL fileToURL(File file)
Convert a File to a URL. File.toURL() does not encode characters like #. File.toURI() has been introduced in java 1.4, so Ant cannot use it (except by reflection) FileUtils.toURI() cannot be used by Locator.java Implemented this way. File.toURL() adds file: and changes '\' to '/' for dos OSes encodeURI converts characters like ' ' and '#' to %DD

Parameters: file the file to convert

Returns: URL the converted File

Throws: MalformedURLException on error

fromJarURI

public static String fromJarURI(String uri)
Crack a JAR URI. This method is public for testing; we may delete it without any warning -it is not part of Ant's stable API.

Parameters: uri uri to expand; contains jar: somewhere in it

Returns: the decoded URI

Since: Ant1.7.1

fromURI

public static String fromURI(String uri)
Constructs a file path from a file: URI.

Will be an absolute path if the given URI is absolute.

Prior to Java 1.4, swallows '%' that are not followed by two characters.

See dt-sysid which makes some mention of how characters not supported by URI Reference syntax should be escaped.

Parameters: uri the URI designating a file in the local filesystem.

Returns: the local file system path for the file.

Throws: IllegalArgumentException if the URI is malformed or not a legal file: URL

Since: Ant 1.6

getClassSource

public static File getClassSource(Class c)
Find the directory or jar file the class has been loaded from.

Parameters: c the class whose location is required.

Returns: the file or jar with the class or null if we cannot determine the location.

Since: Ant 1.6

getLocationURLs

public static URL[] getLocationURLs(File location)
Get an array of URLs representing all of the jar files in the given location. If the location is a file, it is returned as the only element of the array. If the location is a directory, it is scanned for jar files.

Parameters: location the location to scan for Jars.

Returns: an array of URLs for all jars in the given location.

Throws: MalformedURLException if the URLs for the jars cannot be formed.

getLocationURLs

public static URL[] getLocationURLs(File location, String[] extensions)
Get an array of URLs representing all of the files of a given set of extensions in the given location. If the location is a file, it is returned as the only element of the array. If the location is a directory, it is scanned for matching files.

Parameters: location the location to scan for files. extensions an array of extension that are to match in the directory search.

Returns: an array of URLs of matching files.

Throws: MalformedURLException if the URLs for the files cannot be formed.

getResourceSource

public static File getResourceSource(ClassLoader c, String resource)
Find the directory or jar a given resource has been loaded from.

Parameters: c the classloader to be consulted for the source. resource the resource whose location is required.

Returns: the file with the resource source or null if we cannot determine the location.

Since: Ant 1.6

getToolsJar

public static File getToolsJar()
Get the File necessary to load the Sun compiler tools. If the classes are available to this class, then no additional URL is required and null is returned. This may be because the classes are explicitly in the class path or provided by the JVM directly.

Returns: the tools jar as a File if required, null otherwise.