6815345: java.awt.Component.createImage(int width,int height) should remove behavioral optionality
Reviewed-by: prr, ssadetsky
--- a/jdk/src/java.desktop/share/classes/java/awt/Component.java Tue Oct 13 14:59:44 2015 +0300
+++ b/jdk/src/java.desktop/share/classes/java/awt/Component.java Sun Oct 18 13:33:20 2015 +0300
@@ -3622,18 +3622,17 @@
}
/**
- * Creates an off-screen drawable image
- * to be used for double buffering.
- * @param width the specified width
- * @param height the specified height
- * @return an off-screen drawable image, which can be used for double
- * buffering. The return value may be <code>null</code> if the
- * component is not displayable. This will always happen if
- * <code>GraphicsEnvironment.isHeadless()</code> returns
- * <code>true</code>.
+ * Creates an off-screen drawable image to be used for double buffering.
+ *
+ * @param width the specified width
+ * @param height the specified height
+ * @return an off-screen drawable image, which can be used for double
+ * buffering. The {@code null} value if the component is not
+ * displayable or {@code GraphicsEnvironment.isHeadless()} returns
+ * {@code true}.
* @see #isDisplayable
* @see GraphicsEnvironment#isHeadless
- * @since 1.0
+ * @since 1.0
*/
public Image createImage(int width, int height) {
ComponentPeer peer = this.peer;
@@ -3646,19 +3645,19 @@
}
/**
- * Creates a volatile off-screen drawable image
- * to be used for double buffering.
- * @param width the specified width.
- * @param height the specified height.
- * @return an off-screen drawable image, which can be used for double
- * buffering. The return value may be <code>null</code> if the
- * component is not displayable. This will always happen if
- * <code>GraphicsEnvironment.isHeadless()</code> returns
- * <code>true</code>.
+ * Creates a volatile off-screen drawable image to be used for double
+ * buffering.
+ *
+ * @param width the specified width
+ * @param height the specified height
+ * @return an off-screen drawable image, which can be used for double
+ * buffering. The {@code null} value if the component is not
+ * displayable or {@code GraphicsEnvironment.isHeadless()} returns
+ * {@code true}.
* @see java.awt.image.VolatileImage
* @see #isDisplayable
* @see GraphicsEnvironment#isHeadless
- * @since 1.4
+ * @since 1.4
*/
public VolatileImage createVolatileImage(int width, int height) {
ComponentPeer peer = this.peer;
@@ -3674,22 +3673,26 @@
}
/**
- * Creates a volatile off-screen drawable image, with the given capabilities.
- * The contents of this image may be lost at any time due
- * to operating system issues, so the image must be managed
- * via the <code>VolatileImage</code> interface.
- * @param width the specified width.
- * @param height the specified height.
- * @param caps the image capabilities
- * @exception AWTException if an image with the specified capabilities cannot
- * be created
- * @return a VolatileImage object, which can be used
- * to manage surface contents loss and capabilities.
+ * Creates a volatile off-screen drawable image, with the given
+ * capabilities. The contents of this image may be lost at any time due to
+ * operating system issues, so the image must be managed via the
+ * {@code VolatileImage} interface.
+ *
+ * @param width the specified width
+ * @param height the specified height
+ * @param caps the image capabilities
+ * @return a VolatileImage object, which can be used to manage surface
+ * contents loss and capabilities. The {@code null} value if the
+ * component is not displayable or
+ * {@code GraphicsEnvironment.isHeadless()} returns {@code true}.
+ * @throws AWTException if an image with the specified capabilities cannot
+ * be created
* @see java.awt.image.VolatileImage
* @since 1.4
*/
public VolatileImage createVolatileImage(int width, int height,
- ImageCapabilities caps) throws AWTException {
+ ImageCapabilities caps)
+ throws AWTException {
// REMIND : check caps
return createVolatileImage(width, height);
}
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/test/java/awt/Component/CreateImage/CreateImage.java Sun Oct 18 13:33:20 2015 +0300
@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+import java.awt.AWTException;
+import java.awt.Button;
+import java.awt.Component;
+import java.awt.EventQueue;
+import java.awt.Frame;
+import java.awt.GraphicsEnvironment;
+
+import javax.swing.JButton;
+
+/**
+ * @test
+ * @bug 6815345
+ * @run main CreateImage
+ * @run main/othervm -Djava.awt.headless=true CreateImage
+ */
+public final class CreateImage {
+
+ public static void main(final String[] args) throws Exception {
+ EventQueue.invokeAndWait(CreateImage::test);
+ }
+
+ private static void test() {
+ final JButton jbutton1 = new JButton();
+ final JButton jbutton2 = new JButton();
+
+ if (GraphicsEnvironment.isHeadless()) {
+ checkCreateImage(jbutton1, true);
+ checkCreateImage(jbutton2, true);
+ return;
+ }
+
+ final Frame frame = new Frame();
+ final Button button1 = new Button();
+ final Button button2 = new Button();
+ try {
+ // all components are not displayable
+ checkCreateImage(frame, true);
+ checkCreateImage(button1, true);
+ checkCreateImage(button2, true);
+ checkCreateImage(jbutton1, true);
+ checkCreateImage(jbutton2, true);
+
+ // some components added to the non-displayable frame
+ frame.add(button1);
+ frame.add(jbutton1);
+ checkCreateImage(button1, true);
+ checkCreateImage(jbutton1, true);
+ frame.pack();
+
+ // tests previously added components when the frame is displayable
+ checkCreateImage(frame, false);
+ checkCreateImage(button1, false);
+ checkCreateImage(jbutton1, false);
+
+ // some components added to the displayable frame
+ frame.add(button2);
+ frame.add(jbutton2);
+ checkCreateImage(button2, false);
+ checkCreateImage(jbutton2, false);
+
+ } finally {
+ frame.dispose();
+ }
+ // tests all components after the frame became non-displayable again
+ checkCreateImage(frame, true);
+ checkCreateImage(button1, true);
+ checkCreateImage(button2, true);
+ checkCreateImage(jbutton1, true);
+ checkCreateImage(jbutton2, true);
+ }
+
+ private static void checkCreateImage(final Component comp,
+ final boolean isNull) {
+ if ((comp.createImage(10, 10) != null) == isNull) {
+ throw new RuntimeException("Image is wrong");
+ }
+ if ((comp.createVolatileImage(10, 10) != null) == isNull) {
+ throw new RuntimeException("Image is wrong");
+ }
+ try {
+ if ((comp.createVolatileImage(10, 10, null) != null) == isNull) {
+ throw new RuntimeException("Image is wrong");
+ }
+ } catch (final AWTException ignored) {
+ // this check is not applicable
+ }
+ }
+}