org.eclipse.core.runtime
Class BundleFinder

java.lang.Object
  org.eclipse.core.runtime.BundleFinder

public final class BundleFinder

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 1.0 XXX bundle finder renamed and it aggregates URLCOnverter. This is not a service! just statics.

Constructor Summary

BundleFinder()

Method Summary

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 override) Returns a URL for the given path in the given bundle.
static InputStream	openStream(Bundle bundle, IPath file) Returns an input stream for the specified file.
static InputStream	openStream(Bundle bundle, IPath file, boolean localized) 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

Constructor Detail

BundleFinder

public BundleFinder()

Method Detail

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.

Parameters:

bundle - the bundle in which to search

path - 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.

See Also:

find(Bundle, IPath, Map)

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.

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.

openStream

public static final InputStream openStream(Bundle bundle,
                                           IPath file,
                                           boolean localized)
                                    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 platform searches for the correct localized version of the specified file using the users current locale, and Java naming convention for localized resource files (locale suffix appended to the specified file extension).

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

localized - true for the localized version of the file, and false for the file exactly as specified

Returns:

an input stream

Throws:

IOException - if the given path cannot be found in this plug-in

openStream

public static final InputStream openStream(Bundle bundle,
                                           IPath file)
                                    throws IOException

Returns an input stream for the specified file. The file path must be specified relative this the plug-in's installation location.

Parameters:

bundle - the bundle in which to search

file - path relative to plug-in installation location

Returns:

an input stream

Throws:

IOException - if the given path cannot be found in this plug-in

See Also:

openStream(Bundle,IPath,boolean)

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 reconized 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