Eclipse Platform
2.0

org.eclipse.core.runtime
Class Platform

java.lang.Object
  |
  +--org.eclipse.core.runtime.Platform

public final class Platform
extends Object

The central class of the Eclipse Platform Runtime. This class cannot be instantiated or subclassed by clients; all functionality is provided by static methods. Features include:

The platform is in one of two states, running or not running, at all times. The only ways to start the platform running, or to shut it down, are on the bootstrap BootLoader class. Code in plug-ins will only observe the platform in the running state. The platform cannot be shutdown from inside (code in plug-ins have no access to BootLoader).


Field Summary
static int FAILED_DELETE_METADATA
          Status code constant (value 6) indicating the platform could not delete some of its metadata.
static int FAILED_READ_METADATA
          Status code constant (value 4) indicating the platform could not read some of its metadata.
static int FAILED_WRITE_METADATA
          Status code constant (value 5) indicating the platform could not write some of its metadata.
static int INTERNAL_ERROR
          Status code constant (value 3) indicating an error internal to the platform has occurred.
static String OPTION_STARTTIME
          Debug option value denoting the time at which the platform runtime was started.
static int PARSE_PROBLEM
          Status code constant (value 1) indicating a problem in a plug-in manifest (plugin.xml) file.
static String PI_RUNTIME
          The unique identifier constant (value "org.eclipse.core.runtime") of the Core Runtime (pseudo-) plug-in.
static int PLUGIN_ERROR
          Status code constant (value 2) indicating an error occurred while running a plug-in.
static String PT_APPLICATIONS
          The simple identifier constant (value "applications") of the extension point of the Core Runtime plug-in where plug-ins declare the existence of runnable applications.
 
Method Summary
static void addAuthorizationInfo(URL serverUrl, String realm, String authScheme, Map info)
          Adds the given authorization information to the keyring.
static void addLogListener(ILogListener listener)
          Adds the given log listener to the notification list of the platform.
static void addProtectionSpace(URL resourceUrl, String realm)
          Adds the specified resource to the protection space specified by the given realm.
static URL asLocalURL(URL url)
          Returns a URL which is the local equivalent of the supplied URL.
static void endSplash()
          Takes down the splash screen if one was put up.
static void flushAuthorizationInfo(URL serverUrl, String realm, String authScheme)
          Removes the authorization information for the specified protection space and given authorization scheme.
static IAdapterManager getAdapterManager()
          Returns the adapter manager used for extending IAdaptable objects.
static Map getAuthorizationInfo(URL serverUrl, String realm, String authScheme)
          Returns the authorization information for the specified protection space and given authorization scheme.
static String[] getCommandLineArgs()
          Returns the command line args provided to the platform when it was first run.
static String getDebugOption(String option)
          Returns the identified option.
static IPath getLocation()
          Returns the location of the platform working directory.
static IPath getLogFileLocation()
          Returns the location of the platform log file.
static Plugin getPlugin(String id)
          Returns the plug-in runtime object for the identified plug-in or null if no such plug-in can be found.
static IPluginRegistry getPluginRegistry()
          Returns the plug-in registry for this platform.
static IPath getPluginStateLocation(Plugin plugin)
          Returns the location in the local file system of the plug-in state area for the given plug-in.
static String getProtectionSpace(URL resourceUrl)
          Returns the protection space (realm) for the specified resource, or null if the realm is unknown.
static PluginRegistryModel parsePlugins(URL[] pluginPath, Factory factory)
          Returns a plug-in registry containing all of the plug-ins discovered on the given plug-in path.
static void removeLogListener(ILogListener listener)
          Removes the indicated (identical) log listener from the notification list of the platform.
static URL resolve(URL url)
          Returns a URL which is the resolved equivalent of the supplied URL.
static void run(ISafeRunnable runnable)
          Runs the given runnable in a protected mode.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PI_RUNTIME

public static final String PI_RUNTIME
The unique identifier constant (value "org.eclipse.core.runtime") of the Core Runtime (pseudo-) plug-in.

See Also:
Constant Field Values

PT_APPLICATIONS

public static final String PT_APPLICATIONS
The simple identifier constant (value "applications") of the extension point of the Core Runtime plug-in where plug-ins declare the existence of runnable applications. A plug-in may define any number of applications; however, the platform is only capable of running one application at a time.

See Also:
BootLoader.run(java.lang.String, java.net.URL, java.lang.String, java.lang.String[]), Constant Field Values

OPTION_STARTTIME

public static final String OPTION_STARTTIME
Debug option value denoting the time at which the platform runtime was started. This constant can be used in conjunction with getDebugOption to find the string value of System.currentTimeMillis() when the platform was started.

See Also:
Constant Field Values

PARSE_PROBLEM

public static final int PARSE_PROBLEM
Status code constant (value 1) indicating a problem in a plug-in manifest (plugin.xml) file.

See Also:
Constant Field Values

PLUGIN_ERROR

public static final int PLUGIN_ERROR
Status code constant (value 2) indicating an error occurred while running a plug-in.

See Also:
Constant Field Values

INTERNAL_ERROR

public static final int INTERNAL_ERROR
Status code constant (value 3) indicating an error internal to the platform has occurred.

See Also:
Constant Field Values

FAILED_READ_METADATA

public static final int FAILED_READ_METADATA
Status code constant (value 4) indicating the platform could not read some of its metadata.

See Also:
Constant Field Values

FAILED_WRITE_METADATA

public static final int FAILED_WRITE_METADATA
Status code constant (value 5) indicating the platform could not write some of its metadata.

See Also:
Constant Field Values

FAILED_DELETE_METADATA

public static final int FAILED_DELETE_METADATA
Status code constant (value 6) indicating the platform could not delete some of its metadata.

See Also:
Constant Field Values
Method Detail

addAuthorizationInfo

public static void addAuthorizationInfo(URL serverUrl,
                                        String realm,
                                        String authScheme,
                                        Map info)
                                 throws CoreException
Adds the given authorization information to the keyring. The information is relevant for the specified protection space and the given authorization scheme. The protection space is defined by the combination of the given server URL and realm. The authorization scheme determines what the authorization information contains and how it should be used. The authorization information is a Map of String to String and typically contains information such as usernames and passwords.

Parameters:
serverUrl - the URL identifying the server for this authorization information. For example, "http://www.example.com/".
realm - the subsection of the given server to which this authorization information applies. For example, "realm1@example.com" or "" for no realm.
authScheme - the scheme for which this authorization information applies. For example, "Basic" or "" for no authorization scheme
info - a Map containing authorization information such as usernames and passwords (key type : String, value type : String)
Throws:
CoreException - if there are problems setting the authorization information. Reasons include:
  • The keyring could not be saved.

addLogListener

public static void addLogListener(ILogListener listener)
Adds the given log listener to the notification list of the platform.

Once registered, a listener starts receiving notification as entries are added to plug-in logs via ILog.log(). The listener continues to receive notifications until it is replaced or removed.

Parameters:
listener - the listener to register
See Also:
ILog.addLogListener(org.eclipse.core.runtime.ILogListener), removeLogListener(org.eclipse.core.runtime.ILogListener)

addProtectionSpace

public static void addProtectionSpace(URL resourceUrl,
                                      String realm)
                               throws CoreException
Adds the specified resource to the protection space specified by the given realm. All targets at or deeper than the depth of the last symbolic element in the path of the given resource URL are assumed to be in the same protection space.

Parameters:
resourceUrl - the URL identifying the resources to be added to the specified protection space. For example, "http://www.example.com/folder/".
realm - the name of the protection space. For example, "realm1@example.com"
Throws:
CoreException - if there are problems setting the authorization information. Reasons include:
  • The keyring could not be saved.

asLocalURL

public static URL asLocalURL(URL url)
                      throws IOException
Returns a URL which is the local equivalent of the supplied URL. This method is expected to be used with plug-in-relative URLs returned by IPluginDescriptor. If the specified URL is not a plug-in-relative URL, it is returned asis. If the specified URL is a plug-in-relative URL of a file (incl. .jar archive), it is returned as a locally-accessible URL using "file:" or "jar:file:" protocol (caching the file locally, if required). If the specified URL is a plug-in-relative URL of a directory, an exception is thrown.

Parameters:
url - original plug-in-relative URL.
Returns:
the resolved URL
Throws:
IOException - if unable to resolve URL
See Also:
resolve(java.net.URL), IPluginDescriptor.getInstallURL()

endSplash

public static void endSplash()
Takes down the splash screen if one was put up.


flushAuthorizationInfo

public static void flushAuthorizationInfo(URL serverUrl,
                                          String realm,
                                          String authScheme)
                                   throws CoreException
Removes the authorization information for the specified protection space and given authorization scheme. The protection space is defined by the given server URL and realm.

Parameters:
serverUrl - the URL identifying the server to remove the authorization information for. For example, "http://www.example.com/".
realm - the subsection of the given server to remove the authorization information for. For example, "realm1@example.com" or "" for no realm.
authScheme - the scheme for which the authorization information to remove applies. For example, "Basic" or "" for no authorization scheme.
Throws:
CoreException - if there are problems removing the authorization information. Reasons include:
  • The keyring could not be saved.

getAdapterManager

public static IAdapterManager getAdapterManager()
Returns the adapter manager used for extending IAdaptable objects.

Returns:
the adapter manager for this platform
See Also:
IAdapterManager

getAuthorizationInfo

public static Map getAuthorizationInfo(URL serverUrl,
                                       String realm,
                                       String authScheme)
Returns the authorization information for the specified protection space and given authorization scheme. The protection space is defined by the given server URL and realm. Returns null if no such information exists.

Parameters:
serverUrl - the URL identifying the server for the authorization information. For example, "http://www.example.com/".
realm - the subsection of the given server to which the authorization information applies. For example, "realm1@example.com" or "" for no realm.
authScheme - the scheme for which the authorization information applies. For example, "Basic" or "" for no authorization scheme
Returns:
the authorization information for the specified protection space and given authorization scheme, or null if no such information exists

getCommandLineArgs

public static String[] getCommandLineArgs()
Returns the command line args provided to the platform when it was first run. Note that individual platform runnables may be provided with different arguments if they are being run individually rather than with Platform.run().

Returns:
the command line used to start the platform

getDebugOption

public static String getDebugOption(String option)
Returns the identified option. null is returned if no such option is found. Options are specified in the general form <plug-in id>/<option-path>. For example, org.eclipse.core.runtime/debug

Parameters:
option - the name of the option to lookup
Returns:
the value of the requested debug option or null

getLocation

public static IPath getLocation()
Returns the location of the platform working directory. This corresponds to the -data command line argument if present or, if not, the current working directory when the platform was started.

Returns:
the location of the platform

getLogFileLocation

public static IPath getLogFileLocation()
Returns the location of the platform log file. This file may contain information about errors that have previously occurred during this invocation of the Platform. Note: it is very important that users of this method do not leave the log file open for extended periods of time. Doing so may prevent others from writing to the log file, which could result in important error messages being lost. It is strongly recommended that clients wanting to read the log file for extended periods should copy the log file contents elsewhere, and immediately close the original file.

Returns:
the path of the log file on disk.

getPlugin

public static Plugin getPlugin(String id)
Returns the plug-in runtime object for the identified plug-in or null if no such plug-in can be found. If the plug-in is defined but not yet activated, the plug-in will be activated before being returned.

Parameters:
id - the unique identifier of the desired plug-in (e.g., "com.example.acme").
Returns:
the plug-in runtime object, or null

getPluginRegistry

public static IPluginRegistry getPluginRegistry()
Returns the plug-in registry for this platform.

Returns:
the plug-in registry
See Also:
IPluginRegistry

getPluginStateLocation

public static IPath getPluginStateLocation(Plugin plugin)
Returns the location in the local file system of the plug-in state area for the given plug-in. The platform must be running.

The plug-in state area is a file directory within the platform's metadata area where a plug-in is free to create files. The content and structure of this area is defined by the plug-in, and the particular plug-in is solely responsible for any files it puts there. It is recommended for plug-in preference settings.

Parameters:
plugin - the plug-in whose state location is returned
Returns:
a local file system path

getProtectionSpace

public static String getProtectionSpace(URL resourceUrl)
Returns the protection space (realm) for the specified resource, or null if the realm is unknown.

Parameters:
resourceUrl - the URL of the resource whose protection space is returned. For example, "http://www.example.com/folder/".
Returns:
the protection space (realm) for the specified resource, or null if the realm is unknown

parsePlugins

public static PluginRegistryModel parsePlugins(URL[] pluginPath,
                                               Factory factory)
Returns a plug-in registry containing all of the plug-ins discovered on the given plug-in path. Any problems encountered are added to the status managed by the supplied factory.

The given plug-in path is the list of locations in which to look for plug-ins. If an entry identifies a directory (i.e., ends in a '/'), this method attempts to scan all sub-directories for plug-ins. Alternatively, an entry may identify a particular plug-in manifest (plugin.xml) file.

Note: this method does not affect the running platform. It is intended for introspecting installed plug-ins on this and other platforms. The returned registry is not the same as the platform's registry.

Parameters:
pluginPath - the list of locations in which to look for plug-ins
factory - the factory to use to create runtime model objects
Returns:
the registry of parsed plug-ins

removeLogListener

public static void removeLogListener(ILogListener listener)
Removes the indicated (identical) log listener from the notification list of the platform. If no such listener exists, no action is taken.

Parameters:
listener - the listener to deregister
See Also:
ILog.removeLogListener(org.eclipse.core.runtime.ILogListener), addLogListener(org.eclipse.core.runtime.ILogListener)

resolve

public static URL resolve(URL url)
                   throws IOException
Returns a URL which is the resolved equivalent of the supplied URL. This method is expected to be used with plug-in-relative URLs returned by IPluginDescriptor. If the specified URL is not a plug-in-relative URL, it is returned as is. If the specified URL is a plug-in-relative URL, it is resolved to a URL using the actual URL protocol (eg. file, http, etc)

Parameters:
url - original plug-in-relative URL.
Returns:
the resolved URL
Throws:
IOException - if unable to resolve URL
See Also:
asLocalURL(java.net.URL), IPluginDescriptor.getInstallURL()

run

public static void run(ISafeRunnable runnable)
Runs the given runnable in a protected mode. Exceptions thrown in the runnable are logged and passed to the runnable's exception handler. Such exceptions are not rethrown by this method.


Eclipse Platform
2.0

Copyright (c) IBM Corp. and others 2000, 2002. All Rights Reserved.