Platform


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-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.internal.runtime.auth.AuthorizationHandler;
19  import org.eclipse.core.runtime.content.IContentTypeManager;
20  import org.eclipse.core.runtime.jobs.IJobManager;
21  import org.eclipse.core.runtime.jobs.Job;
22  import org.eclipse.core.runtime.preferences.IPreferencesService;
23  import org.eclipse.osgi.service.datalocation.Location;
24  import org.eclipse.osgi.service.debug.DebugOptions;
25  import org.eclipse.osgi.service.environment.EnvironmentInfo;
26  import org.eclipse.osgi.service.resolver.PlatformAdmin;
27  import org.osgi.framework.Bundle;
28  import org.osgi.service.packageadmin.PackageAdmin;
29  
30  /**
31   * The central class of the Eclipse Platform Runtime. This class cannot
32   * be instantiated or subclassed by clients; all functionality is provided 
33   * by static methods.  Features include:
34   * <ul>
35   * <li>the platform registry of installed plug-ins</li>
36   * <li>the platform adapter manager</li>
37   * <li>the platform log</li>
38   * <li>the authorization info management</li>
39   * </ul>
40   * <p>
41   * Most users don't have to worry about Platform's lifecycle. However, if your 
42   * code can call methods of this class when Platform is not running, it becomes 
43   * necessary to check {@link #isRunning()} before making the call. A runtime 
44   * exception might be thrown or incorrect result might be returned if a method 
45   * from this class is called while Platform is not running.
46   * </p>
47   */
48  public final class Platform {
49  
50      /**
51       * The unique identifier constant (value "<code>org.eclipse.core.runtime</code>")
52       * of the Core Runtime (pseudo-) plug-in.
53       */
54      public static final String   PI_RUNTIME = "org.eclipse.core.runtime"; //$NON-NLS-1$
55  
56      /** 
57       * The simple identifier constant (value "<code>applications</code>") of
58       * the extension point of the Core Runtime plug-in where plug-ins declare
59       * the existence of runnable applications. A plug-in may define any
60       * number of applications; however, the platform is only capable
61       * of running one application at a time.
62       * 
63       */
64      public static final String   PT_APPLICATIONS = "applications"; //$NON-NLS-1$
65  
66      /** 
67       * The simple identifier constant (value "<code>adapters</code>") of
68       * the extension point of the Core Runtime plug-in where plug-ins declare
69       * the existence of adapter factories. A plug-in may define any
70       * number of adapters.
71       * 
72       * @see IAdapterManager#hasAdapter(Object, String)
73       * @since 3.0
74       */
75      public static final String   PT_ADAPTERS = "adapters"; //$NON-NLS-1$
76  
77      /** 
78       * The simple identifier constant (value "<code>preferences</code>") of
79       * the extension point of the Core Runtime plug-in where plug-ins declare
80       * extensions to the preference facility. A plug-in may define any number
81       * of preference extensions.
82       * 
83       * @see #getPreferencesService()
84       * @since 3.0
85       */
86      public static final String   PT_PREFERENCES = Preferences.PT_PREFERENCES;
87  
88      /** 
89       * The simple identifier constant (value "<code>products</code>") of
90       * the extension point of the Core Runtime plug-in where plug-ins declare
91       * the existence of a product. A plug-in may define any
92       * number of products; however, the platform is only capable
93       * of running one product at a time.
94       * 
95       * @see #getProduct()
96       * @since 3.0
97       */
98      public static final String   PT_PRODUCT = "products"; //$NON-NLS-1$
99  
100     /** 
101      * Debug option value denoting the time at which the platform runtime
102      * was started.  This constant can be used in conjunction with
103      * <code>getDebugOption</code> to find the string value of
104      * <code>System.currentTimeMillis()</code> when the platform was started.
105      */
106     public static final String   OPTION_STARTTIME = PI_RUNTIME + "/starttime"; //$NON-NLS-1$
107 
108     /**
109      * Name of a preference for configuring the performance level for this system.
110      *
111      * <p>
112      * This value can be used by all components to customize features to suit the 
113      * speed of the user's machine.  The platform job manager uses this value to make
114      * scheduling decisions about background jobs.
115      * </p>
116      * <p>
117      * The preference value must be an integer between the constant values
118      * MIN_PERFORMANCE and MAX_PERFORMANCE
119      * </p>
120      * @see #MIN_PERFORMANCE
121      * @see #MAX_PERFORMANCE
122      * @since 3.0
123      */
124     public static final String   PREF_PLATFORM_PERFORMANCE = "runtime.performance"; //$NON-NLS-1$
125 
126     /**
127      * Constant (value "line.separator") name of the preference used for storing 
128      * the line separator. 
129      * 
130      * @see #knownPlatformLineSeparators
131      * @since 3.1
132      */
133     public static final String   PREF_LINE_SEPARATOR = "line.separator"; //$NON-NLS-1$
134 
135     /** 
136      * Constant (value 1) indicating the minimum allowed value for the 
137      * <code>PREF_PLATFORM_PERFORMANCE</code> preference setting.
138      * @since 3.0
139      */
140     public static final int MIN_PERFORMANCE = 1;
141 
142     /** 
143      * Constant (value 5) indicating the maximum allowed value for the 
144      * <code>PREF_PLATFORM_PERFORMANCE</code> preference setting.
145      * @since 3.0
146      */
147     public static final int MAX_PERFORMANCE = 5;
148 
149     /** 
150      * Status code constant (value 1) indicating a problem in a plug-in
151      * manifest (<code>plugin.xml</code>) file.
152      */
153     public static final int PARSE_PROBLEM = 1;
154 
155     /**
156      * Status code constant (value 2) indicating an error occurred while running a plug-in.
157      */
158     public static final int PLUGIN_ERROR = 2;
159 
160     /**
161      * Status code constant (value 3) indicating an error internal to the
162      * platform has occurred.
163      */
164     public static final int INTERNAL_ERROR = 3;
165 
166     /**
167      * Status code constant (value 4) indicating the platform could not read
168      * some of its metadata.
169      */
170     public static final int FAILED_READ_METADATA = 4;
171 
172     /**
173      * Status code constant (value 5) indicating the platform could not write
174      * some of its metadata.
175      */
176     public static final int FAILED_WRITE_METADATA = 5;
177 
178     /**
179      * Status code constant (value 6) indicating the platform could not delete
180      * some of its metadata.
181      */
182     public static final int FAILED_DELETE_METADATA = 6;
183 
184     /**
185      * Constant string (value "win32") indicating the platform is running on a
186      * Window 32-bit operating system (e.g., Windows 98, NT, 2000).
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_WIN32 = "win32";//$NON-NLS-1$
194 
195     /**
196      * Constant string (value "linux") indicating the platform is running on a
197      * Linux-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_LINUX = "linux";//$NON-NLS-1$
205 
206     /**
207      * Constant string (value "aix") indicating the platform is running on an
208      * AIX-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_AIX = "aix";//$NON-NLS-1$
216 
217     /**
218      * Constant string (value "solaris") indicating the platform is running on a
219      * Solaris-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_SOLARIS = "solaris";//$NON-NLS-1$
227 
228     /**
229      * Constant string (value "hpux") indicating the platform is running on an
230      * HP/UX-based 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_HPUX = "hpux";//$NON-NLS-1$
238 
239     /**
240      * Constant string (value "qnx") indicating the platform is running on a
241      * QNX-based 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_QNX = "qnx";//$NON-NLS-1$
249 
250     /**
251      * Constant string (value "macosx") indicating the platform is running on a
252      * Mac OS X operating system.
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   OS_MACOSX = "macosx";//$NON-NLS-1$
260 
261     /**
262      * Constant string (value "unknown") indicating the platform is running on a
263      * machine running an unknown operating system.
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   OS_UNKNOWN = "unknown";//$NON-NLS-1$
271 
272     /**
273      * Constant string (value "x86") indicating the platform is running on an
274      * x86-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_X86 = "x86";//$NON-NLS-1$
282 
283     /**
284      * Constant string (value "PA_RISC") indicating the platform is running on an
285      * PA_RISC-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_PA_RISC = "PA_RISC";//$NON-NLS-1$
293 
294     /**
295      * Constant string (value "ppc") indicating the platform is running on an
296      * PowerPC-based architecture.
297      * <p>
298      * Note this constant has been moved from the deprecated 
299      * org.eclipse.core.boot.BootLoader class and its value has not changed.
300      * </p>
301      * @since 3.0
302      */
303     public static final String   ARCH_PPC = "ppc";//$NON-NLS-1$
304 
305     /**
306      * Constant string (value "sparc") indicating the platform is running on an
307      * Sparc-based architecture.
308      * <p>
309      * Note this constant has been moved from the deprecated 
310      * org.eclipse.core.boot.BootLoader class and its value has not changed.
311      * </p>
312      * @since 3.0
313      */
314     public static final String   ARCH_SPARC = "sparc";//$NON-NLS-1$
315 
316     /**
317      * Constant string (value "x86_64") indicating the platform is running on an
318      * x86 64bit-based architecture.
319      * 
320      * @since 3.1
321      */
322     public static final String   ARCH_X86_64 = "x86_64";//$NON-NLS-1$
323 
324     /**
325      * Constant string (value "amd64") indicating the platform is running on an
326      * AMD64-based architecture.
327      * 
328      * @since 3.0
329      * @deprecated use <code>ARCH_X86_64</code> instead. Note the values
330      * has been changed to be the value of the <code>ARCH_X86_64</code> constant.
331      */
332     public static final String   ARCH_AMD64 = ARCH_X86_64;
333 
334     /**
335      * Constant string (value "ia64") indicating the platform is running on an
336      * IA64-based architecture.
337      * 
338      * @since 3.0
339      */
340     public static final String   ARCH_IA64 = "ia64"; //$NON-NLS-1$
341 
342     /**
343      * Constant string (value "ia64_32") indicating the platform is running on an
344      * IA64 32bit-based architecture.
345      * 
346      * @since 3.1
347      */
348     public static final String   ARCH_IA64_32 = "ia64_32";//$NON-NLS-1$
349 
350     /**
351      * Constant string (value "win32") indicating the platform is running on a
352      * machine using the Windows windowing system.
353      * <p>
354      * Note this constant has been moved from the deprecated 
355      * org.eclipse.core.boot.BootLoader class and its value has not changed.
356      * </p>
357      * @since 3.0
358      */
359     public static final String   WS_WIN32 = "win32";//$NON-NLS-1$
360 
361     /**
362      * Constant string (value "motif") indicating the platform is running on a
363      * machine using the Motif windowing system.
364      * <p>
365      * Note this constant has been moved from the deprecated 
366      * org.eclipse.core.boot.BootLoader class and its value has not changed.
367      * </p>
368      * @since 3.0
369      */
370     public static final String   WS_MOTIF = "motif";//$NON-NLS-1$
371 
372     /**
373      * Constant string (value "gtk") indicating the platform is running on a
374      * machine using the GTK windowing system.
375      * <p>
376      * Note this constant has been moved from the deprecated 
377      * org.eclipse.core.boot.BootLoader class and its value has not changed.
378      * </p>
379      * @since 3.0
380      */
381     public static final String   WS_GTK = "gtk";//$NON-NLS-1$
382 
383     /**
384      * Constant string (value "photon") indicating the platform is running on a
385      * machine using the Photon windowing system.
386      * <p>
387      * Note this constant has been moved from the deprecated 
388      * org.eclipse.core.boot.BootLoader class and its value has not changed.
389      * </p>
390      * @since 3.0
391      */
392     public static final String   WS_PHOTON = "photon";//$NON-NLS-1$
393 
394     /**
395      * Constant string (value "carbon") indicating the platform is running on a
396      * machine using the Carbon windowing system (Mac OS X).
397      * <p>
398      * Note this constant has been moved from the deprecated 
399      * org.eclipse.core.boot.BootLoader class and its value has not changed.
400      * </p>
401      * @since 3.0
402      */
403     public static final String   WS_CARBON = "carbon";//$NON-NLS-1$
404 
405     /**
406      * Constant string (value "wpf") indicating the platform is running on a
407      * machine using the WPF windowing system.
408      * @since 3.3
409      */
410     public static final String   WS_WPF = "wpf";//$NON-NLS-1$
411 
412     /**
413      * Constant string (value "unknown") indicating the platform is running on a
414      * machine running an unknown windowing system.
415      * <p>
416      * Note this constant has been moved from the deprecated 
417      * org.eclipse.core.boot.BootLoader class and its value has not changed.
418      * </p>
419      * @since 3.0
420      */
421     public static final String   WS_UNKNOWN = "unknown";//$NON-NLS-1$
422 
423     // private constants for platform line separators and their associated platform names
424     private static final String   LINE_SEPARATOR_KEY_MAC_OS_9 = Messages.line_separator_platform_mac_os_9;
425     private static final String   LINE_SEPARATOR_KEY_UNIX = Messages.line_separator_platform_unix;
426     private static final String   LINE_SEPARATOR_KEY_WINDOWS = Messages.line_separator_platform_windows;
427 
428     private static final String   LINE_SEPARATOR_VALUE_CR = "\r"; //$NON-NLS-1$
429     private static final String   LINE_SEPARATOR_VALUE_LF = "\n"; //$NON-NLS-1$
430     private static final String   LINE_SEPARATOR_VALUE_CRLF = "\r\n"; //$NON-NLS-1$
431 
432     /**
433      * Private constructor to block instance creation.
434      */
435     private Platform() {
436         super();
437     }
438 
439     /**
440      * Adds the given authorization information to the key ring. The
441      * information is relevant for the specified protection space and the
442      * given authorization scheme. The protection space is defined by the
443      * combination of the given server URL and realm. The authorization 
444      * scheme determines what the authorization information contains and how 
445      * it should be used. The authorization information is a <code>Map</code> 
446      * of <code>String</code> to <code>String</code> and typically
447      * contains information such as user names and passwords.
448      *
449      * @param serverUrl the URL identifying the server for this authorization
450      *      information. For example, "http://www.example.com/".
451      * @param realm the subsection of the given server to which this
452      *      authorization information applies.  For example,
453      *      "realm1@example.com" or "" for no realm.
454      * @param authScheme the scheme for which this authorization information
455      *      applies. For example, "Basic" or "" for no authorization scheme
456      * @param info a <code>Map</code> containing authorization information 
457      *      such as user names and passwords (key type : <code>String</code>, 
458      *      value type : <code>String</code>)
459      * @exception CoreException if there are problems setting the
460      *      authorization information. Reasons include:
461      * <ul>
462      * <li>The keyring could not be saved.</li>
463      * </ul>
464      */
465     public static void addAuthorizationInfo(URL   serverUrl, String   realm, String   authScheme, Map info) throws CoreException {
466         try {
467             AuthorizationHandler.addAuthorizationInfo(serverUrl, realm, authScheme, info);
468         } catch (NoClassDefFoundError   e) {
469             // The authorization code is not available so just log and continue
470             logAuthNotAvailable(e);
471         }
472     }
473 
474     /** 
475      * Adds the given log listener to the notification list of the platform.
476      * <p>
477      * Once registered, a listener starts receiving notification as entries
478      * are added to plug-in logs via <code>ILog.log()</code>. The listener continues to
479      * receive notifications until it is replaced or removed.
480      * </p>
481      *
482      * @param listener the listener to register
483      * @see ILog#addLogListener(ILogListener)
484      * @see #removeLogListener(ILogListener)
485      * XXX Use the LogMgr service.
486      */
487     public static void addLogListener(ILogListener listener) {
488         InternalPlatform.getDefault().addLogListener(listener);
489     }
490 
491     /**
492      * Adds the specified resource to the protection space specified by the
493      * given realm. All targets at or deeper than the depth of the last
494      * symbolic element in the path of the given resource URL are assumed to
495      * be in the same protection space.
496      *
497      * @param resourceUrl the URL identifying the resources to be added to
498      *      the specified protection space. For example,
499      *      "http://www.example.com/folder/".
500      * @param realm the name of the protection space. For example,
501      *      "realm1@example.com"
502      * @exception CoreException if there are problems setting the
503      *      authorization information. Reasons include:
504      * <ul>
505      * <li>The key ring could not be saved.</li>
506      * </ul>
507      */
508     public static void addProtectionSpace(URL   resourceUrl, String   realm) throws CoreException {
509         try {
510             AuthorizationHandler.addProtectionSpace(resourceUrl, realm);
511         } catch (NoClassDefFoundError   e) {
512             // The authorization code is not available so just log and continue
513             logAuthNotAvailable(e);
514         }
515     }
516 
517     /**
518      * Returns a URL that is the local equivalent of the
519      * supplied URL. This method is expected to be used with the
520      * plug-in-relative URLs returned by IPluginDescriptor, Bundle.getEntry()
521      * and Platform.find().
522      * If the specified URL is not a plug-in-relative URL, it 
523      * is returned as is. If the specified URL is a plug-in-relative
524      * URL of a file (including .jar archive), it is returned as 
525      * a locally accessible URL using "file:" protocol
526      * (extracting/caching the file locally, if required). If the specified URL
527      * is a plug-in-relative URL of a directory, the directory and any files and directories
528      * under it are made locally accessible likewise. 
529      *
530      * @param url original plug-in-relative URL.
531      * @return the resolved URL
532      * @exception IOException if unable to resolve URL
533      * @see #resolve(URL)
534      * @see #find(Bundle, IPath)
535      * @see Bundle#getEntry(String)
536      * @deprecated use {@link FileLocator#toFileURL(URL)} instead
537      */
538     public static URL   asLocalURL(URL   url) throws IOException   {
539         return FileLocator.toFileURL(url);
540     }
541 
542     /**
543      * Takes down the splash screen if one was put up.
544      * XXX this is application life cycle. Need to have the appropriate method on IApplication.
545      */
546     public static void endSplash() {
547         InternalPlatform.getDefault().endSplash();
548     }
549 
550     /**
551      * Removes the authorization information for the specified protection
552      * space and given authorization scheme. The protection space is defined
553      * by the given server URL and realm.
554      *
555      * @param serverUrl the URL identifying the server to remove the
556      *      authorization information for. For example,
557      *      "http://www.example.com/".
558      * @param realm the subsection of the given server to remove the
559      *      authorization information for. For example,
560      *      "realm1@example.com" or "" for no realm.
561      * @param authScheme the scheme for which the authorization information
562      *      to remove applies. For example, "Basic" or "" for no
563      *      authorization scheme.
564      * @exception CoreException if there are problems removing the
565      *      authorization information. Reasons include:
566      * <ul>
567      * <li>The keyring could not be saved.</li>
568      * </ul>
569      */
570     public static void flushAuthorizationInfo(URL   serverUrl, String   realm, String   authScheme) throws CoreException {
571         try {
572             AuthorizationHandler.flushAuthorizationInfo(serverUrl, realm, authScheme);
573         } catch (NoClassDefFoundError   e) {
574             // The authorization code is not available so just log and continue
575             logAuthNotAvailable(e);
576         }
577     }
578 
579     private static void logAuthNotAvailable(Throwable   e) {
580         InternalPlatform.getDefault().log(new Status(IStatus.WARNING, Platform.PI_RUNTIME, 0, Messages.auth_notAvailable, e));
581     }
582 
583     /**
584      * Returns the adapter manager used for extending
585      * <code>IAdaptable</code> objects.
586      *
587      * @return the adapter manager for this platform
588      * @see IAdapterManager
589      * XXX register as a service (same pattern than Jobs)
590      * Do we want to make it available as a singleton?
591      */
592     public static IAdapterManager getAdapterManager() {
593         return InternalPlatform.getDefault().getAdapterManager();
594     }
595 
596     /**
597      * Returns the authorization information for the specified protection
598      * space and given authorization scheme. The protection space is defined
599      * by the given server URL and realm. Returns <code>null</code> if no
600      * such information exists.
601      *
602      * @param serverUrl the URL identifying the server for the authorization
603      *      information. For example, "http://www.example.com/".
604      * @param realm the subsection of the given server to which the
605      *      authorization information applies.  For example,
606      *      "realm1@example.com" or "" for no realm.
607      * @param authScheme the scheme for which the authorization information
608      *      applies. For example, "Basic" or "" for no authorization scheme
609      * @return the authorization information for the specified protection
610      *      space and given authorization scheme, or <code>null</code> if no
611      *      such information exists
612      */
613     public static Map getAuthorizationInfo(URL   serverUrl, String   realm, String   authScheme) {
614         try {
615             return AuthorizationHandler.getAuthorizationInfo(serverUrl, realm, authScheme);
616         } catch (NoClassDefFoundError   e) {
617             // The authorization code is not available so just log and continue
618             logAuthNotAvailable(e);
619         }
620         return null;
621     }
622 
623     /**
624      * Returns the command line args provided to the Eclipse runtime layer when it was first run.
625      * The returned value does not include arguments consumed by the lower levels of Eclipse
626      * (e.g., OSGi or the launcher).
627      * Note that individual platform runnables may be provided with different arguments
628      * if they are being run individually rather than with <code>Platform.run()</code>.
629      * <p>
630      * Clients are also able to acquire the {@link EnvironmentInfo} service and query it for
631      * the command-line arguments.
632      * </p>
633      * @return the command line used to start the platform
634      */
635     public static String  [] getCommandLineArgs() {
636         return InternalPlatform.getDefault().getCommandLineArgs();
637     }
638 
639     /**
640      * Returns the content type manager.
641      * <p>
642      * Clients are also able to acquire the {@link IContentTypeManager} service.
643      * </p>
644      * @return the content type manager
645      * @since 3.0
646      */
647     public static IContentTypeManager getContentTypeManager() {
648         return InternalPlatform.getDefault().getContentTypeManager();
649     }
650 
651     /**
652      * Returns the identified option.  <code>null</code>
653      * is returned if no such option is found.   Options are specified
654      * in the general form <i>&lt;plug-in id&gt;/&lt;option-path&gt;</i>.  
655      * For example, <code>org.eclipse.core.runtime/debug</code>
656      * <p>
657      * Clients are also able to acquire the {@link DebugOptions} service
658      * and query it for debug options.
659      * </p>
660      * @param option the name of the option to lookup
661      * @return the value of the requested debug option or <code>null</code>
662      */
663     public static String   getDebugOption(String   option) {
664         return InternalPlatform.getDefault().getOption(option);
665     }
666 
667     /**
668      * Returns the location of the platform working directory.  
669      * <p>
670      * Callers of this method should consider using <code>getInstanceLocation</code>
671      * instead.  In various, typically non IDE-related configurations of Eclipse, the platform
672      * working directory may not be on the local file system.  As such, the more general
673      * form of this location is as a URL.
674      * </p><p>
675      * Alternatively, instead of calling <code>getInstanceLocation</code> clients are 
676      * able to acquire the {@link Location} service (with the type {@link Location#INSTANCE_FILTER})
677      * and then change the resulting URL to a path. See the javadoc for <code>getInstanceLocation</code>
678      * for more details.
679      * </p>
680      * @return the location of the platform
681      * @see #getInstanceLocation()
682      */
683     public static IPath getLocation() throws IllegalStateException   {
684         return InternalPlatform.getDefault().getLocation();
685     }
686 
687     /**
688      * Returns the location of the platform log file.  This file may contain information
689      * about errors that have previously occurred during this invocation of the Platform.
690      * <p>
691      * It is recommended not to keep this value, as the log location may vary when an instance
692      * location is being set.</p>
693      * <p>
694      * Note: it is very important that users of this method do not leave the log
695      * file open for extended periods of time.  Doing so may prevent others
696      * from writing to the log file, which could result in important error messages
697      * being lost.  It is strongly recommended that clients wanting to read the
698      * log file for extended periods should copy the log file contents elsewhere,
699      * and immediately close the original file.</p>
700      * @return the path of the log file on disk.
701      * 
702      * XXX  consider making an ILogger interface that listeners can implements and it allows 
703      * us to implement Platform.getLogLocation()
704      */
705     public static IPath getLogFileLocation() {
706         return InternalPlatform.getDefault().getMetaArea().getLogLocation();
707     }
708 
709     /**
710      * Returns the plug-in runtime object for the identified plug-in
711      * or <code>null</code> if no such plug-in can be found.  If
712      * the plug-in is defined but not yet activated, the plug-in will
713      * be activated before being returned.
714      * <p>
715      * <b>Note</b>: This method is only able to find and return plug-in
716      * objects for plug-ins described using plugin.xml according to the 
717      * traditional Eclipse conventions.  Eclipse 3.0 permits plug-ins to be
718      * described in manifest.mf files and to define their own bundle 
719      * activators.  Such plug-ins cannot be discovered by this method.</p>
720      *
721      * @param id the unique identifier of the desired plug-in 
722      *      (e.g., <code>"com.example.acme"</code>).
723      * @return the plug-in runtime object, or <code>null</code>
724      * @deprecated 
725      * This method only works if the compatibility layer is installed and must not be used otherwise.
726      * See the comments on {@link IPluginDescriptor#getPlugin()} for details.
727      */
728     public static Plugin getPlugin(String   id) {
729         try {
730             IPluginRegistry registry = getPluginRegistry();
731             if (registry == null)
732                 throw new IllegalStateException  ();
733             IPluginDescriptor pd = registry.getPluginDescriptor(id);
734             if (pd == null)
735                 return null;
736             return pd.getPlugin();
737         } catch (CoreException e) {
738             // TODO log the exception
739         }
740         return null;
741     }
742 
743     /**
744      * Returns the plug-in registry for this platform.
745      *
746      * @return the plug-in registry
747      * @see IPluginRegistry
748      * @deprecated <code>IPluginRegistry</code> was refactored in Eclipse 3.0.
749      * This method only works if the compatibility layer is installed and must not be used otherwise.
750      * See the comments on {@link IPluginRegistry} and its methods for details.
751      */
752     public static IPluginRegistry getPluginRegistry() {
753         Bundle compatibility = InternalPlatform.getDefault().getBundle(CompatibilityHelper.PI_RUNTIME_COMPATIBILITY);
754         if (compatibility == null)
755             throw new IllegalStateException  ();
756 
757         Class   oldInternalPlatform = null;
758         try {
759             oldInternalPlatform = compatibility.loadClass("org.eclipse.core.internal.plugins.InternalPlatform"); //$NON-NLS-1$
760             Method   getPluginRegistry = oldInternalPlatform.getMethod("getPluginRegistry", null); //$NON-NLS-1$
761             return (IPluginRegistry) getPluginRegistry.invoke(oldInternalPlatform, null);
762         } catch (Exception   e) {
763             //Ignore the exceptions, return null
764         }
765         return null;
766 
767     }
768 
769     /**
770      * Returns the location in the local file system of the plug-in 
771      * state area for the given plug-in.
772      * The platform must be running.
773      * <p>
774      * The plug-in state area is a file directory within the
775      * platform's metadata area where a plug-in is free to create files.
776      * The content and structure of this area is defined by the plug-in,
777      * and the particular plug-in is solely responsible for any files
778      * it puts there. It is recommended for plug-in preference settings.
779      * </p>
780      *
781      * @param plugin the plug-in whose state location is returned
782      * @return a local file system path
783      * @deprecated clients should call <code>getStateLocation</code> instead
784      */
785     public static IPath getPluginStateLocation(Plugin plugin) {
786         return plugin.getStateLocation();
787     }
788 
789     /**
790      * Returns the protection space (realm) for the specified resource, or
791      * <code>null</code> if the realm is unknown.
792      *
793      * @param resourceUrl the URL of the resource whose protection space is
794      *      returned. For example, "http://www.example.com/folder/".
795      * @return the protection space (realm) for the specified resource, or
796      *      <code>null</code> if the realm is unknown
797      */
798     public static String   getProtectionSpace(URL   resourceUrl) {
799         try {
800             return AuthorizationHandler.getProtectionSpace(resourceUrl);
801         } catch (NoClassDefFoundError   e) {
802             // The authorization code is not available so just log and continue
803             logAuthNotAvailable(e);
804         }
805         return null;
806     }
807 
808     /** 
809      * Removes the indicated (identical) log listener from the notification list
810      * of the platform.  If no such listener exists, no action is taken.
811      *
812      * @param listener the listener to de-register
813      * @see ILog#removeLogListener(ILogListener)
814      * @see #addLogListener(ILogListener)
815      * XXX Use the LogMgr service.
816      */
817     public static void removeLogListener(ILogListener listener) {
818         InternalPlatform.getDefault().removeLogListener(listener);
819     }
820 
821     /**
822      * Returns a URL which is the resolved equivalent of the
823      * supplied URL. This method is expected to be used with the
824      * plug-in-relative URLs returned by IPluginDescriptor, Bundle.getEntry()
825      * and Platform.find().
826      * <p>
827      * If the specified URL is not a plug-in-relative URL, it is returned
828      * as is. If the specified URL is a plug-in-relative URL, this method
829      * attempts to reduce the given URL to one which is native to the Java
830      * class library (eg. file, http, etc). 
831      * </p><p>
832      * Note however that users of this API should not assume too much about the
833      * results of this method.  While it may consistently return a file: URL in certain
834      * installation configurations, others may result in jar: or http: URLs.
835      * </p>
836      * @param url original plug-in-relative URL.
837      * @return the resolved URL
838      * @exception IOException if unable to resolve URL
839      * @see #asLocalURL(URL)
840      * @see #find(Bundle, IPath)
841      * @see Bundle#getEntry(String)
842      * @deprecated use {@link FileLocator#resolve(URL)} instead
843      */
844     public static URL   resolve(URL   url) throws IOException   {
845         return FileLocator.resolve(url);
846     }
847 
848     /**
849      * Runs the given runnable in a protected mode.   Exceptions
850      * thrown in the runnable are logged and passed to the runnable's
851      * exception handler.  Such exceptions are not rethrown by this method.
852      *
853      * @param runnable the runnable to run
854      * @deprecated clients should use <code>SafeRunner#run</code> instead
855      */
856     public static void run(ISafeRunnable runnable) {
857         SafeRunner.run(runnable);
858     }
859 
860     /**
861      * Returns the platform job manager.
862      * 
863      * @return the platform's job manager
864      * @since 3.0
865      * @deprecated The method {@link Job#getJobManager()} should be used instead.
866      */
867     public static IJobManager getJobManager() {
868         return Job.getJobManager();
869     }
870 
871     /**
872      * Returns the extension registry for this platform.
873      *
874      * @return the extension registry
875      * @see IExtensionRegistry
876      * @since 3.0
877      */
878     public static IExtensionRegistry getExtensionRegistry() {
879         return InternalPlatform.getDefault().getRegistry();
880     }
881 
882     /**
883      * Returns a URL for the given path in the given bundle.  Returns <code>null</code> if the URL
884      * could not be computed or created.
885      * 
886      * @param bundle the bundle in which to search
887      * @param path path relative to plug-in installation location 
888      * @return a URL for the given path or <code>null</code>.  The actual form
889      * of the returned URL is not specified.
890      * @see #find(Bundle, IPath, Map)
891      * @see #resolve(URL)
892      * @see #asLocalURL(URL)
893      * @since 3.0
894      * @deprecated use {@link FileLocator#find(Bundle, IPath, Map)}
895      */
896     public static URL   find(Bundle bundle, IPath path) {
897         return FileLocator.find(bundle, path, null);
898     }
899 
900     /**
901      * Returns a URL for the given path in the given bundle.  Returns <code>null</code> if the URL
902      * could not be computed or created.
903      * <p>
904      * find looks for this path in given bundle and any attached fragments.  
905      * <code>null</code> is returned if no such entry is found.  Note that
906      * there is no specific order to the fragments.
907      * </p><p>
908      * The following arguments may also be used
909      * <pre>
910      *     $nl$ - for language specific information
911      *     $os$ - for operating system specific information
912      *     $ws$ - for windowing system specific information
913      * </pre>
914      * </p><p>
915      * A path of $nl$/about.properties in an environment with a default 
916      * locale of en_CA will return a URL corresponding to the first place
917      * about.properties is found according to the following order:
918      * <pre>
919      *     plugin root/nl/en/CA/about.properties
920      *     fragment1 root/nl/en/CA/about.properties
921      *     fragment2 root/nl/en/CA/about.properties
922      *     ...
923      *     plugin root/nl/en/about.properties
924      *     fragment1 root/nl/en/about.properties
925      *     fragment2 root/nl/en/about.properties
926      *     ...
927      *     plugin root/about.properties
928      *     fragment1 root/about.properties
929      *     fragment2 root/about.properties
930      *     ...
931      * </pre>
932      * </p><p>
933      * The current environment variable values can be overridden using 
934      * the override map argument.
935      * </p>
936      * 
937      * @param bundle the bundle in which to search
938      * @param path file path relative to plug-in installation location
939      * @param override map of override substitution arguments to be used for
940      * any $arg$ path elements. The map keys correspond to the substitution
941      * arguments (eg. "$nl$" or "$os$"). The resulting
942      * values must be of type java.lang.String. If the map is <code>null</code>,
943      * or does not contain the required substitution argument, the default
944      * is used.
945      * @return a URL for the given path or <code>null</code>.  The actual form
946      * of the returned URL is not specified.
947      * @see #resolve(URL)
948      * @see #asLocalURL(URL)
949      * @since 3.0
950      * @deprecated use {@link FileLocator#find(Bundle, IPath, Map)} instead
951      */
952     public static URL   find(Bundle bundle, IPath path, Map override) {
953         return FileLocator.find(bundle, path, override);
954     }
955 
956     /**
957      * Returns the location in the local file system of the 
958      * plug-in state area for the given bundle.
959      * If the plug-in state area did not exist prior to this call,
960      * it is created.
961      * <p>
962      * The plug-in state area is a file directory within the
963      * platform's metadata area where a plug-in is free to create files.
964      * The content and structure of this area is defined by the plug-in,
965      * and the particular plug-in is solely responsible for any files
966      * it puts there. It is recommended for plug-in preference settings and 
967      * other configuration parameters.
968      * </p>
969      *
970      * @param bundle the bundle whose state location if returned
971      * @return a local file system path
972      * @since 3.0
973      * XXX Investigate the usage of a service factory
974      */
975     public static IPath getStateLocation(Bundle bundle) {
976         return InternalPlatform.getDefault().getStateLocation(bundle);
977     }
978 
979     /**
980      * Returns a number that changes whenever the set of installed plug-ins
981      * changes. This can be used for invalidating caches that are based on 
982      * the set of currently installed plug-ins. (e.g. extensions)
983      * <p>
984      * Clients are also able to acquire the {@link PlatformAdmin} service
985      * and get the timestamp from its state object.
986      * </p>
987      * @return a number related to the set of installed plug-ins
988      * @since 3.1
989      */
990     public static long getStateStamp() {
991         return InternalPlatform.getDefault().getStateTimeStamp();
992     }
993 
994     /**
995      * Returns the log for the given bundle.  If no such log exists, one is created.
996      *
997      * @param bundle the bundle whose log is returned
998      * @return the log for the given bundle
999      * @since 3.0
1000     * XXX change this into a LogMgr service that would keep track of the map. See if it can be a service factory.
1001     * It would contain all the methods that are here.
1002     * Relate to RuntimeLog if appropriate.
1003     * The system log listener needs to be optional: turned on or off. What about a system property? :-)
1004     */
1005    public static ILog getLog(Bundle bundle) {
1006        return InternalPlatform.getDefault().getLog(bundle);
1007    }
1008
1009    /**
1010     * Returns the given bundle's resource bundle for the current locale. 
1011     * <p>
1012     * This resource bundle is typically stored as the plugin.properties file 
1013     * in the plug-in itself, and contains any translatable strings used in the 
1014     * plug-in manifest file (plugin.xml).
1015     * </p>
1016     * <p>
1017     *  This mechanism is intended only for 
1018     * externalizing strings found in the plug-in manifest file. Using this 
1019     * method for externalizing strings in your code may result in degraded 
1020     * memory performance.
1021     * </p>
1022     *
1023     * @param bundle the bundle whose resource bundle is being queried
1024     * @return the resource bundle
1025     * @exception MissingResourceException if the resource bundle was not found
1026     * @since 3.0
1027     * XXX this is deprecated. use NLS or BundleFinder.find()
1028     */
1029    public static ResourceBundle getResourceBundle(Bundle bundle) throws MissingResourceException {
1030        return InternalPlatform.getDefault().getResourceBundle(bundle);
1031    }
1032
1033    /**
1034     * Returns a resource string corresponding to the given argument value.
1035     * If the argument value specifies a resource key, the string
1036     * is looked up in the default resource bundle for the given runtime bundle. If the argument does not
1037     * specify a valid key, the argument itself is returned as the
1038     * resource string. The key lookup is performed in the
1039     * file referenced in the Bundle-Localization header of the bundle manifest. If a resource string 
1040     * corresponding to the key is not found in the resource bundle
1041     * the key value, or any default text following the key in the
1042     * argument value is returned as the resource string.
1043     * A key is identified as a string beginning with the "%" character.
1044     * Note, that the "%" character is stripped off prior to lookup
1045     * in the resource bundle.
1046     * <p>
1047     * Equivalent to <code>getResourceString(bundle, value, getResourceBundle())</code>
1048     * </p>
1049     *
1050     * @param bundle the bundle whose resource bundle is being queried
1051     * @param value the value to look for
1052     * @return the resource string
1053     * @see #getResourceBundle(Bundle)
1054     * @since 3.0
1055     * XXX this is deprecated. use NLS or  BundleFinder.find()
1056     */
1057    public static String   getResourceString(Bundle bundle, String   value) {
1058        return InternalPlatform.getDefault().getResourceString(bundle, value);
1059    }
1060
1061    /**
1062     * Returns a resource string corresponding to the given argument 
1063     * value and resource bundle in the given runtime bundle.
1064     * If the argument value specifies a resource key, the string
1065     * is looked up in the given resource bundle. If the argument does not
1066     * specify a valid key, the argument itself is returned as the
1067     * resource string. The key lookup is performed against the
1068     * specified resource bundle. If a resource string 
1069     * corresponding to the key is not found in the resource bundle
1070     * the key value, or any default text following the key in the
1071     * argument value is returned as the resource string.
1072     * A key is identified as a string beginning with the "%" character.
1073     * Note that the "%" character is stripped off prior to lookup
1074     * in the resource bundle.
1075     * <p>
1076     * For example, assume resource bundle plugin.properties contains
1077     * name = Project Name
1078     * <pre>
1079     *     getResourceString("Hello World") returns "Hello World"</li>
1080     *     getResourceString("%name") returns "Project Name"</li>
1081     *     getResourceString("%name Hello World") returns "Project Name"</li>
1082     *     getResourceString("%abcd Hello World") returns "Hello World"</li>
1083     *     getResourceString("%abcd") returns "%abcd"</li>
1084     *     getResourceString("%%name") returns "%name"</li>
1085     * </pre>
1086     * </p>
1087     *
1088     * @param bundle the bundle whose resource bundle is being queried
1089     * @param value the value
1090     * @param resourceBundle the resource bundle to query
1091     * @return the resource string
1092     * @see #getResourceBundle(Bundle)
1093     * @since 3.0
1094     * XXX this is deprecated. use NLS or  BundleFinder.find()
1095     */
1096    public static String   getResourceString(Bundle bundle, String   value, ResourceBundle resourceBundle) {
1097        return InternalPlatform.getDefault().getResourceString(bundle, value, resourceBundle);
1098    }
1099
1100    /**
1101     * Returns the string name of the current system architecture.  
1102     * The value is a user-defined string if the architecture is 
1103     * specified on the command line, otherwise it is the value 
1104     * returned by <code>java.lang.System.getProperty("os.arch")</code>.
1105     * <p>
1106     * Clients are also able to acquire the {@link EnvironmentInfo} service and query it for
1107     * the operating-system architecture.
1108     * </p>
1109     * @return the string name of the current system architecture
1110     * @since 3.0
1111     */
1112    public static String   getOSArch() {
1113        return InternalPlatform.getDefault().getOSArch();
1114    }
1115
1116    /**
1117     * Returns the string name of the current locale for use in finding files
1118     * whose path starts with <code>$nl$</code>.
1119     * <p>
1120     * Clients are also able to acquire the {@link EnvironmentInfo} service and query it for
1121     * the NL.
1122     * </p>
1123     * @return the string name of the current locale
1124     * @since 3.0
1125     */
1126    public static String   getNL() {
1127        return InternalPlatform.getDefault().getNL();
1128    }
1129
1130    /**
1131     * Returns the string name of the current operating system for use in finding
1132     * files whose path starts with <code>$os$</code>.  <code>OS_UNKNOWN</code> is
1133     * returned if the operating system cannot be determined.  
1134     * The value may indicate one of the operating systems known to the platform
1135     * (as specified in <code>knownOSValues</code>) or a user-defined string if
1136     * the operating system name is specified on the command line.
1137     * <p>
1138     * Clients are also able to acquire the {@link EnvironmentInfo} service and query it for
1139     * the operating-system.
1140     * </p>
1141     * @return the string name of the current operating system
1142     * @since 3.0
1143     */
1144    public static String   getOS() {
1145        return InternalPlatform.getDefault().getOS();
1146    }
1147
1148    /**
1149     * Returns the string name of the current window system for use in finding files
1150     * whose path starts with <code>$ws$</code>.  <code>null</code> is returned
1151     * if the window system cannot be determined.
1152     * <p>
1153     * Clients are also able to acquire the {@link EnvironmentInfo} service and query it for
1154     * the windowing system.
1155     * </p>
1156     * @return the string name of the current window system or <code>null</code>
1157     * @since 3.0
1158     */
1159    public static String   getWS() {
1160        return InternalPlatform.getDefault().getWS();
1161    }
1162
1163    /**
1164     * Returns the arguments not consumed by the framework implementation itself.  Which
1165     * arguments are consumed is implementation specific. These arguments are available 
1166     * for use by the application.
1167     * 
1168     * @return the array of command line arguments not consumed by the framework.
1169     * @since 3.0
1170     * XXX Use the Environment info service. Need to see how to set the value of the app args.
1171     */
1172    public static String  [] getApplicationArgs() {
1173        return InternalPlatform.getDefault().getApplicationArgs();
1174    }
1175
1176    /**
1177     * Returns the platform administrator for this running Eclipse.  
1178     * <p>
1179     * Note: This is an internal method and <em>must not</em> 
1180     * be used by clients which are not part of the Eclipse Platform.
1181     * This method allows access to classes which are not Eclipse 
1182     * Platform API but are part of the OSGi runtime that the Eclipse
1183     * Platform is built on. Even as the Eclipse Platform evolves 
1184     * in compatible ways from release to release, the details of 
1185     * the OSGi implementation might not. 
1186     * </p><p>
1187     * Clients can also acquire the {@link PlatformAdmin} service
1188     * to retrieve this object.
1189     * </p>
1190     * @return the platform admin for this instance of Eclipse
1191     * @since 3.0
1192     */
1193    public static PlatformAdmin getPlatformAdmin() {
1194        return InternalPlatform.getDefault().getPlatformAdmin();
1195    }
1196
1197    /**
1198     * Returns the location of the platform's working directory (also known as the instance data area).  
1199     * <code>null</code> is returned if the platform is running without an instance location.
1200     * <p>
1201     * This method is equivalent to acquiring the <code>org.eclipse.osgi.service.datalocation.Location</code>
1202     * service with the property "type" equal to {@link Location#INSTANCE_FILTER}.
1203     *</p>
1204     * @return the location of the platform's instance data area or <code>null</code> if none
1205     * @since 3.0
1206     * @see Location#INSTANCE_FILTER
1207     */
1208    public static Location getInstanceLocation() {
1209        return InternalPlatform.getDefault().getInstanceLocation();
1210    }
1211
1212    /**
1213     * Returns the currently registered bundle group providers.
1214     * <p>
1215     * Clients are also able to acquire the {@link IBundleGroupProvider} service and query it for
1216     * the registered bundle group providers.
1217     * </p>
1218     * @return the currently registered bundle group providers
1219     * @since 3.0
1220     */
1221    public static IBundleGroupProvider[] getBundleGroupProviders() {
1222        return InternalPlatform.getDefault().getBundleGroupProviders();
1223    }
1224
1225    /**
1226     * Return the interface into the preference mechanism. The returned
1227     * object can be used for such operations as searching for preference 
1228     * values across multiple scopes and preference import/export.
1229     * <p>
1230     * Clients are also able to acquire the {@link IPreferencesService} service via
1231     * OSGi mechanisms and use it for preference functions.
1232     * </p>
1233     * @return an object to interface into the preference mechanism
1234     * @since 3.0
1235     */
1236    public static IPreferencesService getPreferencesService() {
1237        return InternalPlatform.getDefault().getPreferencesService();
1238    }
1239
1240    /**
1241     * Returns the product which was selected when running this Eclipse instance
1242     * or <code>null</code> if none
1243     * @return the current product or <code>null</code> if none
1244     * @since 3.0
1245     * XXX move this into the app model.
1246     */
1247    public static IProduct getProduct() {
1248        return InternalPlatform.getDefault().getProduct();
1249    }
1250
1251    /**
1252     * Registers the given bundle group provider with the platform.
1253     * <p>
1254     * Clients are also able to use the {@link IBundleGroupProvider} service to
1255     * register themselves as a bundle group provider.
1256     * </p>
1257     * @param provider a provider to register
1258     * @since 3.0
1259     */
1260    public static void registerBundleGroupProvider(IBundleGroupProvider provider) {
1261        InternalPlatform.getDefault().registerBundleGroupProvider(provider);
1262    }
1263
1264    /**
1265     * De-registers the given bundle group provider with the platform.
1266     * <p>
1267     * Clients are also able to use the {@link IBundleGroupProvider} service mechanism
1268     * for unregistering themselves.
1269     * </p>
1270     * @param provider a provider to de-register
1271     * @since 3.0
1272     * @see #registerBundleGroupProvider(IBundleGroupProvider)
1273     */
1274    public static void unregisterBundleGroupProvider(IBundleGroupProvider provider) {
1275        InternalPlatform.getDefault().unregisterBundleGroupProvider(provider);
1276    }
1277
1278    /**
1279     * Returns the location of the configuration information 
1280     * used to run this instance of Eclipse.  The configuration area typically
1281     * contains the list of plug-ins available for use, various settings
1282     * (those shared across different instances of the same configuration)
1283     * and any other such data needed by plug-ins.
1284     * <code>null</code> is returned if the platform is running without a configuration location.
1285     * <p>
1286     * This method is equivalent to acquiring the <code>org.eclipse.osgi.service.datalocation.Location</code>
1287     * service with the property "type" equal to {@link Location#CONFIGURATION_FILTER}.
1288     *</p>
1289     * @return the location of the platform's configuration data area or <code>null</code> if none
1290     * @since 3.0
1291     * @see Location#CONFIGURATION_FILTER
1292     */
1293    public static Location getConfigurationLocation() {
1294        return InternalPlatform.getDefault().getConfigurationLocation();
1295    }
1296
1297    /**
1298     * Returns the location of the platform's user data area.  The user data area is a location on the system
1299     * which is specific to the system's current user.  By default it is located relative to the 
1300     * location given by the System property "user.home".  
1301     * <code>null</code> is returned if the platform is running without an user location.
1302     * <p>
1303     * This method is equivalent to acquiring the <code>org.eclipse.osgi.service.datalocation.Location</code>
1304     * service with the property "type" equal to {@link Location#USER_FILTER}.
1305     *</p>
1306     * @return the location of the platform's user data area or <code>null</code> if none
1307     * @since 3.0
1308     * @see Location#USER_FILTER
1309     */
1310    public static Location getUserLocation() {
1311        return InternalPlatform.getDefault().getUserLocation();
1312    }
1313
1314    /**
1315     * Returns the location of the base installation for the running platform
1316     * <code>null</code> is returned if the platform is running without a configuration location.
1317     * <p>
1318     * This method is equivalent to acquiring the <code>org.eclipse.osgi.service.datalocation.Location</code>
1319     * service with the property "type" equal to {@link Location#INSTALL_FILTER}.
1320     *</p>
1321     * @return the location of the platform's installation area or <code>null</code> if none
1322     * @since 3.0
1323     * @see Location#INSTALL_FILTER
1324     */
1325    public static Location getInstallLocation() {
1326        return InternalPlatform.getDefault().getInstallLocation();
1327    }
1328
1329    /**
1330     * Checks if the specified bundle is a fragment bundle.
1331     * <p>
1332     * Clients are also able to acquire the {@link PackageAdmin} service
1333     * to query if the given bundle is a fragment by asking for the bundle type
1334     * and checking against constants on the service interface.
1335     * </p>
1336     * @param bundle the bundle to query
1337     * @return true if the specified bundle is a fragment bundle; otherwise false is returned.
1338     * @since 3.0
1339     */
1340    public static boolean isFragment(Bundle bundle) {
1341        return InternalPlatform.getDefault().isFragment(bundle);
1342    }
1343
1344    /**
1345     * Returns an array of attached fragment bundles for the specified bundle.  If the 
1346     * specified bundle is a fragment then <tt>null</tt> is returned.  If no fragments are 
1347     * attached to the specified bundle then <tt>null</tt> is returned.
1348     * <p>
1349     * Clients are also able to acquire the {@link PackageAdmin} service and query
1350     * it for the fragments of the given bundle.
1351     * </p>
1352     * @param bundle the bundle to get the attached fragment bundles for.
1353     * @return an array of fragment bundles or <tt>null</tt> if the bundle does not 
1354     * have any attached fragment bundles. 
1355     * @since 3.0
1356     */
1357    public static Bundle[] getFragments(Bundle bundle) {
1358        return InternalPlatform.getDefault().getFragments(bundle);
1359    }
1360
1361    /**
1362     * Returns the resolved bundle with the specified symbolic name that has the
1363     * highest version.  If no resolved bundles are installed that have the 
1364     * specified symbolic name then null is returned.
1365     * <p>
1366     * Clients are also able to acquire the {@link PackageAdmin} service and query
1367     * it for the bundle with the specified symbolic name. Clients can ask the
1368     * service for all bundles with that particular name and then determine the
1369     * one with the highest version. Note that clients may want to filter
1370     * the results based on the state of the bundles.
1371     * </p>
1372     * @param symbolicName the symbolic name of the bundle to be returned.
1373     * @return the bundle that has the specified symbolic name with the 
1374     * highest version, or <tt>null</tt> if no bundle is found.
1375     * @since 3.0
1376     */
1377    public static Bundle getBundle(String   symbolicName) {
1378        return InternalPlatform.getDefault().getBundle(symbolicName);
1379    }
1380
1381    /**
1382     * Returns all bundles with the specified symbolic name.  If no resolved bundles 
1383     * with the specified symbolic name can be found, <tt>null</tt> is returned.  
1384     * If the version argument is not null then only the Bundles that have 
1385     * the specified symbolic name and a version greater than or equal to the 
1386     * specified version are returned. The returned bundles are ordered in 
1387     * descending bundle version order.
1388     * <p>
1389     * Clients are also able to acquire the {@link PackageAdmin} service and query
1390     * it for all bundle versions with the given symbolic name, after turning the
1391     * specific version into a version range. Note that clients may want to filter
1392     * the results based on the state of the bundles.
1393     * </p>
1394     * @param symbolicName the symbolic name of the bundles that are to be returned.
1395     * @param version the version that the return bundle versions must match, 
1396     * or <tt>null</tt> if no version matching is to be done. 
1397     * @return the array of Bundles with the specified name that match the 
1398     * specified version and match rule, or <tt>null</tt> if no bundles are found.
1399     */
1400    public static Bundle[] getBundles(String   symbolicName, String   version) {
1401        return InternalPlatform.getDefault().getBundles(symbolicName, version);
1402    }
1403
1404    /**
1405     * Returns an array of host bundles that the specified fragment bundle is 
1406     * attached to or <tt>null</tt> if the specified bundle is not attached to a host.  
1407     * If the bundle is not a fragment bundle then <tt>null</tt> is returned.
1408     * <p>
1409     * Clients are also able to acquire the {@link PackageAdmin} service and query
1410     * it for the hosts for the given bundle.
1411     * </p>
1412     * @param bundle the bundle to get the host bundles for.
1413     * @return an array of host bundles or null if the bundle does not have any
1414     * host bundles.
1415     * @since 3.0
1416     */
1417    public static Bundle[] getHosts(Bundle bundle) {
1418        return InternalPlatform.getDefault().getHosts(bundle);
1419    }
1420
1421    /**
1422     * Returns whether the platform is running.
1423     *
1424     * @return <code>true</code> if the platform is running, 
1425     *      and <code>false</code> otherwise
1426     *@since 3.0
1427     *XXX do what you want to do. track osgi, track runtime, or whatever.
1428     */
1429    public static boolean isRunning() {
1430        return InternalPlatform.getDefault().isRunning();
1431    }
1432
1433    /**
1434     * Returns a list of known system architectures.
1435     * <p>
1436     * Note that this list is not authoritative; there may be legal values
1437     * not included in this list. Indeed, the value returned by 
1438     * <code>getOSArch</code> may not be in this list. Also, this list may 
1439     * change over time as Eclipse comes to run on more operating environments.
1440     * </p>
1441     * 
1442     * @return the list of system architectures known to the system
1443     * @see #getOSArch()
1444     * @since 3.0
1445     * XXX This is useless
1446     */
1447    public static String  [] knownOSArchValues() {
1448        return InternalPlatform.getDefault().knownOSArchValues();
1449    }
1450
1451    /**
1452     * Returns a list of known operating system names.
1453     * <p>
1454     * Note that this list is not authoritative; there may be legal values
1455     * not included in this list. Indeed, the value returned by 
1456     * <code>getOS</code> may not be in this list. Also, this list may 
1457     * change over time as Eclipse comes to run on more operating environments.
1458     * </p>
1459     * 
1460     * @return the list of operating systems known to the system
1461     * @see #getOS()
1462     * @since 3.0
1463     * XXX This is useless
1464     */
1465    public static String  [] knownOSValues() {
1466        return InternalPlatform.getDefault().knownOSValues();
1467    }
1468
1469    /**
1470     * Returns a map of known platform line separators. The keys are 
1471     * translated names of platforms and the values are their associated 
1472     * line separator strings.
1473     * 
1474     * @return a map of platform to their line separator string
1475     * @since 3.1
1476     */
1477    public static Map knownPlatformLineSeparators() {
1478        Map result = new HashMap();
1479        result.put(LINE_SEPARATOR_KEY_MAC_OS_9, LINE_SEPARATOR_VALUE_CR);
1480        result.put(LINE_SEPARATOR_KEY_UNIX, LINE_SEPARATOR_VALUE_LF);
1481        result.put(LINE_SEPARATOR_KEY_WINDOWS, LINE_SEPARATOR_VALUE_CRLF);
1482        return result;
1483    }
1484
1485    /**
1486     * Returns a list of known windowing system names.
1487     * <p>
1488     * Note that this list is not authoritative; there may be legal values
1489     * not included in this list. Indeed, the value returned by 
1490     * <code>getWS</code> may not be in this list. Also, this list may 
1491     * change over time as Eclipse comes to run on more operating environments.
1492     * </p>
1493     * 
1494     * @return the list of window systems known to the system
1495     * @see #getWS()
1496     * @since 3.0
1497     * XXX This is useless
1498     */
1499    public static String  [] knownWSValues() {
1500        return InternalPlatform.getDefault().knownWSValues();
1501    }
1502
1503    /**
1504     * Returns <code>true</code> if the platform is currently running in 
1505     * debug mode.  The platform is typically put in debug mode using the
1506     * "-debug" command line argument.
1507     * <p>
1508     * Clients are also able to acquire the {@link EnvironmentInfo} service and query it 
1509     * to see if they are in debug mode.
1510     * </p>
1511     * @return whether or not the platform is running in debug mode
1512     * @since 3.0
1513     */
1514    public static boolean inDebugMode() {
1515        return PlatformActivator.getContext().getProperty("osgi.debug") != null; //$NON-NLS-1$
1516    }
1517
1518    /**
1519     * Returns <code>true</code> if the platform is currently running in 
1520     * development mode.  That is, if special procedures are to be 
1521     * taken when defining plug-in class paths.  The platform is typically put in 
1522     * development mode using the "-dev" command line argument.
1523     * <p>
1524     * Clients are also able to acquire the {@link EnvironmentInfo} service and query it
1525     * to see if they are in development mode.
1526     * </p>
1527     * @return whether or not the platform is running in development mode
1528     * @since 3.0
1529     */
1530    public static boolean inDevelopmentMode() {
1531        return PlatformActivator.getContext().getProperty("osgi.dev") != null; //$NON-NLS-1$
1532    }
1533}
1534
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags