public final class FileLocator extends Object
Modifier and Type | Method and Description |
---|---|
static URL |
find(Bundle bundle,
IPath path,
Map<String,String> override)
Returns a URL for the given path in the given bundle.
|
static URL |
find(URL url)
Returns the URL of a resource inside a bundle corresponding to the given URL.
|
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 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.
|
public static URL find(Bundle bundle, IPath path, Map<String,String> override)
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:
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.
bundle
- the bundle in which to searchpath
- file path relative to plug-in installation locationoverride
- 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.null
. The actual form
of the returned URL is not specified.public static URL[] findEntries(Bundle bundle, IPath path, Map<String,String> override)
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.bundle
- the bundle in which to searchpath
- file path relative to plug-in installation locationoverride
- 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.public static URL find(URL url)
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:
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 ...
url
- The location of a bundle entry that potentially includes the above
environment variablesnull
if no matching entry could be found. The actual form of the returned URL is not specified.public static URL[] findEntries(Bundle bundle, IPath path)
findEntries(Bundle, IPath, Map)
,
with a value of null
for the map argument.bundle
- the bundle in which to searchpath
- file path relative to plug-in installation locationpublic static InputStream openStream(Bundle bundle, IPath file, boolean substituteArgs) throws IOException
find(Bundle, IPath, Map)
.
The caller must close the returned stream when done.
bundle
- the bundle in which to searchfile
- path relative to plug-in installation locationsubstituteArgs
- true
to process substitution arguments,
and false
for the file exactly as specified without processing any
substitution arguments.IOException
- if the given path cannot be found in this plug-inpublic static URL toFileURL(URL url) throws IOException
If the protocol for the given URL is not recognized by this converter, the original URL is returned as-is.
url
- the original URLIOException
- if an error occurs during the conversionpublic static URL resolve(URL url) throws IOException
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.
url
- the original URLIOException
- if unable to resolve URLIOException
- if an error occurs during the resolutionpublic static File getBundleFile(Bundle bundle) throws IOException
bundle
- the bundleIOException
- if an error occurs during the resolution
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.