6573289: api/java_awt/Color/index.html#CreateContextTesttestCase4,5,6,7 fail since JDK 7 b14

Summary: specify current behavior - not caching the painting context
Reviewed-by: flar, son

src/share/classes/java/awt/Color.java

@@ -51,6 +51,7 @@ import java.awt.color.ColorSpace;
  * http://www.w3.org/pub/WWW/Graphics/Color/sRGB.html
  * </A>.
  * <p>
+ * @version     10 Feb 1997
  * @author      Sami Shaio
  * @author      Arthur van Hoff
  * @see         ColorSpace
@@ -1176,23 +1177,32 @@ public class Color implements Paint, java.io.Serializable {
     }
 
     /**
-     * Creates and returns a {@link PaintContext} used to generate a solid
-     * color pattern.  This enables a <code>Color</code> object to be used
-     * as an argument to any method requiring an object implementing the
-     * {@link Paint} interface.
-     * The same <code>PaintContext</code> is returned, regardless of
-     * whether or not <code>r</code>, <code>r2d</code>,
-     * <code>xform</code>, or <code>hints</code> are <code>null</code>.
-     * @param cm the specified <code>ColorModel</code>
-     * @param r the specified {@link Rectangle}
-     * @param r2d the specified {@link Rectangle2D}
-     * @param xform the specified {@link AffineTransform}
-     * @param hints the specified {@link RenderingHints}
-     * @return a <code>PaintContext</code> that is used to generate a
-     *          solid color pattern.
+     * Creates and returns a {@link PaintContext} used to
+     * generate a solid color field pattern.
+     * See the {@link Paint#createContext specification} of the
+     * method in the {@link Paint} interface for information
+     * on null parameter handling.
+     *
+     * @param cm the preferred {@link ColorModel} which represents the most convenient
+     *           format for the caller to receive the pixel data, or {@code null}
+     *           if there is no preference.
+     * @param r the device space bounding box
+     *                     of the graphics primitive being rendered.
+     * @param r2d the user space bounding box
+     *                   of the graphics primitive being rendered.
+     * @param xform the {@link AffineTransform} from user
+     *              space into device space.
+     * @param hints the set of hints that the context object can use to
+     *              choose between rendering alternatives.
+     * @return the {@code PaintContext} for
+     *         generating color patterns.
      * @see Paint
      * @see PaintContext
-     * @see Graphics2D#setPaint
+     * @see ColorModel
+     * @see Rectangle
+     * @see Rectangle2D
+     * @see AffineTransform
+     * @see RenderingHints
      */
     public synchronized PaintContext createContext(ColorModel cm, Rectangle r,
                                                    Rectangle2D r2d,

src/share/classes/java/awt/GradientPaint.java

@@ -53,6 +53,7 @@ import java.awt.image.ColorModel;
  *
  * @see Paint
  * @see Graphics2D#setPaint
+ * @version 10 Feb 1997
  */
 
 public class GradientPaint implements Paint {
@@ -223,19 +224,32 @@ public class GradientPaint implements Paint {
     }
 
     /**
-     * Creates and returns a context used to generate the color pattern.
-     * @param cm {@link ColorModel} that receives
-     * the <code>Paint</code> data. This is used only as a hint.
-     * @param deviceBounds the device space bounding box of the
-     * graphics primitive being rendered
-     * @param userBounds the user space bounding box of the
-     * graphics primitive being rendered
+     * Creates and returns a {@link PaintContext} used to
+     * generate a linear color gradient pattern.
+     * See the {@link Paint#createContext specification} of the
+     * method in the {@link Paint} interface for information
+     * on null parameter handling.
+     *
+     * @param cm the preferred {@link ColorModel} which represents the most convenient
+     *           format for the caller to receive the pixel data, or {@code null}
+     *           if there is no preference.
+     * @param deviceBounds the device space bounding box
+     *                     of the graphics primitive being rendered.
+     * @param userBounds the user space bounding box
+     *                   of the graphics primitive being rendered.
      * @param xform the {@link AffineTransform} from user
-     *     space into device space
-     * @param hints the hints that the context object uses to choose
-     * between rendering alternatives
-     * @return the {@link PaintContext} that generates color patterns.
+     *              space into device space.
+     * @param hints the set of hints that the context object can use to
+     *              choose between rendering alternatives.
+     * @return the {@code PaintContext} for
+     *         generating color patterns.
+     * @see Paint
      * @see PaintContext
+     * @see ColorModel
+     * @see Rectangle
+     * @see Rectangle2D
+     * @see AffineTransform
+     * @see RenderingHints
      */
     public PaintContext createContext(ColorModel cm,
                                       Rectangle deviceBounds,

src/share/classes/java/awt/LinearGradientPaint.java

@@ -296,7 +296,32 @@ public final class LinearGradientPaint extends MultipleGradientPaint {
     }
 
     /**
-     * {@inheritDoc}
+     * Creates and returns a {@link PaintContext} used to
+     * generate a linear color gradient pattern.
+     * See the {@link Paint#createContext specification} of the
+     * method in the {@link Paint} interface for information
+     * on null parameter handling.
+     *
+     * @param cm the preferred {@link ColorModel} which represents the most convenient
+     *           format for the caller to receive the pixel data, or {@code null}
+     *           if there is no preference.
+     * @param deviceBounds the device space bounding box
+     *                     of the graphics primitive being rendered.
+     * @param userBounds the user space bounding box
+     *                   of the graphics primitive being rendered.
+     * @param transform the {@link AffineTransform} from user
+     *              space into device space.
+     * @param hints the set of hints that the context object can use to
+     *              choose between rendering alternatives.
+     * @return the {@code PaintContext} for
+     *         generating color patterns.
+     * @see Paint
+     * @see PaintContext
+     * @see ColorModel
+     * @see Rectangle
+     * @see Rectangle2D
+     * @see AffineTransform
+     * @see RenderingHints
      */
     public PaintContext createContext(ColorModel cm,
                                       Rectangle deviceBounds,

src/share/classes/java/awt/Paint.java

@@ -46,42 +46,58 @@ import java.awt.geom.Rectangle2D;
  * @see GradientPaint
  * @see TexturePaint
  * @see Graphics2D#setPaint
+ * @version 1.36, 06/05/07
  */
 
 public interface Paint extends Transparency {
     /**
      * Creates and returns a {@link PaintContext} used to
      * generate the color pattern.
-     * Since the ColorModel argument to createContext is only a
-     * hint, implementations of Paint should accept a null argument
-     * for ColorModel.  Note that if the application does not
-     * prefer a specific ColorModel, the null ColorModel argument
-     * will give the Paint implementation full leeway in using the
-     * most efficient ColorModel it prefers for its raster processing.
-     * <p>
-     * Since the API documentation was not specific about this in
-     * releases before 1.4, there may be implementations of
-     * <code>Paint</code> that do not accept a null
-     * <code>ColorModel</code> argument.
-     * If a developer is writing code which passes a null
-     * <code>ColorModel</code> argument to the
-     * <code>createContext</code> method of <code>Paint</code>
-     * objects from arbitrary sources it would be wise to code defensively
-     * by manufacturing a non-null <code>ColorModel</code> for those
-     * objects which throw a <code>NullPointerException</code>.
-     * @param cm the {@link ColorModel} that receives the
-     * <code>Paint</code> data. This is used only as a hint.
+     * The arguments to this method convey additional information
+     * about the rendering operation that may be
+     * used or ignored on various implementations of the {@code Paint} interface.
+     * A caller must pass non-{@code null} values for all of the arguments
+     * except for the {@code ColorModel} argument which may be {@code null} to
+     * indicate that no specific {@code ColorModel} type is preferred.
+     * Implementations of the {@code Paint} interface are allowed to use or ignore
+     * any of the arguments as makes sense for their function, and are
+     * not constrained to use the specified {@code ColorModel} for the returned
+     * {@code PaintContext}, even if it is not {@code null}.
+     * Implementations are allowed to throw {@code NullPointerException} for
+     * any {@code null} argument other than the {@code ColorModel} argument,
+     * but are not required to do so.
+     *
+     * @param cm the preferred {@link ColorModel} which represents the most convenient
+     *           format for the caller to receive the pixel data, or {@code null}
+     *           if there is no preference.
      * @param deviceBounds the device space bounding box
-     *                     of the graphics primitive being rendered
+     *                     of the graphics primitive being rendered.
+     *                     Implementations of the {@code Paint} interface
+     *                     are allowed to throw {@code NullPointerException}
+     *                     for a {@code null} {@code deviceBounds}.
      * @param userBounds the user space bounding box
-     *                     of the graphics primitive being rendered
+     *                   of the graphics primitive being rendered.
+     *                     Implementations of the {@code Paint} interface
+     *                     are allowed to throw {@code NullPointerException}
+     *                     for a {@code null} {@code userBounds}.
      * @param xform the {@link AffineTransform} from user
-     *      space into device space
-     * @param hints the hint that the context object uses to
-     *              choose between rendering alternatives
-     * @return the <code>PaintContext</code> for
-     *              generating color patterns
+     *              space into device space.
+     *                     Implementations of the {@code Paint} interface
+     *                     are allowed to throw {@code NullPointerException}
+     *                     for a {@code null} {@code xform}.
+     * @param hints the set of hints that the context object can use to
+     *              choose between rendering alternatives.
+     *                     Implementations of the {@code Paint} interface
+     *                     are allowed to throw {@code NullPointerException}
+     *                     for a {@code null} {@code hints}.
+     * @return the {@code PaintContext} for
+     *         generating color patterns.
      * @see PaintContext
+     * @see ColorModel
+     * @see Rectangle
+     * @see Rectangle2D
+     * @see AffineTransform
+     * @see RenderingHints
      */
     public PaintContext createContext(ColorModel cm,
                                       Rectangle deviceBounds,

src/share/classes/java/awt/RadialGradientPaint.java

@@ -543,7 +543,31 @@ public final class RadialGradientPaint extends MultipleGradientPaint {
     }
 
     /**
-     * {@inheritDoc}
+     * Creates and returns a {@link PaintContext} used to
+     * generate a circular radial color gradient pattern.
+     * See the description of the {@link Paint#createContext createContext} method
+     * for information on null parameter handling.
+     *
+     * @param cm the preferred {@link ColorModel} which represents the most convenient
+     *           format for the caller to receive the pixel data, or {@code null}
+     *           if there is no preference.
+     * @param deviceBounds the device space bounding box
+     *                     of the graphics primitive being rendered.
+     * @param userBounds the user space bounding box
+     *                   of the graphics primitive being rendered.
+     * @param transform the {@link AffineTransform} from user
+     *              space into device space.
+     * @param hints the set of hints that the context object can use to
+     *              choose between rendering alternatives.
+     * @return the {@code PaintContext} for
+     *         generating color patterns.
+     * @see Paint
+     * @see PaintContext
+     * @see ColorModel
+     * @see Rectangle
+     * @see Rectangle2D
+     * @see AffineTransform
+     * @see RenderingHints
      */
     public PaintContext createContext(ColorModel cm,
                                       Rectangle deviceBounds,

src/share/classes/java/awt/TexturePaint.java

@@ -45,6 +45,7 @@ import java.awt.image.ColorModel;
  * replicated <code>Rectangle2D</code>.
  * @see Paint
  * @see Graphics2D#setPaint
+ * @version 1.48, 06/05/07
  */
 
 public class TexturePaint implements Paint {
@@ -93,20 +94,32 @@ public class TexturePaint implements Paint {
     }
 
     /**
-     * Creates and returns a context used to generate the color pattern.
-     * @param cm the {@link ColorModel} that receives the
-     * <code>Paint</code> data. This is used only as a hint.
-     * @param deviceBounds the device space bounding box of the graphics
-     * primitive being rendered
-     * @param userBounds the user space bounding box of the graphics
-     * primitive being rendered
-     * @param xform the {@link AffineTransform} from user space
-     *          into device space
-     * @param hints a {@link RenderingHints} object that can be used to
-     *          specify how the pattern is ultimately rendered
-     * @return the {@link PaintContext} used for generating color
-     *          patterns.
+     * Creates and returns a {@link PaintContext} used to
+     * generate a tiled image pattern.
+     * See the {@link Paint#createContext specification} of the
+     * method in the {@link Paint} interface for information
+     * on null parameter handling.
+     *
+     * @param cm the preferred {@link ColorModel} which represents the most convenient
+     *           format for the caller to receive the pixel data, or {@code null}
+     *           if there is no preference.
+     * @param deviceBounds the device space bounding box
+     *                     of the graphics primitive being rendered.
+     * @param userBounds the user space bounding box
+     *                   of the graphics primitive being rendered.
+     * @param xform the {@link AffineTransform} from user
+     *              space into device space.
+     * @param hints the set of hints that the context object can use to
+     *              choose between rendering alternatives.
+     * @return the {@code PaintContext} for
+     *         generating color patterns.
+     * @see Paint
      * @see PaintContext
+     * @see ColorModel
+     * @see Rectangle
+     * @see Rectangle2D
+     * @see AffineTransform
+     * @see RenderingHints
      */
     public PaintContext createContext(ColorModel cm,
                                       Rectangle deviceBounds,