JDK-8048731 : JEP 272: Platform-Specific Desktop Features
  • Type: JEP
  • Component: client-libs
  • Sub-Component: java.awt
  • Priority: P2
  • Status: Closed
  • Resolution: Delivered
  • Fix Versions: 9
  • Submitted: 2014-06-30
  • Updated: 2017-06-28
  • Resolved: 2017-01-26
Related Reports
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  
Relates :  

Define a new public API to access platform-specific desktop features such
as interacting with a task bar or dock, or listening for system or
application events.


In the forthcoming release of JDK 9, internal APIs such as those in the
Mac OS X `com.apple.eawt` package will no longer be
accessible. The goal of this JEP is to provide suitable
replacements for these inaccessible APIs and, also, introduce related
platform-specific features. We plan to implement the new features on
those platforms that have the necessary support. Where feasible, the API
will be designed to be cross-platform so that each feature can be
implemented on as wide a range of platforms as possible. 
`apple.applescript` classes are being removed without providing any replacement.


We do not intend to provide direct replacements for all of the internal
OS X APIs present in JDK 8. Specifically, we will not provide a
replacement for the `com.apple.concurrent` package. Is it also not a goal
to maintain compatibility with those internal APIs for which we do
provide substitutes.


This JEP contains two sub-tasks:

### Provide public API to replace the functionality in `com.apple.{eawt,eio}`

The intent of this subtask is to avoid loss of functionality for OS X
developers.  We will provide replacements for the APIs in the
JDK-internal `com.apple.eawt` and `com.apple.eio` packages.

### Provide access to similar features on other platforms

In addition to features specific to OS X, there are similar features that
can be supported on other platforms, including Windows and Linux:

  - Login/logout and screen lock handlers: Provide event listeners on
    system login/logout (or screen lock/unlock) to allow an application
    to start a persistent task or save its state when needed.

  - Task bar/dock interactions

    - Request user attention: Allow an application to request the
      attention of the user, using platform capabilities such as blinking
      the application icon in the taskbar or bouncing the icon in the

    - Indicate task progress: Display a progress bar or other indicator
      in the task bar/dock.

    - Action shortcuts: Provide action shortcuts that are accessible by a
      pop-up menu, for example, Windows jump-lists.

Support for these features will be determined by platform capabilities.

### API

We propose to add the public API for these two sub-tasks to the existing
`java.awt.Desktop` class. The target supported platforms are Mac OS X,
Windows, Linux.

Proposed API sketch:

    package java.awt;
    public class Desktop {
        /* ... */
         * Adds sub-types of {@link AppEventListener} to listen for notifications
         * from the native system.
         * @param listener
         * @see AppForegroundListener
         * @see AppHiddenListener
         * @see AppReOpenedListener
         * @see AppScreenSleepListener
         * @see AppSystemSleepListener
         * @see AppUserSessionListener
        public void addAppEventListener(final AppEventListener listener) {}
         * Requests user attention to this application (usually through bouncing the Dock icon).
         * Critical requests will continue to bounce the Dock icon until the app is activated.
        public void requestUserAttention(final boolean critical) {}
         * Attaches the contents of the provided PopupMenu to the application's Dock icon.
        public void setDockMenu(final PopupMenu menu) {}
         * Changes this application's Dock icon to the provided image.
        public void setDockIconImage(final Image image) {}
         * Affixes a small system provided badge to this application's Dock icon. Usually a number.
        public void setDockIconBadge(final String badge) {}
         * Displays or hides a progress bar or other indicator in
         * the dock.
         * @see DockProgressState.NORMAL
         * @see DockProgressState.PAUSED
         * @see DockProgressState.ERROR
         * @see #setDockProgressValue
        public void setDockProgressState(int state) {}
         * Sets the progress bar's current value to {@code n}.
        public void setDockProgressValue(int n) {}
         * Tests whether a feature is supported on the current platform.
        public boolean isSupportedFeature(Feature f) {}
        /* ... */


Testing will be limited to additional manual tests written to use the new
API. Tests will need to check whether the new features are supported on
platforms where they are expected to be supported, and that they fail
gracefully on platforms with no support.


Internal deprecated APIs will be removed, (like register individual handlers for each task, for the full list please refer to http://cr.openjdk.java.net/~azvegint/jdk/9/8143227/10/jdk/src/java.desktop/macosx/classes/com/apple/eawt/Application.java.udiff.html )

Two approvals to push are in place: http://mail.openjdk.java.net/pipermail/awt-dev/2016-March/010772.html as well Ok from Jigsaw: http://mail.openjdk.java.net/pipermail/awt-dev/2016-March/010775.html

updated the webrev (8th revision) here http://cr.openjdk.java.net/~azvegint/jdk/9/8143227/08/

Updated (7th) revision: http://cr.openjdk.java.net/~azvegint/jdk/9/8143227/07/

Updated (6th) revision: http://cr.openjdk.java.net/~azvegint/jdk/9/8143227/06/ Open issues will be forked to separated bug(s). The target to push this code base by end of this week (Feb 19)

Jan 21 revision: http://cr.openjdk.java.net/~azvegint/jdk/9/8143227/05/ http://mail.openjdk.java.net/pipermail/awt-dev/2016-January/010598.html

Due Date updated based on SQE input

I agree with previous comments, can methods be renamed to not use "Dock". I don't agree with "Taskbar" either however. Something more generic, perhaps "Application" is more generic. I also think this should not be in awt, unless there is a JavaFX equivalent version.

Will be moved back to Proposed To Target next week (Oct 14) since SQE needs one more week for SQE Test Plan finalization.

I've added the link to the related JavaFX issue: JDK-8091107

One major issue I see with the java.awt.Desktop class: if you want to use those features in a JavaFX application you would likely need then the complete AWT stack. Would it be possible to add such utility functions in a GUI-toolkit agnostic package/ class from now on, so that it can be used by any GUI toolkit without the need to add the complete GUI stack in a tailored JRE (Jigsaw)? I see some AWT dependencies such as Popup and Image, so this might not be possible. At least make sure it can be easily ported to JavaFX eg. by resusing some of the implementation classes.

Sorry for the previous question. I have another one: why to use the "dock" term from the Mac-world in a generic class? It is not used on other platforms and can confuse developers. Taskbar is much more recognisable term.

P2 as related to modularization

The sketch is added, JEP is updated.

**reverted to draft pending completion of IPCOM review**

Raising priority due to functionality loss without this feature.

Proposed public API http://cr.openjdk.java.net/~azvegint/jdk/jep/8048731/00/ .