Desktop (Java Platform SE 6) (original) (raw)
java.awt
Class Desktop
java.lang.Object
java.awt.Desktop
public class Desktop
extends Object
The Desktop class allows a Java application to launch associated applications registered on the native desktop to handle a URI or a file.
Supported operations include:
- launching the user-default browser to show a specified URI;
- launching the user-default mail client with an optional
mailtoURI; - launching a registered application to open, edit or print a specified file.
This class provides methods corresponding to these operations. The methods look for the associated application registered on the current platform, and launch it to handle a URI or file. If there is no associated application or the associated application fails to be launched, an exception is thrown.
An application is registered to a URI or file type; for example, the "sxi" file extension is typically registered to StarOffice. The mechanism of registereing, accessing, and launching the associated application is platform-dependent.
Each operation is an action type represented by the Desktop.Action class.
Note: when some action is invoked and the associated application is executed, it will be executed on the same system as the one on which the Java application was launched.
Since:
1.6
| Nested Class Summary | |
|---|---|
| static class | Desktop.Action Represents an action type. |
| Method Summary | |
|---|---|
| void | browse(URI uri) Launches the default browser to display a URI. |
| void | edit(File file) Launches the associated editor application and opens a file for editing. |
| static Desktop | getDesktop() Returns the Desktop instance of the current browser context. |
| static boolean | isDesktopSupported() Tests whether this class is supported on the current platform. |
| boolean | isSupported(Desktop.Action action) Tests whether an action is supported on the current platform. |
| void | mail() Launches the mail composing window of the user default mail client. |
| void | mail(URI mailtoURI) Launches the mail composing window of the user default mail client, filling the message fields specified by a mailto: URI. |
| void | open(File file) Launches the associated application to open the file. |
| void | print(File file) Prints a file with the native desktop printing facility, using the associated application's print command. |
| Methods inherited from class java.lang.Object |
|---|
| clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, [wait](../../java/lang/Object.html#wait%28long, int%29) |
| Method Detail |
|---|
getDesktop
public static Desktop getDesktop()
Returns the Desktop instance of the current browser context. On some platforms the Desktop API may not be supported; use the isDesktopSupported() method to determine if the current desktop is supported.
Returns:
the Desktop instance of the current browser context
Throws:
[HeadlessException](../../java/awt/HeadlessException.html "class in java.awt") - if GraphicsEnvironment.isHeadless() returns true
[UnsupportedOperationException](../../java/lang/UnsupportedOperationException.html "class in java.lang") - if this class is not supported on the current platform
See Also:
isDesktopSupported(), GraphicsEnvironment.isHeadless()
isDesktopSupported
public static boolean isDesktopSupported()
Tests whether this class is supported on the current platform. If it's supported, use getDesktop() to retrieve an instance.
Returns:
true if this class is supported on the current platform; false otherwise
See Also:
isSupported
public boolean isSupported(Desktop.Action action)
Tests whether an action is supported on the current platform.
Even when the platform supports an action, a file or URI may not have a registered application for the action. For example, most of the platforms support the Desktop.Action.OPEN action. But for a specific file, there may not be an application registered to open it. In this case, isSupported(java.awt.Desktop.Action) may return true, but the corresponding action method will throw an IOException.
Parameters:
action - the specified Desktop.Action
Returns:
true if the specified action is supported on the current platform; false otherwise
See Also:
open
public void open(File file) throws IOException
Launches the associated application to open the file.
If the specified file is a directory, the file manager of the current platform is launched to open it.
Parameters:
file - the file to be opened with the associated application
Throws:
[NullPointerException](../../java/lang/NullPointerException.html "class in java.lang") - if file is null
[IllegalArgumentException](../../java/lang/IllegalArgumentException.html "class in java.lang") - if the specified file dosen't exist
[UnsupportedOperationException](../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the current platform does not support the Desktop.Action.OPEN action
[IOException](../../java/io/IOException.html "class in java.io") - if the specified file has no associated application or the associated application fails to be launched
[SecurityException](../../java/lang/SecurityException.html "class in java.lang") - if a security manager exists and itsSecurityManager.checkRead(java.lang.String) method denies read access to the file, or it denies theAWTPermission("showWindowWithoutWarningBanner") permission, or the calling thread is not allowed to create a subprocess
See Also:
edit
public void edit(File file) throws IOException
Launches the associated editor application and opens a file for editing.
Parameters:
file - the file to be opened for editing
Throws:
[NullPointerException](../../java/lang/NullPointerException.html "class in java.lang") - if the specified file is null
[IllegalArgumentException](../../java/lang/IllegalArgumentException.html "class in java.lang") - if the specified file doesn't exist
[UnsupportedOperationException](../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the current platform does not support the Desktop.Action.EDIT action
[IOException](../../java/io/IOException.html "class in java.io") - if the specified file has no associated editor, or the associated application fails to be launched
[SecurityException](../../java/lang/SecurityException.html "class in java.lang") - if a security manager exists and itsSecurityManager.checkRead(java.lang.String) method denies read access to the file, or SecurityManager.checkWrite(java.lang.String) method denies write access to the file, or it denies theAWTPermission("showWindowWithoutWarningBanner") permission, or the calling thread is not allowed to create a subprocess
See Also:
public void print(File file) throws IOException
Prints a file with the native desktop printing facility, using the associated application's print command.
Parameters:
file - the file to be printed
Throws:
[NullPointerException](../../java/lang/NullPointerException.html "class in java.lang") - if the specified file is null
[IllegalArgumentException](../../java/lang/IllegalArgumentException.html "class in java.lang") - if the specified file doesn't exist
[UnsupportedOperationException](../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the current platform does not support the Desktop.Action.PRINT action
[IOException](../../java/io/IOException.html "class in java.io") - if the specified file has no associated application that can be used to print it
[SecurityException](../../java/lang/SecurityException.html "class in java.lang") - if a security manager exists and itsSecurityManager.checkRead(java.lang.String) method denies read access to the file, or its SecurityManager.checkPrintJobAccess() method denies the permission to print the file, or the calling thread is not allowed to create a subprocess
browse
public void browse(URI uri) throws IOException
Launches the default browser to display a URI. If the default browser is not able to handle the specifiedURI, the application registered for handlingURIs of the specified type is invoked. The application is determined from the protocol and path of the URI, as defined by the URI class.
If the calling thread does not have the necessary permissions, and this is invoked from within an applet,AppletContext.showDocument() is used. Similarly, if the calling does not have the necessary permissions, and this is invoked from within a Java Web Started application, BasicService.showDocument() is used.
Parameters:
uri - the URI to be displayed in the user default browser
Throws:
[NullPointerException](../../java/lang/NullPointerException.html "class in java.lang") - if uri is null
[UnsupportedOperationException](../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the current platform does not support the Desktop.Action.BROWSE action
[IOException](../../java/io/IOException.html "class in java.io") - if the user default browser is not found, or it fails to be launched, or the default handler application failed to be launched
[SecurityException](../../java/lang/SecurityException.html "class in java.lang") - if a security manager exists and it denies theAWTPermission("showWindowWithoutWarningBanner") permission, or the calling thread is not allowed to create a subprocess; and not invoked from within an applet or Java Web Started application
[IllegalArgumentException](../../java/lang/IllegalArgumentException.html "class in java.lang") - if the necessary permissions are not available and the URI can not be converted to a URL
See Also:
URI, AWTPermission, AppletContext
public void mail() throws IOException
Launches the mail composing window of the user default mail client.
Throws:
[UnsupportedOperationException](../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the current platform does not support the Desktop.Action.MAIL action
[IOException](../../java/io/IOException.html "class in java.io") - if the user default mail client is not found, or it fails to be launched
[SecurityException](../../java/lang/SecurityException.html "class in java.lang") - if a security manager exists and it denies theAWTPermission("showWindowWithoutWarningBanner") permission, or the calling thread is not allowed to create a subprocess
See Also:
public void mail(URI mailtoURI) throws IOException
Launches the mail composing window of the user default mail client, filling the message fields specified by a mailto: URI.
A mailto: URI can specify message fields including "to", "cc", "subject","body", etc. See The mailto URL scheme (RFC 2368) for the mailto: URI specification details.
Parameters:
mailtoURI - the specified mailto: URI
Throws:
[NullPointerException](../../java/lang/NullPointerException.html "class in java.lang") - if the specified URI is null
[IllegalArgumentException](../../java/lang/IllegalArgumentException.html "class in java.lang") - if the URI scheme is not"mailto"
[UnsupportedOperationException](../../java/lang/UnsupportedOperationException.html "class in java.lang") - if the current platform does not support the Desktop.Action.MAIL action
[IOException](../../java/io/IOException.html "class in java.io") - if the user default mail client is not found or fails to be launched
[SecurityException](../../java/lang/SecurityException.html "class in java.lang") - if a security manager exists and it denies theAWTPermission("showWindowWithoutWarningBanner") permission, or the calling thread is not allowed to create a subprocess
See Also:
Submit a bug or feature
For further API reference and developer documentation, see Java SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2015, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.
Scripting on this page tracks web page traffic, but does not change the content in any way.