Source code: org/eclipse/core/runtime/Platform.java
1 /*******************************************************************************
2 * Copyright (c) 2000, 2004 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
7 *
8 * Contributors:
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package org.eclipse.core.runtime;
12
13 import java.io.IOException;
14 import java.lang.reflect.Method;
15 import java.net.URL;
16 import java.util.*;
17 import org.eclipse.core.internal.runtime.*;
18 import org.eclipse.core.runtime.content.IContentTypeManager;
19 import org.eclipse.core.runtime.jobs.IJobManager;
20 import org.eclipse.core.runtime.preferences.IPreferencesService;
21 import org.eclipse.osgi.service.datalocation.Location;
22 import org.eclipse.osgi.service.resolver.PlatformAdmin;
23 import org.osgi.framework.Bundle;
24
25 /**
26 * The central class of the Eclipse Platform Runtime. This class cannot
27 * be instantiated or subclassed by clients; all functionality is provided
28 * by static methods. Features include:
29 * <ul>
30 * <li>the platform registry of installed plug-ins</li>
31 * <li>the platform adapter manager</li>
32 * <li>the platform log</li>
33 * <li>the authorization info management</li>
34 * </ul>
35 */
36 public final class Platform {
37
38 /**
39 * The unique identifier constant (value "<code>org.eclipse.core.runtime</code>")
40 * of the Core Runtime (pseudo-) plug-in.
41 */
42 public static final String PI_RUNTIME = "org.eclipse.core.runtime"; //$NON-NLS-1$
43
44 /**
45 * The simple identifier constant (value "<code>applications</code>") of
46 * the extension point of the Core Runtime plug-in where plug-ins declare
47 * the existence of runnable applications. A plug-in may define any
48 * number of applications; however, the platform is only capable
49 * of running one application at a time.
50 *
51 */
52 public static final String PT_APPLICATIONS = "applications"; //$NON-NLS-1$
53
54 /**
55 * The simple identifier constant (value "<code>adapters</code>") of
56 * the extension point of the Core Runtime plug-in where plug-ins declare
57 * the existence of adapter factories. A plug-in may define any
58 * number of adapters.
59 *
60 * @see IAdapterManager#hasAdapter(Object, String)
61 * @since 3.0
62 */
63 public static final String PT_ADAPTERS = "adapters"; //$NON-NLS-1$
64
65 /**
66 * The simple identifier constant (value "<code>preferences</code>") of
67 * the extension point of the Core Runtime plug-in where plug-ins declare
68 * extensions to the preference facility. A plug-in may define any number
69 * of preference extensions.
70 *
71 * @see #getPreferencesService()
72 * @since 3.0
73 */
74 public static final String PT_PREFERENCES = "preferences"; //$NON-NLS-1$
75
76 /**
77 * The simple identifier constant (value "<code>products</code>") of
78 * the extension point of the Core Runtime plug-in where plug-ins declare
79 * the existence of a product. A plug-in may define any
80 * number of products; however, the platform is only capable
81 * of running one product at a time.
82 *
83 * @see #getProduct()
84 * @since 3.0
85 */
86 public static final String PT_PRODUCT = "products"; //$NON-NLS-1$
87 /**
88 * Debug option value denoting the time at which the platform runtime
89 * was started. This constant can be used in conjunction with
90 * <code>getDebugOption</code> to find the string value of
91 * <code>System.currentTimeMillis()</code> when the platform was started.
92 */
93 public static final String OPTION_STARTTIME = PI_RUNTIME + "/starttime"; //$NON-NLS-1$
94
95 /**
96 * Name of a preference for configuring the performance level for this system.
97 *
98 * <p>
99 * This value can be used by all components to customize features to suit the
100 * speed of the user's machine. The platform job manager uses this value to make
101 * scheduling decisions about background jobs.
102 * </p>
103 * <p>
104 * The preference value must be an integer between the constant values
105 * MIN_PERFORMANCE and MAX_PERFORMANCE
106 * </p>
107 * @see #MIN_PERFORMANCE
108 * @see #MAX_PERFORMANCE
109 * @since 3.0
110 */
111 public static final String PREF_PLATFORM_PERFORMANCE = "runtime.performance"; //$NON-NLS-1$
112
113 /**
114 * Constant (value 1) indicating the minimum allowed value for the
115 * <code>PREF_PLATFORM_PERFORMANCE</code> preference setting.
116 * @since 3.0
117 */
118 public static final int MIN_PERFORMANCE = 1;
119
120 /**
121 * Constant (value 5) indicating the maximum allowed value for the
122 * <code>PREF_PLATFORM_PERFORMANCE</code> preference setting.
123 * @since 3.0
124 */
125 public static final int MAX_PERFORMANCE = 5;
126
127 /**
128 * Status code constant (value 1) indicating a problem in a plug-in
129 * manifest (<code>plugin.xml</code>) file.
130 */
131 public static final int PARSE_PROBLEM = 1;
132
133 /**
134 * Status code constant (value 2) indicating an error occurred while running a plug-in.
135 */
136 public static final int PLUGIN_ERROR = 2;
137
138 /**
139 * Status code constant (value 3) indicating an error internal to the
140 * platform has occurred.
141 */
142 public static final int INTERNAL_ERROR = 3;
143
144 /**
145 * Status code constant (value 4) indicating the platform could not read
146 * some of its metadata.
147 */
148 public static final int FAILED_READ_METADATA = 4;
149
150 /**
151 * Status code constant (value 5) indicating the platform could not write
152 * some of its metadata.
153 */
154 public static final int FAILED_WRITE_METADATA = 5;
155
156 /**
157 * Status code constant (value 6) indicating the platform could not delete
158 * some of its metadata.
159 */
160 public static final int FAILED_DELETE_METADATA = 6;
161
162 /**
163 * Constant string (value "win32") indicating the platform is running on a
164 * Window 32-bit operating system (e.g., Windows 98, NT, 2000).
165 * <p>
166 * Note this constant has been moved from the deprecated
167 * org.eclipse.core.boot.BootLoader class and its value has not changed.
168 * </p>
169 * @since 3.0
170 */
171 public static final String OS_WIN32 = "win32";//$NON-NLS-1$
172
173 /**
174 * Constant string (value "linux") indicating the platform is running on a
175 * Linux-based operating system.
176 * <p>
177 * Note this constant has been moved from the deprecated
178 * org.eclipse.core.boot.BootLoader class and its value has not changed.
179 * </p>
180 * @since 3.0
181 */
182 public static final String OS_LINUX = "linux";//$NON-NLS-1$
183
184 /**
185 * Constant string (value "aix") indicating the platform is running on an
186 * AIX-based operating system.
187 * <p>
188 * Note this constant has been moved from the deprecated
189 * org.eclipse.core.boot.BootLoader class and its value has not changed.
190 * </p>
191 * @since 3.0
192 */
193 public static final String OS_AIX = "aix";//$NON-NLS-1$
194
195 /**
196 * Constant string (value "solaris") indicating the platform is running on a
197 * Solaris-based operating system.
198 * <p>
199 * Note this constant has been moved from the deprecated
200 * org.eclipse.core.boot.BootLoader class and its value has not changed.
201 * </p>
202 * @since 3.0
203 */
204 public static final String OS_SOLARIS = "solaris";//$NON-NLS-1$
205
206 /**
207 * Constant string (value "hpux") indicating the platform is running on an
208 * HP/UX-based operating system.
209 * <p>
210 * Note this constant has been moved from the deprecated
211 * org.eclipse.core.boot.BootLoader class and its value has not changed.
212 * </p>
213 * @since 3.0
214 */
215 public static final String OS_HPUX = "hpux";//$NON-NLS-1$
216
217 /**
218 * Constant string (value "qnx") indicating the platform is running on a
219 * QNX-based operating system.
220 * <p>
221 * Note this constant has been moved from the deprecated
222 * org.eclipse.core.boot.BootLoader class and its value has not changed.
223 * </p>
224 * @since 3.0
225 */
226 public static final String OS_QNX = "qnx";//$NON-NLS-1$
227
228 /**
229 * Constant string (value "macosx") indicating the platform is running on a
230 * Mac OS X operating system.
231 * <p>
232 * Note this constant has been moved from the deprecated
233 * org.eclipse.core.boot.BootLoader class and its value has not changed.
234 * </p>
235 * @since 3.0
236 */
237 public static final String OS_MACOSX = "macosx";//$NON-NLS-1$
238
239 /**
240 * Constant string (value "unknown") indicating the platform is running on a
241 * machine running an unknown operating system.
242 * <p>
243 * Note this constant has been moved from the deprecated
244 * org.eclipse.core.boot.BootLoader class and its value has not changed.
245 * </p>
246 * @since 3.0
247 */
248 public static final String OS_UNKNOWN = "unknown";//$NON-NLS-1$
249
250 /**
251 * Constant string (value "x86") indicating the platform is running on an
252 * x86-based architecture.
253 * <p>
254 * Note this constant has been moved from the deprecated
255 * org.eclipse.core.boot.BootLoader class and its value has not changed.
256 * </p>
257 * @since 3.0
258 */
259 public static final String ARCH_X86 = "x86";//$NON-NLS-1$
260
261 /**
262 * Constant string (value "PA_RISC") indicating the platform is running on an
263 * PA_RISC-based architecture.
264 * <p>
265 * Note this constant has been moved from the deprecated
266 * org.eclipse.core.boot.BootLoader class and its value has not changed.
267 * </p>
268 * @since 3.0
269 */
270 public static final String ARCH_PA_RISC = "PA_RISC";//$NON-NLS-1$
271
272 /**
273 * Constant string (value "ppc") indicating the platform is running on an
274 * PowerPC-based architecture.
275 * <p>
276 * Note this constant has been moved from the deprecated
277 * org.eclipse.core.boot.BootLoader class and its value has not changed.
278 * </p>
279 * @since 3.0
280 */
281 public static final String ARCH_PPC = "ppc";//$NON-NLS-1$
282
283 /**
284 * Constant string (value "sparc") indicating the platform is running on an
285 * Sparc-based architecture.
286 * <p>
287 * Note this constant has been moved from the deprecated
288 * org.eclipse.core.boot.BootLoader class and its value has not changed.
289 * </p>
290 * @since 3.0
291 */
292 public static final String ARCH_SPARC = "sparc";//$NON-NLS-1$
293
294 /**
295 * Constant string (value "amd64") indicating the platform is running on an
296 * AMD64-based architecture.
297 *
298 * @since 3.0
299 */
300 public static final String ARCH_AMD64 = "amd64";//$NON-NLS-1$
301
302 /**
303 * Constant string (value "ia64") indicating the platform is running on an
304 * IA64-based architecture.
305 *
306 * @since 3.0
307 */
308 public static final String ARCH_IA64 = "ia64"; //$NON-NLS-1$
309
310 /**
311 * Constant string (value "win32") indicating the platform is running on a
312 * machine using the Windows windowing system.
313 * <p>
314 * Note this constant has been moved from the deprecated
315 * org.eclipse.core.boot.BootLoader class and its value has not changed.
316 * </p>
317 * @since 3.0
318 */
319 public static final String WS_WIN32 = "win32";//$NON-NLS-1$
320
321 /**
322 * Constant string (value "motif") indicating the platform is running on a
323 * machine using the Motif windowing system.
324 * <p>
325 * Note this constant has been moved from the deprecated
326 * org.eclipse.core.boot.BootLoader class and its value has not changed.
327 * </p>
328 * @since 3.0
329 */
330 public static final String WS_MOTIF = "motif";//$NON-NLS-1$
331
332 /**
333 * Constant string (value "gtk") indicating the platform is running on a
334 * machine using the GTK windowing system.
335 * <p>
336 * Note this constant has been moved from the deprecated
337 * org.eclipse.core.boot.BootLoader class and its value has not changed.
338 * </p>
339 * @since 3.0
340 */
341 public static final String WS_GTK = "gtk";//$NON-NLS-1$
342
343 /**
344 * Constant string (value "photon") indicating the platform is running on a
345 * machine using the Photon windowing system.
346 * <p>
347 * Note this constant has been moved from the deprecated
348 * org.eclipse.core.boot.BootLoader class and its value has not changed.
349 * </p>
350 * @since 3.0
351 */
352 public static final String WS_PHOTON = "photon";//$NON-NLS-1$
353
354 /**
355 * Constant string (value "carbon") indicating the platform is running on a
356 * machine using the Carbon windowing system (Mac OS X).
357 * <p>
358 * Note this constant has been moved from the deprecated
359 * org.eclipse.core.boot.BootLoader class and its value has not changed.
360 * </p>
361 * @since 3.0
362 */
363 public static final String WS_CARBON = "carbon";//$NON-NLS-1$
364
365 /**
366 * Constant string (value "unknown") indicating the platform is running on a
367 * machine running an unknown windowing system.
368 * <p>
369 * Note this constant has been moved from the deprecated
370 * org.eclipse.core.boot.BootLoader class and its value has not changed.
371 * </p>
372 * @since 3.0
373 */
374 public static final String WS_UNKNOWN = "unknown";//$NON-NLS-1$
375
376 /**
377 * Private constructor to block instance creation.
378 */
379 private Platform() {
380 super();
381 }
382
383 /**
384 * Adds the given authorization information to the keyring. The
385 * information is relevant for the specified protection space and the
386 * given authorization scheme. The protection space is defined by the
387 * combination of the given server URL and realm. The authorization
388 * scheme determines what the authorization information contains and how
389 * it should be used. The authorization information is a <code>Map</code>
390 * of <code>String</code> to <code>String</code> and typically
391 * contains information such as usernames and passwords.
392 *
393 * @param serverUrl the URL identifying the server for this authorization
394 * information. For example, "http://www.example.com/".
395 * @param realm the subsection of the given server to which this
396 * authorization information applies. For example,
397 * "realm1@example.com" or "" for no realm.
398 * @param authScheme the scheme for which this authorization information
399 * applies. For example, "Basic" or "" for no authorization scheme
400 * @param info a <code>Map</code> containing authorization information
401 * such as usernames and passwords (key type : <code>String</code>,
402 * value type : <code>String</code>)
403 * @exception CoreException if there are problems setting the
404 * authorization information. Reasons include:
405 * <ul>
406 * <li>The keyring could not be saved.</li>
407 * </ul>
408 */
409 public static void addAuthorizationInfo(URL serverUrl, String realm, String authScheme, Map info) throws CoreException {
410 InternalPlatform.getDefault().addAuthorizationInfo(serverUrl, realm, authScheme, info);
411 }
412
413 /**
414 * Adds the given log listener to the notification list of the platform.
415 * <p>
416 * Once registered, a listener starts receiving notification as entries
417 * are added to plug-in logs via <code>ILog.log()</code>. The listener continues to
418 * receive notifications until it is replaced or removed.
419 * </p>
420 *
421 * @param listener the listener to register
422 * @see ILog#addLogListener(ILogListener)
423 * @see #removeLogListener(ILogListener)
424 */
425 public static void addLogListener(ILogListener listener) {
426 InternalPlatform.getDefault().addLogListener(listener);
427 }
428
429 /**
430 * Adds the specified resource to the protection space specified by the
431 * given realm. All targets at or deeper than the depth of the last
432 * symbolic element in the path of the given resource URL are assumed to
433 * be in the same protection space.
434 *
435 * @param resourceUrl the URL identifying the resources to be added to
436 * the specified protection space. For example,
437 * "http://www.example.com/folder/".
438 * @param realm the name of the protection space. For example,
439 * "realm1@example.com"
440 * @exception CoreException if there are problems setting the
441 * authorization information. Reasons include:
442 * <ul>
443 * <li>The keyring could not be saved.</li>
444 * </ul>
445 */
446 public static void addProtectionSpace(URL resourceUrl, String realm) throws CoreException {
447 InternalPlatform.getDefault().addProtectionSpace(resourceUrl, realm);
448 }
449
450 /**
451 * Returns a URL which is the local equivalent of the
452 * supplied URL. This method is expected to be used with the
453 * plug-in-relative URLs returned by IPluginDescriptor, Bundle.getEntry()
454 * and Platform.find().
455 * If the specified URL is not a plug-in-relative URL, it
456 * is returned asis. If the specified URL is a plug-in-relative
457 * URL of a file (incl. .jar archive), it is returned as
458 * a locally-accessible URL using "file:" or "jar:file:" protocol
459 * (caching the file locally, if required). If the specified URL
460 * is a plug-in-relative URL of a directory,
461 * an exception is thrown.
462 *
463 * @param url original plug-in-relative URL.
464 * @return the resolved URL
465 * @exception IOException if unable to resolve URL
466 * @see #resolve(URL)
467 * @see #find(Bundle, IPath)
468 * @see Bundle#getEntry(String)
469 */
470 public static URL asLocalURL(URL url) throws IOException {
471 return InternalPlatform.getDefault().asLocalURL(url);
472 }
473
474 /**
475 * Takes down the splash screen if one was put up.
476 */
477 public static void endSplash() {
478 InternalPlatform.getDefault().endSplash();
479 }
480
481 /**
482 * Removes the authorization information for the specified protection
483 * space and given authorization scheme. The protection space is defined
484 * by the given server URL and realm.
485 *
486 * @param serverUrl the URL identifying the server to remove the
487 * authorization information for. For example,
488 * "http://www.example.com/".
489 * @param realm the subsection of the given server to remove the
490 * authorization information for. For example,
491 * "realm1@example.com" or "" for no realm.
492 * @param authScheme the scheme for which the authorization information
493 * to remove applies. For example, "Basic" or "" for no
494 * authorization scheme.
495 * @exception CoreException if there are problems removing the
496 * authorization information. Reasons include:
497 * <ul>
498 * <li>The keyring could not be saved.</li>
499 * </ul>
500 */
501 public static void flushAuthorizationInfo(URL serverUrl, String realm, String authScheme) throws CoreException {
502 InternalPlatform.getDefault().flushAuthorizationInfo(serverUrl, realm, authScheme);
503 }
504
505 /**
506 * Returns the adapter manager used for extending
507 * <code>IAdaptable</code> objects.
508 *
509 * @return the adapter manager for this platform
510 * @see IAdapterManager
511 */
512 public static IAdapterManager getAdapterManager() {
513 return InternalPlatform.getDefault().getAdapterManager();
514 }
515
516 /**
517 * Returns the authorization information for the specified protection
518 * space and given authorization scheme. The protection space is defined
519 * by the given server URL and realm. Returns <code>null</code> if no
520 * such information exists.
521 *
522 * @param serverUrl the URL identifying the server for the authorization
523 * information. For example, "http://www.example.com/".
524 * @param realm the subsection of the given server to which the
525 * authorization information applies. For example,
526 * "realm1@example.com" or "" for no realm.
527 * @param authScheme the scheme for which the authorization information
528 * applies. For example, "Basic" or "" for no authorization scheme
529 * @return the authorization information for the specified protection
530 * space and given authorization scheme, or <code>null</code> if no
531 * such information exists
532 */
533 public static Map getAuthorizationInfo(URL serverUrl, String realm, String authScheme) {
534 return InternalPlatform.getDefault().getAuthorizationInfo(serverUrl, realm, authScheme);
535 }
536
537 /**
538 * Returns the command line args provided to the Eclipse runtime layer when it was first run.
539 * The returned value does not include arguments consumed by the lower levels of Eclipse
540 * (e.g., OSGi or the launcher).
541 * Note that individual platform runnables may be provided with different arguments
542 * if they are being run individually rather than with <code>Platform.run()</code>.
543 *
544 * @return the command line used to start the platform
545 */
546 public static String[] getCommandLineArgs() {
547 return InternalPlatform.getDefault().getCommandLineArgs();
548 }
549
550 /**
551 * Returns the content type manager.
552 *
553 * @return the content type manager
554 * @since 3.0
555 */
556 public static IContentTypeManager getContentTypeManager() {
557 return InternalPlatform.getDefault().getContentTypeManager();
558 }
559
560 /**
561 * Returns the identified option. <code>null</code>
562 * is returned if no such option is found. Options are specified
563 * in the general form <i><plug-in id>/<option-path></i>.
564 * For example, <code>org.eclipse.core.runtime/debug</code>
565 *
566 * @param option the name of the option to lookup
567 * @return the value of the requested debug option or <code>null</code>
568 */
569 public static String getDebugOption(String option) {
570 return InternalPlatform.getDefault().getOption(option);
571 }
572
573 /**
574 * Returns the location of the platform working directory.
575 * <p>
576 * Callers of this method should consider using <code>getInstanceLocation</code>
577 * instead. In various, typically non IDE-related configurations of Eclipse, the platform
578 * working directory may not be on the local filesystem. As such, the more general
579 * form of this location is as a URL.
580 * </p>
581 *
582 * @return the location of the platform
583 * @see #getInstanceLocation()
584 */
585 public static IPath getLocation() throws IllegalStateException {
586 return InternalPlatform.getDefault().getLocation();
587 }
588
589 /**
590 * Returns the location of the platform log file. This file may contain information
591 * about errors that have previously occurred during this invocation of the Platform.
592 *
593 * It is recommended not to keep this value, as the log location may vary when an instance
594 * location is being set.
595 * s
596 * Note: it is very important that users of this method do not leave the log
597 * file open for extended periods of time. Doing so may prevent others
598 * from writing to the log file, which could result in important error messages
599 * being lost. It is strongly recommended that clients wanting to read the
600 * log file for extended periods should copy the log file contents elsewhere,
601 * and immediately close the original file.
602 *
603 * @return the path of the log file on disk.
604 */
605 public static IPath getLogFileLocation() {
606 return InternalPlatform.getDefault().getMetaArea().getLogLocation();
607 }
608
609 /**
610 * Returns the plug-in runtime object for the identified plug-in
611 * or <code>null</code> if no such plug-in can be found. If
612 * the plug-in is defined but not yet activated, the plug-in will
613 * be activated before being returned.
614 * <p>
615 * <b>Note</b>: This method is only able to find and return plug-in
616 * objects for plug-ins described using plugin.xml according to the
617 * traditional Eclipse conventions. Eclipse 3.0 permits plug-ins to be
618 * described in manifest.mf files and to define their own bundle
619 * activators. Such plug-ins cannot be discovered by this method.</p>
620 *
621 * @param id the unique identifier of the desired plug-in
622 * (e.g., <code>"com.example.acme"</code>).
623 * @return the plug-in runtime object, or <code>null</code>
624 * @deprecated
625 * This method only works if the compatibility layer is installed and must not be used otherwise.
626 * See the comments on {@link IPluginDescriptor#getPlugin()} for details.
627 */
628 public static Plugin getPlugin(String id) {
629 try {
630 IPluginRegistry registry = getPluginRegistry();
631 if (registry == null)
632 throw new IllegalStateException();
633 IPluginDescriptor pd = registry.getPluginDescriptor(id);
634 if (pd == null)
635 return null;
636 return pd.getPlugin();
637 } catch (CoreException e) {
638 // TODO log the exception
639 }
640 return null;
641 }
642
643 /**
644 * Returns the plug-in registry for this platform.
645 *
646 * @return the plug-in registry
647 * @see IPluginRegistry
648 * @deprecated <code>IPluginRegistry</code> was refactored in Eclipse 3.0.
649 * This method only works if the compatibility layer is installed and must not be used otherwise.
650 * See the comments on {@link IPluginRegistry} and its methods for details.
651 */
652 public static IPluginRegistry getPluginRegistry() {
653 Bundle compatibility = InternalPlatform.getDefault().getBundle(CompatibilityHelper.PI_RUNTIME_COMPATIBILITY);
654 if (compatibility == null)
655 throw new IllegalStateException();
656
657 Class oldInternalPlatform = null;
658 try {
659 oldInternalPlatform = compatibility.loadClass("org.eclipse.core.internal.plugins.InternalPlatform"); //$NON-NLS-1$
660 Method getPluginRegistry = oldInternalPlatform.getMethod("getPluginRegistry", null); //$NON-NLS-1$
661 return (IPluginRegistry) getPluginRegistry.invoke(oldInternalPlatform, null);
662 } catch (Exception e) {
663 //Ignore the exceptions, return null
664 }
665 return null;
666
667 }
668
669 /**
670 * Returns the location in the local file system of the plug-in
671 * state area for the given plug-in.
672 * The platform must be running.
673 * <p>
674 * The plug-in state area is a file directory within the
675 * platform's metadata area where a plug-in is free to create files.
676 * The content and structure of this area is defined by the plug-in,
677 * and the particular plug-in is solely responsible for any files
678 * it puts there. It is recommended for plug-in preference settings.
679 * </p>
680 *
681 * @param plugin the plug-in whose state location is returned
682 * @return a local file system path
683 */
684 public static IPath getPluginStateLocation(Plugin plugin) {
685 return plugin.getStateLocation();
686 }
687
688 /**
689 * Returns the protection space (realm) for the specified resource, or
690 * <code>null</code> if the realm is unknown.
691 *
692 * @param resourceUrl the URL of the resource whose protection space is
693 * returned. For example, "http://www.example.com/folder/".
694 * @return the protection space (realm) for the specified resource, or
695 * <code>null</code> if the realm is unknown
696 */
697 public static String getProtectionSpace(URL resourceUrl) {
698 return InternalPlatform.getDefault().getProtectionSpace(resourceUrl);
699 }
700
701 /**
702 * Removes the indicated (identical) log listener from the notification list
703 * of the platform. If no such listener exists, no action is taken.
704 *
705 * @param listener the listener to deregister
706 * @see ILog#removeLogListener(ILogListener)
707 * @see #addLogListener(ILogListener)
708 */
709 public static void removeLogListener(ILogListener listener) {
710 InternalPlatform.getDefault().removeLogListener(listener);
711 }
712
713 /**
714 * Returns a URL which is the resolved equivalent of the
715 * supplied URL. This method is expected to be used with the
716 * plug-in-relative URLs returned by IPluginDescriptor, Bundle.getEntry()
717 * and Platform.find().
718 * <p>
719 * If the specified URL is not a plug-in-relative URL, it is returned
720 * as is. If the specified URL is a plug-in-relative URL, this method
721 * attempts to reduce the given URL to one which is native to the Java
722 * class library (eg. file, http, etc).
723 * </p><p>
724 * Note however that users of this API should not assume too much about the
725 * results of this method. While it may consistently return a file: URL in certain
726 * installation configurations, others may result in jar: or http: URLs.
727 * </p>
728 * @param url original plug-in-relative URL.
729 * @return the resolved URL
730 * @exception IOException if unable to resolve URL
731 * @see #asLocalURL(URL)
732 * @see #find(Bundle, IPath)
733 * @see Bundle#getEntry(String)
734 */
735 public static URL resolve(URL url) throws IOException {
736 return InternalPlatform.getDefault().resolve(url);
737 }
738
739 /**
740 * Runs the given runnable in a protected mode. Exceptions
741 * thrown in the runnable are logged and passed to the runnable's
742 * exception handler. Such exceptions are not rethrown by this method.
743 *
744 * @param runnable the runnable to run
745 */
746 public static void run(ISafeRunnable runnable) {
747 InternalPlatform.getDefault().run(runnable);
748 }
749
750 /**
751 * Returns the platform job manager.
752 *
753 * @return the platform's job manager
754 * @since 3.0
755 */
756 public static IJobManager getJobManager() {
757 return InternalPlatform.getDefault().getJobManager();
758 }
759
760 /**
761 * Returns the extension registry for this platform.
762 *
763 * @return the extension registry
764 * @see IExtensionRegistry
765 * @since 3.0
766 */
767 public static IExtensionRegistry getExtensionRegistry() {
768 return InternalPlatform.getDefault().getRegistry();
769 }
770
771 /**
772 * Returns a URL for the given path in the given bundle. Returns <code>null</code> if the URL
773 * could not be computed or created.
774 *
775 * @param bundle the bundle in which to search
776 * @param path path relative to plug-in installation location
777 * @return a URL for the given path or <code>null</code>. The actual form
778 * of the returned URL is not specified.
779 * @see #find(Bundle, IPath, Map)
780 * @see #resolve(URL)
781 * @see #asLocalURL(URL)
782 * @since 3.0
783 */
784 public static URL find(Bundle bundle, IPath path) {
785 return FindSupport.find(bundle, path, null);
786 }
787
788 /**
789 * Returns a URL for the given path in the given bundle. Returns <code>null</code> if the URL
790 * could not be computed or created.
791 * <p>
792 * find looks for this path in given bundle and any attached fragments.
793 * <code>null</code> is returned if no such entry is found. Note that
794 * there is no specific order to the fragments.
795 * </p><p>
796 * The following arguments may also be used
797 * <pre>
798 * $nl$ - for language specific information
799 * $os$ - for operating system specific information
800 * $ws$ - for windowing system specific information
801 * </pre>
802 * </p><p>
803 * A path of $nl$/about.properties in an environment with a default
804 * locale of en_CA will return a URL corresponding to the first place
805 * about.properties is found according to the following order:
806 * <pre>
807 * plugin root/nl/en/CA/about.properties
808 * fragment1 root/nl/en/CA/about.properties
809 * fragment2 root/nl/en/CA/about.properties
810 * ...
811 * plugin root/nl/en/about.properties
812 * fragment1 root/nl/en/about.properties
813 * fragment2 root/nl/en/about.properties
814 * ...
815 * plugin root/about.properties
816 * fragment1 root/about.properties
817 * fragment2 root/about.properties
818 * ...
819 * </pre>
820 * </p><p>
821 * The current environment variable values can be overridden using
822 * the override map argument.
823 * </p>
824 *
825 * @param bundle the bundle in which to search
826 * @param path file path relative to plug-in installation location
827 * @param override map of override substitution arguments to be used for
828 * any $arg$ path elements. The map keys correspond to the substitution
829 * arguments (eg. "$nl$" or "$os$"). The resulting
830 * values must be of type java.lang.String. If the map is <code>null</code>,
831 * or does not contain the required substitution argument, the default
832 * is used.
833 * @return a URL for the given path or <code>null</code>. The actual form
834 * of the returned URL is not specified.
835 * @see #resolve(URL)
836 * @see #asLocalURL(URL)
837 * @since 3.0
838 */
839 public static URL find(Bundle bundle, IPath path, Map override) {
840 return FindSupport.find(bundle, path, override);
841 }
842
843 /**
844 * Returns the location in the local file system of the
845 * plug-in state area for the given bundle.
846 * If the plug-in state area did not exist prior to this call,
847 * it is created.
848 * <p>
849 * The plug-in state area is a file directory within the
850 * platform's metadata area where a plug-in is free to create files.
851 * The content and structure of this area is defined by the plug-in,
852 * and the particular plug-in is solely responsible for any files
853 * it puts there. It is recommended for plug-in preference settings and
854 * other configuration parameters.
855 * </p>
856 *
857 * @param bundle the bundle whose state location if returned
858 * @return a local file system path
859 * @since 3.0
860 */
861 public static IPath getStateLocation(Bundle bundle) {
862 return InternalPlatform.getDefault().getStateLocation(bundle);
863 }
864
865 /**
866 * Returns the log for the given bundle. If no such log exists, one is created.
867 *
868 * @param bundle the bundle whose log is returned
869 * @return the log for the given bundle
870 * @since 3.0
871 */
872 public static ILog getLog(Bundle bundle) {
873 return InternalPlatform.getDefault().getLog(bundle);
874 }
875
876 /**
877 * Returns the given bundle's resource bundle for the current locale.
878 * <p>
879 * The resource bundle is typcially stored as the <code>plugin.properties</code> file
880 * in the plug-in itself, and contains any translatable
881 * strings used in the plug-in manifest file (<code>plugin.xml</code>)
882 * along with other resource strings used by the plug-in implementation.
883 * </p>
884 *
885 * @param bundle the bundle whose resource bundle is being queried
886 * @return the resource bundle
887 * @exception MissingResourceException if the resource bundle was not found
888 * @since 3.0
889 */
890 public static ResourceBundle getResourceBundle(Bundle bundle) throws MissingResourceException {
891 return InternalPlatform.getDefault().getResourceBundle(bundle);
892 }
893
894 /**
895 * Returns a resource string corresponding to the given argument value.
896 * If the argument value specifies a resource key, the string
897 * is looked up in the default resource bundle for the given runtime bundle. If the argument does not
898 * specify a valid key, the argument itself is returned as the
899 * resource string. The key lookup is performed in the
900 * file referenced in the Bundle-Localization header of the bundle manifest. If a resource string
901 * corresponding to the key is not found in the resource bundle
902 * the key value, or any default text following the key in the
903 * argument value is returned as the resource string.
904 * A key is identified as a string begining with the "%" character.
905 * Note, that the "%" character is stripped off prior to lookup
906 * in the resource bundle.
907 * <p>
908 * Equivalent to <code>getResourceString(bundle, value, getResourceBundle())</code>
909 * </p>
910 *
911 * @param bundle the bundle whose resource bundle is being queried
912 * @param value the value to look for
913 * @return the resource string
914 * @see #getResourceBundle(Bundle)
915 * @since 3.0
916 */
917 public static String getResourceString(Bundle bundle, String value) {
918 return InternalPlatform.getDefault().getResourceString(bundle, value);
919 }
920
921 /**
922 * Returns a resource string corresponding to the given argument
923 * value and resource bundle in the given runtime bundle.
924 * If the argument value specifies a resource key, the string
925 * is looked up in the given resource bundle. If the argument does not
926 * specify a valid key, the argument itself is returned as the
927 * resource string. The key lookup is performed against the
928 * specified resource bundle. If a resource string
929 * corresponding to the key is not found in the resource bundle
930 * the key value, or any default text following the key in the
931 * argument value is returned as the resource string.
932 * A key is identified as a string begining with the "%" character.
933 * Note that the "%" character is stripped off prior to lookup
934 * in the resource bundle.
935 * <p>
936 * For example, assume resource bundle plugin.properties contains
937 * name = Project Name
938 * <pre>
939 * getResourceString("Hello World") returns "Hello World"</li>
940 * getResourceString("%name") returns "Project Name"</li>
941 * getResourceString("%name Hello World") returns "Project Name"</li>
942 * getResourceString("%abcd Hello World") returns "Hello World"</li>
943 * getResourceString("%abcd") returns "%abcd"</li>
944 * getResourceString("%%name") returns "%name"</li>
945 * </pre>
946 * </p>
947 *
948 * @param bundle the bundle whose resource bundle is being queried
949 * @param value the value
950 * @param resourceBundle the resource bundle to query
951 * @return the resource string
952 * @see #getResourceBundle(Bundle)
953 * @since 3.0
954 */
955 public static String getResourceString(Bundle bundle, String value, ResourceBundle resourceBundle) {
956 return InternalPlatform.getDefault().getResourceString(bundle, value, resourceBundle);
957 }
958
959 /**
960 * Returns the string name of the current system architecture.
961 * The value is a user-defined string if the architecture is
962 * specified on the command line, otherwise it is the value
963 * returned by <code>java.lang.System.getProperty("os.arch")</code>.
964 *
965 * @return the string name of the current system architecture
966 * @since 3.0
967 */
968 public static String getOSArch() {
969 return InternalPlatform.getDefault().getOSArch();
970 }
971
972 /**
973 * Returns the string name of the current locale for use in finding files
974 * whose path starts with <code>$nl$</code>.
975 *
976 * @return the string name of the current locale
977 * @since 3.0
978 */
979 public static String getNL() {
980 return InternalPlatform.getDefault().getNL();
981 }
982
983 /**
984 * Returns the string name of the current operating system for use in finding
985 * files whose path starts with <code>$os$</code>. <code>OS_UNKNOWN</code> is
986 * returned if the operating system cannot be determined.
987 * The value may indicate one of the operating systems known to the platform
988 * (as specified in <code>knownOSValues</code>) or a user-defined string if
989 * the operating system name is specified on the command line.
990 *
991 * @return the string name of the current operating system
992 * @since 3.0
993 */
994 public static String getOS() {
995 return InternalPlatform.getDefault().getOS();
996 }
997
998 /**
999 * Returns the string name of the current window system for use in finding files
1000 * whose path starts with <code>$ws$</code>. <code>null</code> is returned
1001 * if the window system cannot be determined.
1002 *
1003 * @return the string name of the current window system or <code>null</code>
1004 * @since 3.0
1005 */
1006 public static String getWS() {
1007 return InternalPlatform.getDefault().getWS();
1008 }
1009
1010 /**
1011 * Returns the arguments not consumed by the framework implementation itself. Which
1012 * arguments are consumed is implementation specific. These arguments are available
1013 * for use by the application.
1014 *
1015 * @return the array of command line arguments not consumed by the framework.
1016 * @since 3.0
1017 */
1018 public static String[] getApplicationArgs() {
1019 return InternalPlatform.getDefault().getApplicationArgs();
1020 }
1021
1022 /**
1023 * Returns the platform administrator for this running Eclipse.
1024 * <p>
1025 * <b>Note</b>: This is an early access API to the new OSGI-based Eclipse 3.0
1026 * Platform Runtime. Because the APIs for the new runtime have not yet been full
1027 * stabilized, they should only be used by clients needing to take particular
1028 * advantage of new OSGI-specific functionality, and only then with the understanding
1029 * that these APIs are likely to change in incompatible ways until they reach
1030 * their finished, stable form (post-3.0).
1031 * </p>
1032 * @return the platform admin for this instance of Eclipse
1033 */
1034 public static PlatformAdmin getPlatformAdmin() {
1035 return InternalPlatform.getDefault().getPlatformAdmin();
1036 }
1037
1038 /**
1039 * Returns the location of the platform's working directory (also known as the instance data area).
1040 * <code>null</code> is returned if the platform is running without an instance location.
1041 * <p>
1042 * This method is equivalent to acquiring the <code>org.eclipse.osgi.service.datalocation.Location</code>
1043 * service with the property "type" = "osgi.instance.area".
1044 *</p>
1045 * @return the location of the platform's instance data area or <code>null</code> if none
1046 * @since 3.0
1047 */
1048 public static Location getInstanceLocation() {
1049 return InternalPlatform.getDefault().getInstanceLocation();
1050 }
1051
1052 /**
1053 * Returns the currently registered bundle group providers
1054 * @return the currently registered bundle group providers
1055 * @since 3.0
1056 */
1057 public static IBundleGroupProvider[] getBundleGroupProviders() {
1058 return InternalPlatform.getDefault().getBundleGroupProviders();
1059 }
1060
1061 /**
1062 * Return the interface into the preference mechanism. The returned
1063 * object can be used for such operations as searching for preference
1064 * values across multiple scopes and preference import/export.
1065 *
1066 * @return an object to interface into the preference mechanism
1067 * @since 3.0
1068 */
1069 public static IPreferencesService getPreferencesService() {
1070 return InternalPlatform.getDefault().getPreferencesService();
1071 }
1072
1073 /**
1074 * Returns the product which was selected when running this Eclipse instance
1075 * or <code>null</code> if none
1076 * @return the current product or <code>null</code> if none
1077 * @since 3.0
1078 */
1079 public static IProduct getProduct() {
1080 return InternalPlatform.getDefault().getProduct();
1081 }
1082
1083 /**
1084 * Registers the given bundle group provider with the platform
1085 * @param provider a provider to register
1086 * @since 3.0
1087 */
1088 public static void registerBundleGroupProvider(IBundleGroupProvider provider) {
1089 InternalPlatform.getDefault().registerBundleGroupProvider(provider);
1090 }
1091
1092 /**
1093 * Deregisters the given bundle group provider with the platform
1094 * @param provider a provider to deregister
1095 * @since 3.0
1096 */
1097 public static void unregisterBundleGroupProvider(IBundleGroupProvider provider) {
1098 InternalPlatform.getDefault().unregisterBundleGroupProvider(provider);
1099 }
1100
1101 /**
1102 * Returns the location of the configuration information
1103 * used to run this instance of Eclipse. The configuration area typically
1104 * contains the list of plug-ins available for use, various setttings
1105 * (those shared across different instances of the same configuration)
1106 * and any other such data needed by plug-ins.
1107 * <code>null</code> is returned if the platform is running without a configuration location.
1108 * <p>
1109 * This method is equivalent to acquiring the <code>org.eclipse.osgi.service.datalocation.Location</code>
1110 * service with the property "type" = "osgi.configuration.area".
1111 *</p>
1112 * @return the location of the platform's configuration data area or <code>null</code> if none
1113 * @since 3.0
1114 */
1115 public static Location getConfigurationLocation() {
1116 return InternalPlatform.getDefault().getConfigurationLocation();
1117 }
1118
1119 /**
1120 * Returns the location of the platform's user data area. The user data area is a location on the system
1121 * which is specific to the system's current user. By default it is located relative to the
1122 * location given by the System property "user.home".
1123 * <code>null</code> is returned if the platform is running without an user location.
1124 * <p>
1125 * This method is equivalent to acquiring the <code>org.eclipse.osgi.service.datalocation.Location</code>
1126 * service with the property "type" = "osgi.user.area".
1127 *</p>
1128 * @return the location of the platform's user data area or <code>null</code> if none
1129 * @since 3.0
1130 */
1131 public static Location getUserLocation() {
1132 return InternalPlatform.getDefault().getConfigurationLocation();
1133 }
1134
1135 /**
1136 * Returns the location of the base installation for the running platform
1137 * <code>null</code> is returned if the platform is running without a configuration location.
1138 * <p>
1139 * This method is equivalent to acquiring the <code>org.eclipse.osgi.service.datalocation.Location</code>
1140 * service with the property "type" = "osgi.install.area".
1141 *</p>
1142 * @return the location of the platform's installation area or <code>null</code> if none
1143 * @since 3.0
1144 */
1145 public static Location getInstallLocation() {
1146 return InternalPlatform.getDefault().getInstallLocation();
1147 }
1148
1149 /**
1150 * Checks if the specified bundle is a fragment bundle.
1151 *
1152 * @param bundle the bundle to query
1153 * @return true if the specified bundle is a fragment bundle; otherwise false is returned.
1154 * @since 3.0
1155 */
1156 public static boolean isFragment(Bundle bundle) {
1157 return InternalPlatform.getDefault().isFragment(bundle);
1158 }
1159
1160 /**
1161 * Returns an array of attached fragment bundles for the specified bundle. If the
1162 * specified bundle is a fragment then <tt>null</tt> is returned. If no fragments are
1163 * attached to the specified bundle then <tt>null</tt> is returned.
1164 *
1165 * @param bundle the bundle to get the attached fragment bundles for.
1166 * @return an array of fragment bundles or <tt>null</tt> if the bundle does not
1167 * have any attached fragment bundles.
1168 * @since 3.0
1169 */
1170 public static Bundle[] getFragments(Bundle bundle) {
1171 return InternalPlatform.getDefault().getFragments(bundle);
1172 }
1173
1174 /**
1175 * Returns the resolved bundle with the specified symbolic name that has the
1176 * highest version. If no resolved bundles are installed that have the
1177 * specified symbolic name then null is returned.
1178 *
1179 * @param symbolicName the symbolic name of the bundle to be returned.
1180 * @return the bundle that has the specified symbolic name with the
1181 * highest version, or <tt>null</tt> if no bundle is found.
1182 * @since 3.0
1183 */
1184 public static Bundle getBundle(String symbolicName) {
1185 return InternalPlatform.getDefault().getBundle(symbolicName);
1186 }
1187
1188 /**
1189 * Returns all bundles with the specified symbolic name. If no resolved bundles
1190 * with the specified symbolic name can be found, <tt>null</tt> is returned.
1191 * If the version argument is not null then only the Bundles that have
1192 * the specified symbolic name and a version greater than or equal to the
1193 * specified version are returned. The returned bundles are ordered in
1194 * descending bundle version order.
1195 *
1196 * @param symbolicName the symbolic name of the bundles that are to be returned.
1197 * @param version the version that the return bundle versions must match,
1198 * or <tt>null</tt> if no version matching is to be done.
1199 * @return the array of Bundles with the specified name that match the
1200 * specified version and match rule, or <tt>null</tt> if no bundles are found.
1201 */
1202 public static Bundle[] getBundles(String symbolicName, String version) {
1203 return InternalPlatform.getDefault().getBundles(symbolicName, version);
1204 }
1205
1206 /**
1207 * Returns an array of host bundles that the specified fragment bundle is
1208 * attached to or <tt>null</tt> if the specified bundle is not attached to a host.
1209 * If the bundle is not a fragment bundle then <tt>null</tt> is returned.
1210 *
1211 * @param bundle the bundle to get the host bundles for.
1212 * @return an array of host bundles or null if the bundle does not have any
1213 * host bundles.
1214 * @since 3.0
1215 */
1216 public static Bundle[] getHosts(Bundle bundle) {
1217 return InternalPlatform.getDefault().getHosts(bundle);
1218 }
1219
1220 /**
1221 * Returns whether the platform is running.
1222 *
1223 * @return <code>true</code> if the platform is running,
1224 * and <code>false</code> otherwise
1225 *@since 3.0
1226 */
1227 public static boolean isRunning() {
1228 return InternalPlatform.getDefault().isRunning();
1229 }
1230
1231 /**
1232 * Returns a list of known system architectures.
1233 * <p>
1234 * Note that this list is not authoritative; there may be legal values
1235 * not included in this list. Indeed, the value returned by
1236 * <code>getOSArch</code> may not be in this list. Also, this list may
1237 * change over time as Eclipse comes to run on more operating environments.
1238 * </p>
1239 *
1240 * @return the list of system architectures known to the system
1241 * @see #getOSArch()
1242 * @since 3.0
1243 */
1244 public static String[] knownOSArchValues() {
1245 return InternalPlatform.getDefault().knownOSArchValues();
1246 }
1247
1248 /**
1249 * Returns a list of known operating system names.
1250 * <p>
1251 * Note that this list is not authoritative; there may be legal values
1252 * not included in this list. Indeed, the value returned by
1253 * <code>getOS</code> may not be in this list. Also, this list may
1254 * change over time as Eclipse comes to run on more operating environments.
1255 * </p>
1256 *
1257 * @return the list of operating systems known to the system
1258 * @see #getOS()
1259 * @since 3.0
1260 */
1261 public static String[] knownOSValues() {
1262 return InternalPlatform.getDefault().knownOSValues();
1263 }
1264
1265 /**
1266 * Returns a list of known windowing system names.
1267 * <p>
1268 * Note that this list is not authoritative; there may be legal values
1269 * not included in this list. Indeed, the value returned by
1270 * <code>getWS</code> may not be in this list. Also, this list may
1271 * change over time as Eclipse comes to run on more operating environments.
1272 * </p>
1273 *
1274 * @return the list of window systems known to the system
1275 * @see #getWS()
1276 * @since 3.0
1277 */
1278 public static String[] knownWSValues() {
1279 return InternalPlatform.getDefault().knownWSValues();
1280 }
1281
1282 /**
1283 * Returns <code>true</code> if the platform is currently running in
1284 * debug mode. The platform is typically put in debug mode using the
1285 * "-debug" command line argument.
1286 *
1287 * @return whether or not the platform is running in debug mode
1288 * @since 3.0
1289 */
1290 public static boolean inDebugMode() {
1291 return System.getProperty("osgi.debug") != null; //$NON-NLS-1$
1292 }
1293
1294 /**
1295 * Returns <code>true</code> if the platform is currently running in
1296 * development mode. That is, if special procedures are to be
1297 * taken when defining plug-in class paths. The platform is typically put in
1298 * development mode using the "-dev" command line argument.
1299 *
1300 * @return whether or not the platform is running in development mode
1301 * @since 3.0
1302 */
1303 public static boolean inDevelopmentMode() {
1304 return System.getProperty("osgi.dev") != null; //$NON-NLS-1$
1305 }
1306}