Module java.desktop
Package java.awt

Class Desktop

  • public class Desktop
extends Object
    The Desktop class allows interact with various desktop capabilities.

    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. Please see Desktop.Action for the full list of supported operations and capabilities.

    An application is registered to a URI or file type. 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.

    Note: the methods in the Desktop class may require platform-dependent permissions in addition to those described in the specification.

    Since:
    1.6
    See Also:
    Desktop.Action

    • Method Detail

      • 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(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

      • 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

      • setOpenFileHandler

        public void setOpenFileHandler​(OpenFilesHandler openFileHandler)
        Installs the handler which is notified when the application is asked to open a list of files.
        Implementation Note:
        Please note that for macOS, notifications are only sent if the Java app is a bundled application, with a CFBundleDocumentTypes array present in its Info.plist. Check the Apple Developer Documentation for more information about Info.plist.
        Parameters:
        openFileHandler - handler
        Throws:
        SecurityException - if a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the files, or it denies the RuntimePermission("canProcessApplicationEvents") permission, or the calling thread is not allowed to create a subprocess
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_OPEN_FILE action
        Since:
        9

      • setPrintFileHandler

        public void setPrintFileHandler​(PrintFilesHandler printFileHandler)
        Installs the handler which is notified when the application is asked to print a list of files.
        Implementation Note:
        Please note that for macOS, notifications are only sent if the Java app is a bundled application, with a CFBundleDocumentTypes array present in its Info.plist. Check the Apple Developer Documentation for more information about Info.plist.
        Parameters:
        printFileHandler - handler
        Throws:
        SecurityException - if a security manager exists and its SecurityManager.checkPrintJobAccess() method denies the permission to print or it denies the RuntimePermission("canProcessApplicationEvents") permission
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_PRINT_FILE action
        Since:
        9

      • setOpenURIHandler

        public void setOpenURIHandler​(OpenURIHandler openURIHandler)
        Installs the handler which is notified when the application is asked to open a URL. Setting the handler to null causes all OpenURIHandler.openURI(OpenURIEvent) requests to be enqueued until another handler is set.
        Implementation Note:
        Please note that for macOS, notifications are only sent if the Java app is a bundled application, with a CFBundleDocumentTypes array present in its Info.plist. Check the Apple Developer Documentation for more information about Info.plist.
        Parameters:
        openURIHandler - handler RuntimePermission("canProcessApplicationEvents") permission, or the calling thread is not allowed to create a subprocess
        Throws:
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_OPEN_URI action
        Since:
        9

      • setQuitHandler

        public void setQuitHandler​(QuitHandler quitHandler)
        Installs the handler which determines if the application should quit. The handler is passed a one-shot QuitResponse which can cancel or proceed with the quit. Setting the handler to null causes all quit requests to directly perform the default QuitStrategy.
        Parameters:
        quitHandler - the handler that is called when the application is asked to quit
        Throws:
        SecurityException - if a security manager exists and it will not allow the caller to invoke System.exit or it denies the RuntimePermission("canProcessApplicationEvents") permission
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_QUIT_HANDLER action
        Since:
        9

      • setQuitStrategy

        public void setQuitStrategy​(QuitStrategy strategy)
        Sets the default strategy used to quit this application. The default is calling SYSTEM_EXIT_0.
        Parameters:
        strategy - the way this application should be shutdown
        Throws:
        SecurityException - if a security manager exists and it will not allow the caller to invoke System.exit or it denies the RuntimePermission("canProcessApplicationEvents") permission
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_QUIT_STRATEGY action
        Since:
        9
        See Also:
        QuitStrategy

      • enableSuddenTermination

        public void enableSuddenTermination()
        Enables this application to be suddenly terminated. Call this method to indicate your application's state is saved, and requires no notification to be terminated. Letting your application remain terminatable improves the user experience by avoiding re-paging in your application when it's asked to quit. Note: enabling sudden termination will allow your application to be quit without notifying your QuitHandler, or running any shutdown hooks. E.g. user-initiated Cmd-Q, logout, restart, or shutdown requests will effectively "kill -KILL" your application.
        Throws:
        SecurityException - if a security manager exists and it will not allow the caller to invoke System.exit or it denies the RuntimePermission("canProcessApplicationEvents") permission
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_SUDDEN_TERMINATION action
        Since:
        9
        See Also:
        disableSuddenTermination()

      • disableSuddenTermination

        public void disableSuddenTermination()
        Prevents this application from being suddenly terminated. Call this method to indicate that your application has unsaved state, and may not be terminated without notification.
        Throws:
        SecurityException - if a security manager exists and it will not allow the caller to invoke System.exit or it denies the RuntimePermission("canProcessApplicationEvents") permission
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_SUDDEN_TERMINATION action
        Since:
        9
        See Also:
        enableSuddenTermination()

      • requestForeground

        public void requestForeground​(boolean allWindows)
        Requests this application to move to the foreground.
        Parameters:
        allWindows - if all windows of this application should be moved to the foreground, or only the foremost one
        Throws:
        SecurityException - if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents") permission.
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_REQUEST_FOREGROUND action
        Since:
        9

      • openHelpViewer

        public void openHelpViewer()
        Opens the native help viewer application.
        Implementation Note:
        Please note that for Mac OS, it opens the native help viewer application if a Help Book has been added to the application bundler and registered in the Info.plist with CFBundleHelpBookFolder
        Throws:
        SecurityException - if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents") permission.
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_HELP_VIEWER action
        Since:
        9

      • setDefaultMenuBar

        public void setDefaultMenuBar​(JMenuBar menuBar)
        Sets the default menu bar to use when there are no active frames.
        Parameters:
        menuBar - to use when no other frames are active
        Throws:
        SecurityException - if a security manager exists and it denies the RuntimePermission("canProcessApplicationEvents") permission.
        UnsupportedOperationException - if the current platform does not support the Desktop.Action.APP_MENU_BAR action
        Since:
        9