Locator (Apache Ant API)
Date: 2015-06-29

org.apache.tools.ant.launch

## Class Locator

- java.lang.Object
- - org.apache.tools.ant.launch.Locator

-     public final class Locator
      extends java.lang.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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `ERROR_NOT_FILE_URI` Error string used when an invalid uri is seen
    `static java.lang.String` | `URI_ENCODING` encoding used to represent URIs

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `decodeUri(java.lang.String uri)` Decodes an Uri with % characters.
    `static java.lang.String` | `encodeURI(java.lang.String path)` Encodes an Uri with % characters.
    `static java.net.URL` | `fileToURL(java.io.File file)` Deprecated. since 1.9, use `FileUtils#getFileURL(File)`
    `static java.lang.String` | `fromJarURI(java.lang.String uri)` Crack a JAR URI.
    `static java.lang.String` | `fromURI(java.lang.String uri)` Constructs a file path from a `file:` URI.
    `static java.io.File` | `getClassSource(java.lang.Class<?> c)` Find the directory or jar file the class has been loaded from.
    `static java.net.URL[]` | `getLocationURLs(java.io.File location)` Get an array of URLs representing all of the jar files in the given location.
    `static java.net.URL[]` | `getLocationURLs(java.io.File location, java.lang.String[] extensions)` Get an array of URLs representing all of the files of a given set of extensions in the given location.
    `static java.io.File` | `getResourceSource(java.lang.ClassLoader c, java.lang.String resource)` Find the directory or jar a given resource has been loaded from.
    `static java.io.File` | `getToolsJar()` Get the File necessary to load the Sun compiler tools.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### URI_ENCODING

          public static final java.lang.String URI_ENCODING

      encoding used to represent URIs
      See Also:
        Constant Field Values

    - #### ERROR_NOT_FILE_URI

          public static final java.lang.String ERROR_NOT_FILE_URI

      Error string used when an invalid uri is seen
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### getClassSource

          public static java.io.File getClassSource(java.lang.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

    - #### getResourceSource

          public static java.io.File getResourceSource(java.lang.ClassLoader c,
                                       java.lang.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

    - #### fromURI

          public static java.lang.String fromURI(java.lang.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:
        `java.lang.IllegalArgumentException` - if the URI is malformed or not a legal file: URL
      Since:
        Ant 1.6

    - #### fromJarURI

          public static java.lang.String fromJarURI(java.lang.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

    - #### decodeUri

          public static java.lang.String decodeUri(java.lang.String uri)
                                            throws java.io.UnsupportedEncodingException

      Decodes an Uri with % characters. The URI is escaped
      Parameters:
        `uri` - String with the uri possibly containing % characters.
      Returns:
        The decoded Uri
      Throws:
        `java.io.UnsupportedEncodingException` - if UTF-8 is not available
      Since:
        Ant 1.7

    - #### encodeURI

          public static java.lang.String encodeURI(java.lang.String path)
                                            throws java.io.UnsupportedEncodingException

      Encodes an Uri with % characters. The URI is escaped
      Parameters:
        `path` - String to encode.
      Returns:
        The encoded string, according to URI norms
      Throws:
        `java.io.UnsupportedEncodingException` - if UTF-8 is not available
      Since:
        Ant 1.7

    - #### fileToURL

          @Deprecated
          public static java.net.URL fileToURL(java.io.File file)
                                        throws java.net.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) 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:
        `java.net.MalformedURLException` - on error

    - #### getToolsJar

          public static java.io.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.

    - #### getLocationURLs

          public static java.net.URL[] getLocationURLs(java.io.File location)
                                                throws java.net.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` - the location to scan for Jars.
      Returns:
        an array of URLs for all jars in the given location.
      Throws:
        `java.net.MalformedURLException` - if the URLs for the jars cannot be formed.

    - #### getLocationURLs

          public static java.net.URL[] getLocationURLs(java.io.File location,
                                       java.lang.String[] extensions)
                                                throws java.net.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` - 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:
        `java.net.MalformedURLException` - if the URLs for the files cannot be formed.