Package org.eclipse.core.runtime

## Class FileLocator

- java.lang.Object
- - org.eclipse.core.runtime.FileLocator

    public final class FileLocator
    extends Object

This class contains a collection of helper methods for finding files in bundles. This class can only be used if the OSGi plugin is available.

Since:
  org.eclipse.equinox.common 3.2
Restriction:
  This class is not intended to be instantiated by clients.

### Method Summary

All Methods Static Methods Concrete Methods
`static URL` `find​(URL url)` Returns the URL of a resource inside a bundle corresponding to the given URL.
`static URL` `find​(Bundle bundle, IPath path)` Returns a URL for the given path in the given bundle.
`static URL` `find​(Bundle bundle, IPath path, Map<String,​String> override)` Returns a URL for the given path in the given bundle.
`static URL[]` `findEntries​(Bundle bundle, IPath path)` This is a convenience method, fully equivalent to `findEntries(Bundle, IPath, Map)`, with a value of `null` for the map argument.
`static URL[]` `findEntries​(Bundle bundle, IPath path, Map<String,​String> override)` This method is the same as `find(Bundle, IPath, Map)` except multiple entries can be returned if more than one entry matches the path in the host and any of its fragments.
`static File` `getBundleFile​(Bundle bundle)` Returns a file for the contents of the specified bundle.
`static Optional<File>` `getBundleFileLocation​(Bundle bundle)` Returns an `Optional` `File`, that (if present) describes the bundle's root location on the file system.
`static InputStream` `openStream​(Bundle bundle, IPath file, boolean substituteArgs)` Returns an input stream for the specified file.
`static URL` `resolve​(URL url)` Converts a URL that uses a client-defined protocol into a URL that uses a protocol which is native to the Java class library (file, jar, http, etc).
`static URL` `toFileURL​(URL url)` Converts a URL that uses a user-defined protocol into a URL that uses the file protocol.

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

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

### Method Detail

#### find

    public static URL find​(Bundle bundle,
                           IPath path,
                           Map<String,​String> override)

Returns a URL for the given path in the given bundle. Returns `null` if the URL could not be computed or created.

This method looks for the path in the given bundle and any attached fragments. `null` is returned if no such entry is found. Note that there is no specific order to the fragments.

The following variables may also be used as entries in the provided path:

- $nl$ - for language specific information
- $os$ - for operating system specific information
- $ws$ - for windowing system specific information

A path of "$nl$/about.properties" in an environment with a default locale of en_CA will return a URL corresponding to the first location about.properties is found according to the following order:

         plugin root/nl/en/CA/about.properties
         fragment1 root/nl/en/CA/about.properties
         fragment2 root/nl/en/CA/about.properties
         ...
         plugin root/nl/en/about.properties
         fragment1 root/nl/en/about.properties
         fragment2 root/nl/en/about.properties
         ...
         plugin root/about.properties
         fragment1 root/about.properties
         fragment2 root/about.properties
         ...

The current environment variable values can be overridden using the override map argument or `null` can be specified if this is not desired.

Parameters:
  `bundle` - the bundle in which to search
  `path` - file path relative to plug-in installation location
  `override` - map of override substitution arguments to be used for any $arg$ path elements. The map keys correspond to the substitution arguments (eg. "$nl$" or "$os$"). The resulting values must be of type java.lang.String. If the map is `null`, or does not contain the required substitution argument, the default is used.
Returns:
  a URL for the given path or `null`. The actual form of the returned URL is not specified.

#### find

    public static URL find​(Bundle bundle,
                           IPath path)

Returns a URL for the given path in the given bundle. Returns `null` if the URL could not be computed or created.

This method looks for the path in the given bundle and any attached fragments. `null` is returned if no such entry is found. Note that there is no specific order to the fragments.

The following variables may also be used as entries in the provided path:

- $nl$ - for language specific information
- $os$ - for operating system specific information
- $ws$ - for windowing system specific information

A path of "$nl$/about.properties" in an environment with a default locale of en_CA will return a URL corresponding to the first location about.properties is found according to the following order:

         plugin root/nl/en/CA/about.properties
         fragment1 root/nl/en/CA/about.properties
         fragment2 root/nl/en/CA/about.properties
         ...
         plugin root/nl/en/about.properties
         fragment1 root/nl/en/about.properties
         fragment2 root/nl/en/about.properties
         ...
         plugin root/about.properties
         fragment1 root/about.properties
         fragment2 root/about.properties
         ...

Parameters:
  `bundle` - the bundle in which to search
  `path` - file path relative to plug-in installation location
Returns:
  a URL for the given path or `null`. The actual form of the returned URL is not specified.
Since:
  3.10
See Also:
  `for the option to override the current environment variables`

#### findEntries

    public static URL[] findEntries​(Bundle bundle,
                                    IPath path,
                                    Map<String,​String> override)

This method is the same as `find(Bundle, IPath, Map)` except multiple entries can be returned if more than one entry matches the path in the host and any of its fragments.

Parameters:
  `bundle` - the bundle in which to search
  `path` - file path relative to plug-in installation location
  `override` - map of override substitution arguments to be used for any $arg$ path elements. The map keys correspond to the substitution arguments (eg. "$nl$" or "$os$"). The resulting values must be of type java.lang.String. If the map is `null`, or does not contain the required substitution argument, the default is used.
Returns:
  an array of entries which match the given path. An empty array is returned if no matches are found.
Since:
  org.eclipse.equinox.common 3.3

#### find

    public static URL find​(URL url)

Returns the URL of a resource inside a bundle corresponding to the given URL. Returns `null` if the URL could not be computed or created.

This method looks for a bundle resource described by the given input URL, and returns the URL of the first resource found in the bundle or any attached fragments. `null` is returned if no such entry is found. Note that there is no specific order to the fragments.

The following variables may also be used as segments in the path of the provided URL:

- $nl$ - for language specific information
- $os$ - for operating system specific information
- $ws$ - for windowing system specific information

For example, a URL of "platform:/plugin/org.eclipse.core.runtime/$nl$/about.properties" in an environment with a default locale of en_CA will return a URL corresponding to the first location about.properties is found according to the following order:

         plugin root/nl/en/CA/about.properties
         fragment1 root/nl/en/CA/about.properties
         fragment2 root/nl/en/CA/about.properties
         ...
         plugin root/nl/en/about.properties
         fragment1 root/nl/en/about.properties
         fragment2 root/nl/en/about.properties
         ...
         plugin root/about.properties
         fragment1 root/about.properties
         fragment2 root/about.properties
         ...

Parameters:
  `url` - The location of a bundle entry that potentially includes the above environment variables
Returns:
  The URL of the bundle entry matching the input URL, or `null` if no matching entry could be found. The actual form of the returned URL is not specified.
Since:
  org.eclipse.equinox.common 3.5

#### findEntries

    public static URL[] findEntries​(Bundle bundle,
                                    IPath path)

This is a convenience method, fully equivalent to `findEntries(Bundle, IPath, Map)`, with a value of `null` for the map argument.

Parameters:
  `bundle` - the bundle in which to search
  `path` - file path relative to plug-in installation location
Returns:
  an array of entries which match the given path. An empty array is returned if no matches are found.
Since:
  org.eclipse.equinox.common 3.3

#### openStream

    public static InputStream openStream​(Bundle bundle,
                                         IPath file,
                                         boolean substituteArgs)
                                  throws IOException

Returns an input stream for the specified file. The file path must be specified relative to this plug-in's installation location. Optionally, the path specified may contain $arg$ path elements that can be used as substitution arguments. If this option is used then the $arg$ path elements are processed in the same way as `find(Bundle, IPath, Map)`.

The caller must close the returned stream when done.

Parameters:
  `bundle` - the bundle in which to search
  `file` - path relative to plug-in installation location
  `substituteArgs` - `true` to process substitution arguments, and `false` for the file exactly as specified without processing any substitution arguments.
Returns:
  an input stream
Throws:
  `IOException` - if the given path cannot be found in this plug-in

#### toFileURL

    public static URL toFileURL​(URL url)
                         throws IOException

Converts a URL that uses a user-defined protocol into a URL that uses the file protocol. The contents of the URL may be extracted into a cache on the file-system in order to get a file URL.

If the protocol for the given URL is not recognized by this converter, the original URL is returned as-is.

Parameters:
  `url` - the original URL
Returns:
  the converted file URL or the original URL passed in if it is not recognized by this converter
Throws:
  `IOException` - if an error occurs during the conversion

#### resolve

    public static URL resolve​(URL url)
                       throws IOException

Converts a URL that uses a client-defined protocol into a URL that uses a protocol which is native to the Java class library (file, jar, http, etc).

Note however that users of this API should not assume too much about the results of this method. While it may consistently return a file: URL in certain installation configurations, others may result in jar: or http: URLs.

If the protocol is not recognized by this converter, then the original URL is returned as-is.

Parameters:
  `url` - the original URL
Returns:
  the resolved URL or the original if the protocol is unknown to this converter
Throws:
  `IOException` - if unable to resolve URL
  `IOException` - if an error occurs during the resolution

#### getBundleFile

    public static File getBundleFile​(Bundle bundle)
                              throws IOException

Returns a file for the contents of the specified bundle. Depending on how the bundle is installed the returned file may be a directory or a jar file containing the bundle content.

Parameters:
  `bundle` - the bundle
Returns:
  a file with the contents of the bundle
Throws:
  `IOException` - if an error occurs during the resolution
Since:
  org.eclipse.equinox.common 3.4

#### getBundleFileLocation

    public static Optional<File> getBundleFileLocation​(Bundle bundle)

Returns an `Optional` `File`, that (if present) describes the bundle's root location on the file system.

Depending on how the bundle is installed the returned file may be a directory or a jar file containing the bundle content. In case the location cannot be determined the returned `Optional` is empty, which is for example usually the case for `CONNECT` bundles.

Parameters:
  `bundle` - the bundle
Returns:
  the optional file to the location of the bundle's root
Since:
  3.16