Eclipse Platform
Release 3.3

org.eclipse.core.runtime
Class FileLocator

java.lang.Object
  extended byorg.eclipse.core.runtime.FileLocator

public final class FileLocator
extends Object

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

The class is not intended to be subclassed or instantiated by clients.

Since:
org.eclipse.equinox.common 3.2

Method Summary
static URL find(Bundle bundle, IPath path, Map override)
          Returns a URL for the given path in the given bundle.
static URL[] findEntries(Bundle bundle, IPath path)
          Same as findEntries(Bundle, IPath) except multiple entries can be returned if more than one entry matches the path in the host any of its fragments.
static URL[] findEntries(Bundle bundle, IPath path, Map override)
          Same as findEntries(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 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 override)
Returns a URL for the given path in the given bundle. Returns null if the URL could not be computed or created.

find looks for this path in 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 arguments may also be used

     $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 place 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.

findEntries

public static URL[] findEntries(Bundle bundle,
                                IPath path,
                                Map override)
Same as findEntries(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

findEntries

public static URL[] findEntries(Bundle bundle,
                                IPath path)
Same as findEntries(Bundle, IPath) except multiple entries can be returned if more than one entry matches the path in the host any of its fragments.

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

Eclipse Platform
Release 3.3

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2007. All rights reserved.