Top Description Fields Constructors Methods
org.apache.tools.ant.launch

public final Class Locator

extends Object
Class Inheritance
Imports
java.io.ByteArrayOutputStream, .File, .UnsupportedEncodingException, java.net.MalformedURLException, .URL, java.nio.charset.StandardCharsets, java.text.CharacterIterator, .StringCharacterIterator, java.util.Locale, java.util.stream.Stream
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

Modifier and TypeField and Description
private static final int
ASCII_SIZE

private static final int
BYTE_SIZE

private static final int
DEL

public static final String
ERROR_NOT_FILE_URI

Error string used when an invalid uri is seen

private static char[]
gAfterEscaping1

private static char[]
gAfterEscaping2

private static char[]
gHexChs

private static boolean[]
gNeedEscaping

private static final int
NIBBLE

private static final int
NIBBLE_MASK

private static final int
SPACE

private static final int
WORD

Constructor Summary

AccessConstructor and Description
private
Locator()

Not instantiable

Method Summary

Modifier and TypeMethod and Description
public static String

Returns:

The decoded Uri
decodeUri(String
String with the uri possibly containing % characters.
uri)

Decodes an Uri with % characters.

public static String

Returns:

The encoded string, according to URI norms
encodeURI(String
String to encode.
path)

Encodes an Uri with % characters.

public static URL

Returns:

URL the converted File
fileToURL(File
the file to convert
file)

Deprecated since 1.9, use FileUtils.getFileURL(File)
Convert a File to a URL.
public static String

Returns:

the decoded URI
fromJarURI(String
uri to expand; contains jar: somewhere in it
uri)

Crack a JAR URI.

public static String

Returns:

the local file system path for the file.
fromURI(String
the URI designating a file in the local filesystem.
uri)

Constructs a file path from a file: URI.

public static File

Returns:

the file or jar with the class or null if we cannot determine the location.
getClassSource(Class<?>
the class whose location is required.
c)

Find the directory or jar file the class has been loaded from.

public static URL[]

Returns:

an array of URLs for all jars in the given location.
getLocationURLs(File
the location to scan for Jars.
location)

Get an array of URLs representing all of the jar files in the given location.

public static URL[]

Returns:

an array of URLs of matching files.
getLocationURLs(File
the location to scan for files.
location, final String...
an array of extension that are to match in the directory search.
extensions)

Get an array of URLs representing all of the files of a given set of extensions in the given location.

public static File

Returns:

the file with the resource source or null if we cannot determine the location.
getResourceSource(ClassLoader
the classloader to be consulted for the source.
c, String
the resource whose location is required.
resource)

Find the directory or jar a given resource has been loaded from.

public static File

Returns:

the tools jar as a File if required, null otherwise.
getToolsJar()

Get the File necessary to load the Sun compiler tools.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

ASCII_SIZEback to summary
private static final int ASCII_SIZE
BYTE_SIZEback to summary
private static final int BYTE_SIZE
DELback to summary
private static final int DEL
ERROR_NOT_FILE_URIback to summary
public static final String ERROR_NOT_FILE_URI

Error string used when an invalid uri is seen

gAfterEscaping1back to summary
private static char[] gAfterEscaping1
gAfterEscaping2back to summary
private static char[] gAfterEscaping2
gHexChsback to summary
private static char[] gHexChs
gNeedEscapingback to summary
private static boolean[] gNeedEscaping
NIBBLEback to summary
private static final int NIBBLE
NIBBLE_MASKback to summary
private static final int NIBBLE_MASK
SPACEback to summary
private static final int SPACE
WORDback to summary
private static final int WORD

Constructor Detail

Locatorback to summary
private Locator()

Not instantiable

Method Detail

decodeUriback to summary
public static String decodeUri(String uri) throws UnsupportedEncodingException

Decodes an Uri with % characters. The URI is escaped

Parameters
uri:String

String with the uri possibly containing % characters.

Returns:String

The decoded Uri

Exceptions
UnsupportedEncodingException:
if UTF-8 is not available
Since
Ant 1.7
encodeURIback to summary
public static String encodeURI(String path)

Encodes an Uri with % characters. The URI is escaped

Parameters
path:String

String to encode.

Returns:String

The encoded string, according to URI norms

Since
Ant 1.7
fileToURLback to summary
public static URL fileToURL(File file) throws MalformedURLException

Deprecated

since 1.9, use FileUtils.getFileURL(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) File.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:File

the file to convert

Returns:URL

URL the converted File

Annotations
@Deprecated
Exceptions
MalformedURLException:
on error
fromJarURIback to summary
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:String

uri to expand; contains jar: somewhere in it

Returns:String

the decoded URI

Since
Ant1.7.1
fromURIback to summary
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:String

the URI designating a file in the local filesystem.

Returns:String

the local file system path for the file.

Exceptions
IllegalArgumentException:
if the URI is malformed or not a legal file: URL
Since
Ant 1.6
getClassSourceback to summary
public static File getClassSource(Class<?> c)

Find the directory or jar file the class has been loaded from.

Parameters
c:Class<?>

the class whose location is required.

Returns:File

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

Since
Ant 1.6
getLocationURLsback to summary
public static URL[] getLocationURLs(File location) throws MalformedURLException

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:File

the location to scan for Jars.

Returns:URL[]

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

Exceptions
MalformedURLException:
if the URLs for the jars cannot be formed.
getLocationURLsback to summary
public static URL[] getLocationURLs(File location, final String... extensions) throws MalformedURLException

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:File

the location to scan for files.

extensions:String[]

an array of extension that are to match in the directory search.

Returns:URL[]

an array of URLs of matching files.

Exceptions
MalformedURLException:
if the URLs for the files cannot be formed.
getResourceSourceback to summary
public static File getResourceSource(ClassLoader c, String resource)

Find the directory or jar a given resource has been loaded from.

Parameters
c:ClassLoader

the classloader to be consulted for the source.

resource:String

the resource whose location is required.

Returns:File

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

Since
Ant 1.6
getToolsJarback to summary
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:File

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