Summary

Specify that methods on java.awt.SampleModel that accept a width and height will throw an exception if either of these is negative.

Problem

There is unspecified behaviour for negative width or height arguments passed to methods of java.awt.image.SampleModel , such as getPixels(..), setPixels(..), getSamples(...), setSamples(..). The sub-classes also do not specify it. Also the actual behaviour is that sometimes you get an exception and sometimes no exception is thrown, and instead no data is transferred and an uninitialized array of non-zero length may be returned.

Solution

Consistently specify an exception will be thrown and update the implementation to ensure this. At the same time - make use of {@inheritDoc} so that sub-classes have the same doc as the - add some missing documentation of NullPointerException - fix some typos where the term "output" is used and it should have been "input"

Specification

package java.awt.image
public abstract class SampleModel 

-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if iArray is too small to hold the output.
+     * not in bounds, or if {@code iArray} is too small to hold the output.
      */
     public int[] getPixel(int x, int y, int[] iArray, DataBuffer data) 

-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
      * not in bounds, or if obj is too small to hold the output.
      */
     public abstract Object getDataElements(int x, int y,
                                            Object obj, DataBuffer data);

-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if obj is too small to hold the output.
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code obj} is too small to hold the output.
      */
     public Object getDataElements(int x, int y, int w, int h,
                                   Object obj, DataBuffer data)

-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
      * not in bounds, or if obj is too small to hold the input.
      */
     public abstract void setDataElements(int x, int y,
                                          Object obj, DataBuffer data)

-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
      * not in bounds, or if obj is too small to hold the input.
      */
     public void setDataElements(int x, int y, int w, int h,
                                 Object obj, DataBuffer data) 


-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if fArray is too small to hold the output.
+     * not in bounds, or if {@code fArray} is too small to hold the output.
      */
     public float[] getPixel(int x, int y, float[] fArray,
                             DataBuffer data)

-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if dArray is too small to hold the output.
+     * not in bounds, or if {@code dArray} is too small to hold the output.
      */
     public double[] getPixel(int x, int y, double[] dArray,
                              DataBuffer data)
      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if iArray is too small to hold the output.
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code iArray} is too small to hold the output.
      */
     public int[] getPixels(int x, int y, int w, int h,
                            int[] iArray, DataBuffer data)
      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if fArray is too small to hold the output.
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code fArray} is too small to hold the output.
      */
     public float[] getPixels(int x, int y, int w, int h,
                              float[] fArray, DataBuffer data)


      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if dArray is too small to hold the output.
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code dArray} is too small to hold the output.
      */
     public double[] getPixels(int x, int y, int w, int h,
                               double[] dArray, DataBuffer data) 
      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
      * the band index are not in bounds.
      */
     public abstract int getSample(int x, int y, int b, DataBuffer data);


-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
      * the band index are not in bounds.
      */
     public float getSampleFloat(int x, int y, int b, DataBuffer data) 
      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
      * the band index are not in bounds.
      */
     public double getSampleDouble(int x, int y, int b, DataBuffer data) 
      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
-     * the band index are not in bounds, or if iArray is too small to
-     * hold the output.
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the output.
      */
     public int[] getSamples(int x, int y, int w, int h, int b,
                             int[] iArray, DataBuffer data) 
      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
-     * the band index are not in bounds, or if fArray is too small to
-     * hold the output.
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the output.
      */
     public float[] getSamples(int x, int y, int w, int h,
                               int b, float[] fArray,
                               DataBuffer data) 
      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
-     * the band index are not in bounds, or if dArray is too small to
-     * hold the output.
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code dArray} is too small to hold the output.
      */
     public double[] getSamples(int x, int y, int w, int h,
                                int b, double[] dArray,
                                DataBuffer data) 
      *
-     * @throws NullPointerException if iArray or data is null.
+     * @throws NullPointerException if {@code iArray} or {code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if iArray is too small to hold the input.
+     * not in bounds, or if {@code iArray} is too small to hold the input.
      */
     public void setPixel(int x, int y, int[] iArray, DataBuffer data) 
      *
-     * @throws NullPointerException if fArray or data is null.
+     * @throws NullPointerException if {@code fArray} or {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if fArray is too small to hold the input.
+     * not in bounds, or if {@code fArray} is too small to hold the input.
      */
     public void setPixel(int x, int y, float[] fArray, DataBuffer data) 
      *
-     * @throws NullPointerException if dArray or data is null.
+     * @throws NullPointerException if {@code dArray} or {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if fArray is too small to hold the input.
+     * not in bounds, or if {@code dArray} is too small to hold the input.
      */
     public void setPixel(int x, int y, double[] dArray, DataBuffer data) 
      *
-     * @throws NullPointerException if iArray or data is null.
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if iArray is too small to hold the input.
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code iArray} is too small to hold the input.
      */
     public void setPixels(int x, int y, int w, int h,
                           int[] iArray, DataBuffer data) 
      *
-     * @throws NullPointerException if fArray or data is null.
+     * @throws NullPointerException if {@code fArray} or {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if fArray is too small to hold the input.
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code fArray} is too small to hold the input.
      */
     public void setPixels(int x, int y, int w, int h,
                           float[] fArray, DataBuffer data) 
      *
-     * @throws NullPointerException if dArray or data is null.
+     * @throws NullPointerException if {@code dArray} or {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if dArray is too small to hold the input.
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code dArray} is too small to hold the input.
      */
     public void setPixels(int x, int y, int w, int h,
                           double[] dArray, DataBuffer data) 
      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
      * the band index are not in bounds.
      */
     public abstract void setSample(int x, int y, int b,
                                    int s,

      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
      * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b,
                           float s ,

      *
-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
      * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b,
                           double s,

      *
-     * @throws NullPointerException if iArray or data is null.
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
-     * the band index are not in bounds, or if iArray is too small to
-     * hold the input.
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the input.
      */
     public void setSamples(int x, int y, int w, int h, int b,
                            int[] iArray, DataBuffer data) {

      *
-     * @throws NullPointerException if fArray or data is null.
+     * @throws NullPointerException if {@code fArray} or {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
-     * the band index are not in bounds, or if fArray is too small to
-     * hold the input.
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code fArray} is too small to hold the input.
      */
     public void setSamples(int x, int y, int w, int h, int b,
                            float[] fArray, DataBuffer data) 
      *
-     * @throws NullPointerException if dArray or data is null.
+     * @throws NullPointerException if {@code dArray} or {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates or
-     * the band index are not in bounds, or if dArray is too small to
-     * hold the input.
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code dArray} is too small to hold the input.
      */
     public void setSamples(int x, int y, int w, int h, int b,
                            double[] dArray, DataBuffer data) 



public class ComponentSampleModel extends SampleModel
 


-     * @throws NullPointerException if data is null.
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
      * not in bounds, or if obj is too small to hold the output.
      */
     public Object getDataElements(int x, int y, Object obj, DataBuffer data) 

     /**
-     * Returns all samples for the specified pixel in an int array,
-     * one sample per array element.
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if
-     * the coordinates are not in bounds.
-     * @param x         the X coordinate of the pixel location
-     * @param y         the Y coordinate of the pixel location
-     * @param iArray    If non-null, returns the samples in this array
-     * @param data      The DataBuffer containing the image data
-     * @return the samples of the specified pixel.
-     * @see #setPixel(int, int, int[], DataBuffer)
-     *
-     * @throws NullPointerException if data is null.
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
      * @throws ArrayIndexOutOfBoundsException if the coordinates are
-     * not in bounds, or if iArray is too small to hold the output.
+     * not in bounds, or if {@code iArray} is too small to hold the output.
      */
     public int[] getPixel(int x, int y, int[] iArray, DataBuffer data) 

     /**
-     * Returns all samples for the specified rectangle of pixels in
-     * an int array, one sample per array element.
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if
-     * the coordinates are not in bounds.
-     * @param x         The X coordinate of the upper left pixel location
-     * @param y         The Y coordinate of the upper left pixel location
-     * @param w         The width of the pixel rectangle
-     * @param h         The height of the pixel rectangle
-     * @param iArray    If non-null, returns the samples in this array
-     * @param data      The DataBuffer containing the image data
-     * @return the samples of the pixels within the specified region.
-     * @see #setPixels(int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code iArray} is too small to hold the output.
      */
     public int[] getPixels(int x, int y, int w, int h,
                            int[] iArray, DataBuffer data)

     /**
-     * Returns as int the sample in a specified band for the pixel
-     * located at (x,y).
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if
-     * the coordinates are not in bounds.
-     * @param x         the X coordinate of the pixel location
-     * @param y         the Y coordinate of the pixel location
-     * @param b         the band to return
-     * @param data      the {@code DataBuffer} containing the image data
-     * @return the sample in a specified band for the specified pixel
-     * @see #setSample(int, int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public int getSample(int x, int y, int b, DataBuffer data) 

     /**
-     * Returns the sample in a specified band
-     * for the pixel located at (x,y) as a float.
-     * An {@code ArrayIndexOutOfBoundsException} might be
-     * thrown if the coordinates are not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to return
-     * @param data      The DataBuffer containing the image data
-     * @return a float value representing the sample in the specified
-     * band for the specified pixel.
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public float getSampleFloat(int x, int y, int b, DataBuffer data) 

     /**
-     * Returns the sample in a specified band
-     * for a pixel located at (x,y) as a double.
-     * An {@code ArrayIndexOutOfBoundsException} might be
-     * thrown if the coordinates are not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to return
-     * @param data      The DataBuffer containing the image data
-     * @return a double value representing the sample in the specified
-     * band for the specified pixel.
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public double getSampleDouble(int x, int y, int b, DataBuffer data) 

     /**
-     * Returns the samples in a specified band for the specified rectangle
-     * of pixels in an int array, one sample per data array element.
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if
-     * the coordinates are not in bounds.
-     * @param x         The X coordinate of the upper left pixel location
-     * @param y         The Y coordinate of the upper left pixel location
-     * @param w         the width of the pixel rectangle
-     * @param h         the height of the pixel rectangle
-     * @param b         the band to return
-     * @param iArray    if non-{@code null}, returns the samples
-     *                  in this array
-     * @param data      the {@code DataBuffer} containing the image data
-     * @return the samples in the specified band of the specified pixel
-     * @see #setSamples(int, int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the output.
      */
     public int[] getSamples(int x, int y, int w, int h, int b,
                             int[] iArray, DataBuffer data) 


+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if obj is too small to hold the input.
      */
     public void setDataElements(int x, int y, Object obj, DataBuffer data) 

     /**
-     * Sets a pixel in the {@code DataBuffer} using an int array of
-     * samples for input.  An {@code ArrayIndexOutOfBoundsException}
-     * might be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param iArray    The input samples in an int array
-     * @param data      The DataBuffer containing the image data
-     * @see #getPixel(int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code iArray} is too small to hold the input.
      */
     public void setPixel(int x, int y, int[] iArray, DataBuffer data) 

     /**
-     * Sets all samples for a rectangle of pixels from an int array containing
-     * one sample per array element.
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if the
-     * coordinates are not in bounds.
-     * @param x         The X coordinate of the upper left pixel location
-     * @param y         The Y coordinate of the upper left pixel location
-     * @param w         The width of the pixel rectangle
-     * @param h         The height of the pixel rectangle
-     * @param iArray    The input samples in an int array
-     * @param data      The DataBuffer containing the image data
-     * @see #getPixels(int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code iArray} is too small to hold the input.
      */
     public void setPixels(int x, int y, int w, int h,
                           int[] iArray, DataBuffer data) 

     /**
-     * Sets a sample in the specified band for the pixel located at (x,y)
-     * in the {@code DataBuffer} using an int for input.
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if the
-     * coordinates are not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         the band to set
-     * @param s         the input sample as an int
-     * @param data      the DataBuffer containing the image data
-     * @see #getSample(int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b, int s,
                           DataBuffer data) 

     /**
-     * Sets a sample in the specified band for the pixel located at (x,y)
-     * in the {@code DataBuffer} using a float for input.
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if
-     * the coordinates are not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to set
-     * @param s         The input sample as a float
-     * @param data      The DataBuffer containing the image data
-     * @see #getSample(int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b,
                           float s ,
                           DataBuffer data) {

     /**
-     * Sets a sample in the specified band for the pixel located at (x,y)
-     * in the {@code DataBuffer} using a double for input.
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if
-     * the coordinates are not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to set
-     * @param s         The input sample as a double
-     * @param data      The DataBuffer containing the image data
-     * @see #getSample(int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b,
                           double s,
                           DataBuffer data)

     /**
-     * Sets the samples in the specified band for the specified rectangle
-     * of pixels from an int array containing one sample per data array element.
-     * An {@code ArrayIndexOutOfBoundsException} might be thrown if the
-     * coordinates are not in bounds.
-     * @param x         The X coordinate of the upper left pixel location
-     * @param y         The Y coordinate of the upper left pixel location
-     * @param w         The width of the pixel rectangle
-     * @param h         The height of the pixel rectangle
-     * @param b         The band to set
-     * @param iArray    The input samples in an int array
-     * @param data      The DataBuffer containing the image data
-     * @see #getSamples(int, int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the input.
      */
     public void setSamples(int x, int y, int w, int h, int b,
                            int[] iArray, DataBuffer data)


public class BandedSampleModel extends ComponentSampleModel


+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code obj} is too small to hold the output.
      */
     public Object getDataElements(int x, int y, Object obj, DataBuffer data) {

     /**
-     * Returns all samples for the specified pixel in an int array.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param iArray    If non-null, returns the samples in this array
-     * @param data      The DataBuffer containing the image data
-     * @return the samples for the specified pixel.
-     * @see #setPixel(int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code iArray} is too small to hold the output.
      */
     public int[] getPixel(int x, int y, int[] iArray, DataBuffer data)

     /**
-     * Returns all samples for the specified rectangle of pixels in
-     * an int array, one sample per data array element.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the upper left pixel location
-     * @param y         The Y coordinate of the upper left pixel location
-     * @param w         The width of the pixel rectangle
-     * @param h         The height of the pixel rectangle
-     * @param iArray    If non-null, returns the samples in this array
-     * @param data      The DataBuffer containing the image data
-     * @return the samples for the pixels within the specified region.
-     * @see #setPixels(int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or {@code w} or {@code h} is negative.
+     * or if {@code iArray} is too small to hold the output.
      */
     public int[] getPixels(int x, int y, int w, int h,
                            int[] iArray, DataBuffer data)


     /**
-     * Returns as int the sample in a specified band for the pixel
-     * located at (x,y).
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to return
-     * @param data      The DataBuffer containing the image data
-     * @return the sample in the specified band for the specified pixel.
-     * @see #setSample(int, int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public int getSample(int x, int y, int b, DataBuffer data)

     /**
-     * Returns the sample in a specified band
-     * for the pixel located at (x,y) as a float.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to return
-     * @param data      The DataBuffer containing the image data
-     * @return a float value that represents the sample in the specified
-     * band for the specified pixel.
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public float getSampleFloat(int x, int y, int b, DataBuffer data) 

     /**
-     * Returns the sample in a specified band
-     * for a pixel located at (x,y) as a double.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to return
-     * @param data      The DataBuffer containing the image data
-     * @return a double value that represents the sample in the specified
-     * band for the specified pixel.
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */

     public double getSampleDouble(int x, int y, int b, DataBuffer data) 
     /**
-     * Returns the samples in a specified band for the specified rectangle
-     * of pixels in an int array, one sample per data array element.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the upper left pixel location
-     * @param y         The Y coordinate of the upper left pixel location
-     * @param w         The width of the pixel rectangle
-     * @param h         The height of the pixel rectangle
-     * @param b         The band to return
-     * @param iArray    If non-null, returns the samples in this array
-     * @param data      The DataBuffer containing the image data
-     * @return the samples in the specified band for the pixels within
-     * the specified region.
-     * @see #setSamples(int, int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the output.
      */
     public int[] getSamples(int x, int y, int w, int h, int b,
                             int[] iArray, DataBuffer data)

      * @param y         The Y coordinate of the pixel location
      * @param obj       If non-null, returns the primitive array in this
      *                  object
      * @param data      The DataBuffer containing the image data
      * @see #getDataElements(int, int, Object, DataBuffer)
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code obj} is too small to hold the input.
      */
     public void setDataElements(int x, int y, Object obj, DataBuffer data) 

     /**
-     * Sets a pixel in the DataBuffer using an int array of samples for input.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param iArray    The input samples in an int array
-     * @param data      The DataBuffer containing the image data
-     * @see #getPixel(int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code iArray} is too small to hold the input.
      */
     public void setPixel(int x, int y, int[] iArray, DataBuffer data) 

     /**
-     * Sets all samples for a rectangle of pixels from an int array containing
-     * one sample per array element.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the upper left pixel location
-     * @param y         The Y coordinate of the upper left pixel location
-     * @param w         The width of the pixel rectangle
-     * @param h         The height of the pixel rectangle
-     * @param iArray    The input samples in an int array
-     * @param data      The DataBuffer containing the image data
-     * @see #getPixels(int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or {@code w} or {@code h} is negative.
+     * or if {@code iArray} is too small to hold the input.
      */
     public void setPixels(int x, int y, int w, int h,
                           int[] iArray, DataBuffer data) 



     /**
-     * Sets a sample in the specified band for the pixel located at (x,y)
-     * in the DataBuffer using an int for input.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to set
-     * @param s         The input sample as an int
-     * @param data      The DataBuffer containing the image data
-     * @see #getSample(int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b, int s,
                           DataBuffer data) {

     /**
-     * Sets a sample in the specified band for the pixel located at (x,y)
-     * in the DataBuffer using a float for input.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to set
-     * @param s         The input sample as a float
-     * @param data      The DataBuffer containing the image data
-     * @see #getSample(int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b,
                           float s ,
                           DataBuffer data) 

     /**
-     * Sets a sample in the specified band for the pixel located at (x,y)
-     * in the DataBuffer using a double for input.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location
-     * @param y         The Y coordinate of the pixel location
-     * @param b         The band to set
-     * @param s         The input sample as a double
-     * @param data      The DataBuffer containing the image data
-     * @see #getSample(int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b,
                           double s,
                           DataBuffer data)

     /**
-     * Sets the samples in the specified band for the specified rectangle
-     * of pixels from an int array containing one sample per data array element.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the upper left pixel location
-     * @param y         The Y coordinate of the upper left pixel location
-     * @param w         The width of the pixel rectangle
-     * @param h         The height of the pixel rectangle
-     * @param b         The band to set
-     * @param iArray    The input sample array
-     * @param data      The DataBuffer containing the image data
-     * @see #getSamples(int, int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the input.
      */
     public void setSamples(int x, int y, int w, int h, int b,
                            int[] iArray, DataBuffer data) 

public class MultiPixelPackedSampleModel extends SampleModel

-     * @param b         the band to return, which is assumed to be 0
+     * @param b         the band to return, which must be 0
      public int getSample(int x, int y, int b, DataBuffer data);

-     * @param b the band to return, which is assumed to be 0
+     * @param b the band to set, which must be 0
     public void setSample(int x, int y, int b, int s, DataBuffer data)

+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {code obj} is too small to hold the output.
      */
     public Object getDataElements(int x, int y, Object obj, DataBuffer data) 

      * @throws ArrayIndexOutOfBoundsException if the coordinates
-     *  are not in bounds
+     * are not in bounds, or if {@code iArray} is too small to hold the output.
      * @see #setPixel(int, int, int[], DataBuffer)
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code iArray} is too small to hold the output.
      */
     public int[] getPixel(int x, int y, int[] iArray, DataBuffer data) 


+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code obj} is too small to hold the input.
      */
     public void setDataElements(int x, int y, Object obj, DataBuffer data) 

+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code iArray} is too small to hold the input.
      */
     public void setPixel(int x, int y, int[] iArray, DataBuffer data)


public class SinglePixelPackedSampleModel extends SampleModel


+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if obj is too small to hold the output.
      */
     public Object getDataElements(int x, int y, Object obj, DataBuffer data) 

     /**
-     * Returns all samples in for the specified pixel in an int array.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location.
-     * @param y         The Y coordinate of the pixel location.
-     * @param iArray    If non-null, returns the samples in this array
-     * @param data      The DataBuffer containing the image data.
-     * @return all samples for the specified pixel.
-     * @see #setPixel(int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code iArray} is too small to hold the output.
      */
     public int [] getPixel(int x, int y, int[] iArray, DataBuffer dat{
     /**
-     * Returns all samples for the specified rectangle of pixels in
-     * an int array, one sample per array element.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the upper left pixel location.
-     * @param y         The Y coordinate of the upper left pixel location.
-     * @param w         The width of the pixel rectangle.
-     * @param h         The height of the pixel rectangle.
-     * @param iArray    If non-null, returns the samples in this array.
-     * @param data      The DataBuffer containing the image data.
-     * @return all samples for the specified region of pixels.
-     * @see #setPixels(int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code iArray} is too small to hold the output.
      */
+    @Override
     public int[] getPixels(int x, int y, int w, int h,
                            int[] iArray, DataBuffer data) 

     /**
-     * Returns as int the sample in a specified band for the pixel
-     * located at (x,y).
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location.
-     * @param y         The Y coordinate of the pixel location.
-     * @param b         The band to return.
-     * @param data      The DataBuffer containing the image data.
-     * @return the sample in a specified band for the specified
-     *         pixel.
-     * @see #setSample(int, int, int, int, DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public int getSample(int x, int y, int b, DataBuffer data) 

     /**
-     * Returns the samples for a specified band for the specified rectangle
-     * of pixels in an int array, one sample per array element.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the upper left pixel location.
-     * @param y         The Y coordinate of the upper left pixel location.
-     * @param w         The width of the pixel rectangle.
-     * @param h         The height of the pixel rectangle.
-     * @param b         The band to return.
-     * @param iArray    If non-null, returns the samples in this array.
-     * @param data      The DataBuffer containing the image data.
-     * @return the samples for the specified band for the specified
-     *         region of pixels.
-     * @see #setSamples(int, int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the output.
      */
     public int[] getSamples(int x, int y, int w, int h, int b,
                            int[] iArray, DataBuffer data) 

+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if obj is too small to hold the input.
      */
     public void setDataElements(int x, int y, Object obj, DataBuffer data) 

     /**
-     * Sets a pixel in the DataBuffer using an int array of samples for input.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location.
-     * @param y         The Y coordinate of the pixel location.
-     * @param iArray    The input samples in an int array.
-     * @param data      The DataBuffer containing the image data.
-     * @see #getPixel(int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or if {@code iArray} is too small to hold the input.
      */
     public void setPixel(int x, int y,
                          int[] iArray,
                          DataBuffer data)


     /**
-     * Sets all samples for a rectangle of pixels from an int array containing
-     * one sample per array element.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the upper left pixel location.
-     * @param y         The Y coordinate of the upper left pixel location.
-     * @param w         The width of the pixel rectangle.
-     * @param h         The height of the pixel rectangle.
-     * @param iArray    The input samples in an int array.
-     * @param data      The DataBuffer containing the image data.
-     * @see #getPixels(int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates are
+     * not in bounds, or {@code w} or {@code h} is negative
+     * or if {@code iArray} is too small to hold the input.
      */
     public void setPixels(int x, int y, int w, int h,
                           int[] iArray, DataBuffer data) 

-    /**
-     * Sets a sample in the specified band for the pixel located at (x,y)
-     * in the DataBuffer using an int for input.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the pixel location.
-     * @param y         The Y coordinate of the pixel location.
-     * @param b         The band to set.
-     * @param s         The input sample as an int.
-     * @param data      The DataBuffer containing the image data.
-     * @see #getSample(int, int, int, DataBuffer)
+    /*
+     * {inheritDoc}
+     * @throws NullPointerException if {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * the band index are not in bounds.
      */
     public void setSample(int x, int y, int b, int s,
                           DataBuffer data) 
     /**
-     * Sets the samples in the specified band for the specified rectangle
-     * of pixels from an int array containing one sample per array element.
-     * ArrayIndexOutOfBoundsException may be thrown if the coordinates are
-     * not in bounds.
-     * @param x         The X coordinate of the upper left pixel location.
-     * @param y         The Y coordinate of the upper left pixel location.
-     * @param w         The width of the pixel rectangle.
-     * @param h         The height of the pixel rectangle.
-     * @param b         The band to set.
-     * @param iArray    The input samples in an int array.
-     * @param data      The DataBuffer containing the image data.
-     * @see #getSamples(int, int, int, int, int, int[], DataBuffer)
+     * {@inheritDoc}
+     * @throws NullPointerException if {@code iArray} or {@code data} is null.
+     * @throws ArrayIndexOutOfBoundsException if the coordinates or
+     * band index are not in bounds, or {@code w} or {@code h} is negative,
+     * or if {@code iArray} is too small to hold the input.
      */
     public void setSamples(int x, int y, int w, int h, int b,
                           int[] iArray, DataBuffer data)