Desktop (Java Platform SE 8 )
Keywords: java.awt.Desktop class
Date: 2018-03-02

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 `mailto` URI;
  - 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 registering, 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

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Desktop.Action` Represents an action type.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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`

- - ### 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` - if `GraphicsEnvironment.isHeadless()` returns `true`
        `UnsupportedOperationException` - 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:
        `getDesktop()`

    - #### 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:
        `Desktop.Action`

    - #### 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` - if `file` is `null`
        `IllegalArgumentException` - if the specified file doesn't exist
        `UnsupportedOperationException` - if the current platform does not support the `Desktop.Action.OPEN` action
        `IOException` - if the specified file has no associated application or the associated application fails to be launched
        `SecurityException` - if a security manager exists and its `SecurityManager.checkRead(java.lang.String)` method denies read access to the file, or it denies the `AWTPermission("showWindowWithoutWarningBanner")` permission, or the calling thread is not allowed to create a subprocess
      See Also:
        `AWTPermission`

    - #### 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` - if the specified file is `null`
        `IllegalArgumentException` - if the specified file doesn't exist
        `UnsupportedOperationException` - if the current platform does not support the `Desktop.Action.EDIT` action
        `IOException` - if the specified file has no associated editor, or the associated application fails to be launched
        `SecurityException` - if a security manager exists and its `SecurityManager.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 the `AWTPermission("showWindowWithoutWarningBanner")` permission, or the calling thread is not allowed to create a subprocess
      See Also:
        `AWTPermission`

    - #### print

          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` - if the specified file is `null`
        `IllegalArgumentException` - if the specified file doesn't exist
        `UnsupportedOperationException` - if the current platform does not support the `Desktop.Action.PRINT` action
        `IOException` - if the specified file has no associated application that can be used to print it
        `SecurityException` - if a security manager exists and its `SecurityManager.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 specified `URI`, the application registered for handling `URIs` 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` - if `uri` is `null`
        `UnsupportedOperationException` - if the current platform does not support the `Desktop.Action.BROWSE` action
        `IOException` - if the user default browser is not found, or it fails to be launched, or the default handler application failed to be launched
        `SecurityException` - if a security manager exists and it denies the `AWTPermission("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` - if the necessary permissions are not available and the URI can not be converted to a `URL`
      See Also:
        `URI`, `AWTPermission`, `AppletContext`

    - #### mail

          public void mail()
                    throws IOException

      Launches the mail composing window of the user default mail client.
      Throws:
        `UnsupportedOperationException` - if the current platform does not support the `Desktop.Action.MAIL` action
        `IOException` - if the user default mail client is not found, or it fails to be launched
        `SecurityException` - if a security manager exists and it denies the `AWTPermission("showWindowWithoutWarningBanner")` permission, or the calling thread is not allowed to create a subprocess
      See Also:
        `AWTPermission`

    - #### mail

          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` - if the specified URI is `null`
        `IllegalArgumentException` - if the URI scheme is not `"mailto"`
        `UnsupportedOperationException` - if the current platform does not support the `Desktop.Action.MAIL` action
        `IOException` - if the user default mail client is not found or fails to be launched
        `SecurityException` - if a security manager exists and it denies the `AWTPermission("showWindowWithoutWarningBanner")` permission, or the calling thread is not allowed to create a subprocess
      See Also:
        `URI`, `AWTPermission`

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2018, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.