Summary

Specification of Taskbar::getIconImage doesn't mention that the returned image might not be equal to the Taskbar::setIconImage one.

Problem

As of now Taskbar::getIconImage/Taskbar::setIconImage are supported only on macOS. macOS implementation does internal conversion of passed image and always returns an instance of image of another class.

Solution

Clarify the current behavior in the javadoc. However we should consider possibility of returning the same instance of image if we decide to implement it another platforms in such way.

Specification

src/java.desktop/share/classes/java/awt/Taskbar.java

    /**
-    * Changes this application's icon to the provided image.
+    * Requests the system to change this application's icon to the provided {@code image}.
     *
     * @param image to change
     * @throws SecurityException if a security manager exists and it denies the
     * {@code RuntimePermission("canProcessApplicationEvents")} permission.
     * @throws UnsupportedOperationException if the current platform
     * does not support the {@link Taskbar.Feature#ICON_IMAGE} feature
     */
    public void setIconImage(final Image image) {

    /**
     * Obtains an image of this application's icon.
     *
+    * @apiNote The returned icon image may not be equal
+    * to an image set by {@link java.awt.Taskbar#setIconImage},
+    * but should be visually similar.
+    *
     * @return an image of this application's icon
     * @throws SecurityException if a security manager exists and it denies the
     * {@code RuntimePermission("canProcessApplicationEvents")} permission.
     * @throws UnsupportedOperationException if the current platform
     * does not support the {@link Taskbar.Feature#ICON_IMAGE} feature
     */
    public Image getIconImage() {