View Javadoc
1   /*
2    * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.awt;
27  
28  import java.io.File;
29  import java.io.IOException;
30  import java.net.URISyntaxException;
31  import java.net.URI;
32  import java.net.URL;
33  import java.net.MalformedURLException;
34  import java.awt.AWTPermission;
35  import java.awt.GraphicsEnvironment;
36  import java.awt.HeadlessException;
37  import java.awt.peer.DesktopPeer;
38  import sun.awt.SunToolkit;
39  import sun.awt.HeadlessToolkit;
40  import java.io.FilePermission;
41  import sun.security.util.SecurityConstants;
42  
43  /**
44   * The {@code Desktop} class allows a Java application to launch
45   * associated applications registered on the native desktop to handle
46   * a {@link java.net.URI} or a file.
47   *
48   * <p> Supported operations include:
49   * <ul>
50   *   <li>launching the user-default browser to show a specified
51   *       URI;</li>
52   *   <li>launching the user-default mail client with an optional
53   *       {@code mailto} URI;</li>
54   *   <li>launching a registered application to open, edit or print a
55   *       specified file.</li>
56   * </ul>
57   *
58   * <p> This class provides methods corresponding to these
59   * operations. The methods look for the associated application
60   * registered on the current platform, and launch it to handle a URI
61   * or file. If there is no associated application or the associated
62   * application fails to be launched, an exception is thrown.
63   *
64   * <p> An application is registered to a URI or file type; for
65   * example, the {@code "sxi"} file extension is typically registered
66   * to StarOffice.  The mechanism of registering, accessing, and
67   * launching the associated application is platform-dependent.
68   *
69   * <p> Each operation is an action type represented by the {@link
70   * Desktop.Action} class.
71   *
72   * <p> Note: when some action is invoked and the associated
73   * application is executed, it will be executed on the same system as
74   * the one on which the Java application was launched.
75   *
76   * @since 1.6
77   * @author Armin Chen
78   * @author George Zhang
79   */
80  public class Desktop {
81  
82      /**
83       * Represents an action type.  Each platform supports a different
84       * set of actions.  You may use the {@link Desktop#isSupported}
85       * method to determine if the given action is supported by the
86       * current platform.
87       * @see java.awt.Desktop#isSupported(java.awt.Desktop.Action)
88       * @since 1.6
89       */
90      public static enum Action {
91          /**
92           * Represents an "open" action.
93           * @see Desktop#open(java.io.File)
94           */
95          OPEN,
96          /**
97           * Represents an "edit" action.
98           * @see Desktop#edit(java.io.File)
99           */
100         EDIT,
101         /**
102          * Represents a "print" action.
103          * @see Desktop#print(java.io.File)
104          */
105         PRINT,
106         /**
107          * Represents a "mail" action.
108          * @see Desktop#mail()
109          * @see Desktop#mail(java.net.URI)
110          */
111         MAIL,
112         /**
113          * Represents a "browse" action.
114          * @see Desktop#browse(java.net.URI)
115          */
116         BROWSE
117     };
118 
119     private DesktopPeer peer;
120 
121     /**
122      * Suppresses default constructor for noninstantiability.
123      */
124     private Desktop() {
125         peer = Toolkit.getDefaultToolkit().createDesktopPeer(this);
126     }
127 
128     /**
129      * Returns the <code>Desktop</code> instance of the current
130      * browser context.  On some platforms the Desktop API may not be
131      * supported; use the {@link #isDesktopSupported} method to
132      * determine if the current desktop is supported.
133      * @return the Desktop instance of the current browser context
134      * @throws HeadlessException if {@link
135      * GraphicsEnvironment#isHeadless()} returns {@code true}
136      * @throws UnsupportedOperationException if this class is not
137      * supported on the current platform
138      * @see #isDesktopSupported()
139      * @see java.awt.GraphicsEnvironment#isHeadless
140      */
141     public static synchronized Desktop getDesktop(){
142         if (GraphicsEnvironment.isHeadless()) throw new HeadlessException();
143         if (!Desktop.isDesktopSupported()) {
144             throw new UnsupportedOperationException("Desktop API is not " +
145                                                     "supported on the current platform");
146         }
147 
148         sun.awt.AppContext context = sun.awt.AppContext.getAppContext();
149         Desktop desktop = (Desktop)context.get(Desktop.class);
150 
151         if (desktop == null) {
152             desktop = new Desktop();
153             context.put(Desktop.class, desktop);
154         }
155 
156         return desktop;
157     }
158 
159     /**
160      * Tests whether this class is supported on the current platform.
161      * If it's supported, use {@link #getDesktop()} to retrieve an
162      * instance.
163      *
164      * @return <code>true</code> if this class is supported on the
165      *         current platform; <code>false</code> otherwise
166      * @see #getDesktop()
167      */
168     public static boolean isDesktopSupported(){
169         Toolkit defaultToolkit = Toolkit.getDefaultToolkit();
170         if (defaultToolkit instanceof SunToolkit) {
171             return ((SunToolkit)defaultToolkit).isDesktopSupported();
172         }
173         return false;
174     }
175 
176     /**
177      * Tests whether an action is supported on the current platform.
178      *
179      * <p>Even when the platform supports an action, a file or URI may
180      * not have a registered application for the action.  For example,
181      * most of the platforms support the {@link Desktop.Action#OPEN}
182      * action.  But for a specific file, there may not be an
183      * application registered to open it.  In this case, {@link
184      * #isSupported} may return {@code true}, but the corresponding
185      * action method will throw an {@link IOException}.
186      *
187      * @param action the specified {@link Action}
188      * @return <code>true</code> if the specified action is supported on
189      *         the current platform; <code>false</code> otherwise
190      * @see Desktop.Action
191      */
192     public boolean isSupported(Action action) {
193         return peer.isSupported(action);
194     }
195 
196     /**
197      * Checks if the file is a valid file and readable.
198      *
199      * @throws SecurityException If a security manager exists and its
200      *         {@link SecurityManager#checkRead(java.lang.String)} method
201      *         denies read access to the file
202      * @throws NullPointerException if file is null
203      * @throws IllegalArgumentException if file doesn't exist
204      */
205     private static void checkFileValidation(File file){
206         if (file == null) throw new NullPointerException("File must not be null");
207 
208         if (!file.exists()) {
209             throw new IllegalArgumentException("The file: "
210                                                + file.getPath() + " doesn't exist.");
211         }
212 
213         file.canRead();
214     }
215 
216     /**
217      * Checks if the action type is supported.
218      *
219      * @param actionType the action type in question
220      * @throws UnsupportedOperationException if the specified action type is not
221      *         supported on the current platform
222      */
223     private void checkActionSupport(Action actionType){
224         if (!isSupported(actionType)) {
225             throw new UnsupportedOperationException("The " + actionType.name()
226                                                     + " action is not supported on the current platform!");
227         }
228     }
229 
230 
231     /**
232      *  Calls to the security manager's <code>checkPermission</code> method with
233      *  an <code>AWTPermission("showWindowWithoutWarningBanner")</code>
234      *  permission.
235      */
236     private void checkAWTPermission(){
237         SecurityManager sm = System.getSecurityManager();
238         if (sm != null) {
239             sm.checkPermission(new AWTPermission(
240                                    "showWindowWithoutWarningBanner"));
241         }
242     }
243 
244     /**
245      * Launches the associated application to open the file.
246      *
247      * <p> If the specified file is a directory, the file manager of
248      * the current platform is launched to open it.
249      *
250      * @param file the file to be opened with the associated application
251      * @throws NullPointerException if {@code file} is {@code null}
252      * @throws IllegalArgumentException if the specified file doesn't
253      * exist
254      * @throws UnsupportedOperationException if the current platform
255      * does not support the {@link Desktop.Action#OPEN} action
256      * @throws IOException if the specified file has no associated
257      * application or the associated application fails to be launched
258      * @throws SecurityException if a security manager exists and its
259      * {@link java.lang.SecurityManager#checkRead(java.lang.String)}
260      * method denies read access to the file, or it denies the
261      * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
262      * permission, or the calling thread is not allowed to create a
263      * subprocess
264      * @see java.awt.AWTPermission
265      */
266     public void open(File file) throws IOException {
267         checkAWTPermission();
268         checkExec();
269         checkActionSupport(Action.OPEN);
270         checkFileValidation(file);
271 
272         peer.open(file);
273     }
274 
275     /**
276      * Launches the associated editor application and opens a file for
277      * editing.
278      *
279      * @param file the file to be opened for editing
280      * @throws NullPointerException if the specified file is {@code null}
281      * @throws IllegalArgumentException if the specified file doesn't
282      * exist
283      * @throws UnsupportedOperationException if the current platform
284      * does not support the {@link Desktop.Action#EDIT} action
285      * @throws IOException if the specified file has no associated
286      * editor, or the associated application fails to be launched
287      * @throws SecurityException if a security manager exists and its
288      * {@link java.lang.SecurityManager#checkRead(java.lang.String)}
289      * method denies read access to the file, or {@link
290      * java.lang.SecurityManager#checkWrite(java.lang.String)} method
291      * denies write access to the file, or it denies the
292      * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
293      * permission, or the calling thread is not allowed to create a
294      * subprocess
295      * @see java.awt.AWTPermission
296      */
297     public void edit(File file) throws IOException {
298         checkAWTPermission();
299         checkExec();
300         checkActionSupport(Action.EDIT);
301         file.canWrite();
302         checkFileValidation(file);
303 
304         peer.edit(file);
305     }
306 
307     /**
308      * Prints a file with the native desktop printing facility, using
309      * the associated application's print command.
310      *
311      * @param file the file to be printed
312      * @throws NullPointerException if the specified file is {@code
313      * null}
314      * @throws IllegalArgumentException if the specified file doesn't
315      * exist
316      * @throws UnsupportedOperationException if the current platform
317      *         does not support the {@link Desktop.Action#PRINT} action
318      * @throws IOException if the specified file has no associated
319      * application that can be used to print it
320      * @throws SecurityException if a security manager exists and its
321      * {@link java.lang.SecurityManager#checkRead(java.lang.String)}
322      * method denies read access to the file, or its {@link
323      * java.lang.SecurityManager#checkPrintJobAccess()} method denies
324      * the permission to print the file, or the calling thread is not
325      * allowed to create a subprocess
326      */
327     public void print(File file) throws IOException {
328         checkExec();
329         SecurityManager sm = System.getSecurityManager();
330         if (sm != null) {
331             sm.checkPrintJobAccess();
332         }
333         checkActionSupport(Action.PRINT);
334         checkFileValidation(file);
335 
336         peer.print(file);
337     }
338 
339     /**
340      * Launches the default browser to display a {@code URI}.
341      * If the default browser is not able to handle the specified
342      * {@code URI}, the application registered for handling
343      * {@code URIs} of the specified type is invoked. The application
344      * is determined from the protocol and path of the {@code URI}, as
345      * defined by the {@code URI} class.
346      * <p>
347      * If the calling thread does not have the necessary permissions,
348      * and this is invoked from within an applet,
349      * {@code AppletContext.showDocument()} is used. Similarly, if the calling
350      * does not have the necessary permissions, and this is invoked from within
351      * a Java Web Started application, {@code BasicService.showDocument()}
352      * is used.
353      *
354      * @param uri the URI to be displayed in the user default browser
355      * @throws NullPointerException if {@code uri} is {@code null}
356      * @throws UnsupportedOperationException if the current platform
357      * does not support the {@link Desktop.Action#BROWSE} action
358      * @throws IOException if the user default browser is not found,
359      * or it fails to be launched, or the default handler application
360      * failed to be launched
361      * @throws SecurityException if a security manager exists and it
362      * denies the
363      * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
364      * permission, or the calling thread is not allowed to create a
365      * subprocess; and not invoked from within an applet or Java Web Started
366      * application
367      * @throws IllegalArgumentException if the necessary permissions
368      * are not available and the URI can not be converted to a {@code URL}
369      * @see java.net.URI
370      * @see java.awt.AWTPermission
371      * @see java.applet.AppletContext
372      */
373     public void browse(URI uri) throws IOException {
374         SecurityException securityException = null;
375         try {
376             checkAWTPermission();
377             checkExec();
378         } catch (SecurityException e) {
379             securityException = e;
380         }
381         checkActionSupport(Action.BROWSE);
382         if (uri == null) {
383             throw new NullPointerException();
384         }
385         if (securityException == null) {
386             peer.browse(uri);
387             return;
388         }
389 
390         // Calling thread doesn't have necessary priviledges.
391         // Delegate to DesktopBrowse so that it can work in
392         // applet/webstart.
393         URL url = null;
394         try {
395             url = uri.toURL();
396         } catch (MalformedURLException e) {
397             throw new IllegalArgumentException("Unable to convert URI to URL", e);
398         }
399         sun.awt.DesktopBrowse db = sun.awt.DesktopBrowse.getInstance();
400         if (db == null) {
401             // Not in webstart/applet, throw the exception.
402             throw securityException;
403         }
404         db.browse(url);
405     }
406 
407     /**
408      * Launches the mail composing window of the user default mail
409      * client.
410      *
411      * @throws UnsupportedOperationException if the current platform
412      * does not support the {@link Desktop.Action#MAIL} action
413      * @throws IOException if the user default mail client is not
414      * found, or it fails to be launched
415      * @throws SecurityException if a security manager exists and it
416      * denies the
417      * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
418      * permission, or the calling thread is not allowed to create a
419      * subprocess
420      * @see java.awt.AWTPermission
421      */
422     public void mail() throws IOException {
423         checkAWTPermission();
424         checkExec();
425         checkActionSupport(Action.MAIL);
426         URI mailtoURI = null;
427         try{
428             mailtoURI = new URI("mailto:?");
429             peer.mail(mailtoURI);
430         } catch (URISyntaxException e){
431             // won't reach here.
432         }
433     }
434 
435     /**
436      * Launches the mail composing window of the user default mail
437      * client, filling the message fields specified by a {@code
438      * mailto:} URI.
439      *
440      * <p> A <code>mailto:</code> URI can specify message fields
441      * including <i>"to"</i>, <i>"cc"</i>, <i>"subject"</i>,
442      * <i>"body"</i>, etc.  See <a
443      * href="http://www.ietf.org/rfc/rfc2368.txt">The mailto URL
444      * scheme (RFC 2368)</a> for the {@code mailto:} URI specification
445      * details.
446      *
447      * @param mailtoURI the specified {@code mailto:} URI
448      * @throws NullPointerException if the specified URI is {@code
449      * null}
450      * @throws IllegalArgumentException if the URI scheme is not
451      *         <code>"mailto"</code>
452      * @throws UnsupportedOperationException if the current platform
453      * does not support the {@link Desktop.Action#MAIL} action
454      * @throws IOException if the user default mail client is not
455      * found or fails to be launched
456      * @throws SecurityException if a security manager exists and it
457      * denies the
458      * <code>AWTPermission("showWindowWithoutWarningBanner")</code>
459      * permission, or the calling thread is not allowed to create a
460      * subprocess
461      * @see java.net.URI
462      * @see java.awt.AWTPermission
463      */
464     public  void mail(URI mailtoURI) throws IOException {
465         checkAWTPermission();
466         checkExec();
467         checkActionSupport(Action.MAIL);
468         if (mailtoURI == null) throw new NullPointerException();
469 
470         if (!"mailto".equalsIgnoreCase(mailtoURI.getScheme())) {
471             throw new IllegalArgumentException("URI scheme is not \"mailto\"");
472         }
473 
474         peer.mail(mailtoURI);
475     }
476 
477     private void checkExec() throws SecurityException {
478         SecurityManager sm = System.getSecurityManager();
479         if (sm != null) {
480             sm.checkPermission(new FilePermission("<<ALL FILES>>",
481                                                   SecurityConstants.FILE_EXECUTE_ACTION));
482         }
483     }
484 }