changeset 3780:4b1badcc613c

Fix for RT-30418 Fix ObservableArray, ObservableIntegerArray and ObservableFloatArray javadocs. Added some tests to enforce statements from javadocs.
author Alexander Kouznetsov
date Fri, 31 May 2013 15:21:09 -0700
parents e15e5f07eef3
children beec262373cc
files javafx-beans/src/javafx/collections/ObservableArray.java javafx-beans/src/javafx/collections/ObservableFloatArray.java javafx-beans/src/javafx/collections/ObservableIntegerArray.java javafx-beans/test/javafx/collections/ObservableArrayTest.java
diffstat 4 files changed, 258 insertions(+), 54 deletions(-) [+]
line wrap: on
line diff
--- a/javafx-beans/src/javafx/collections/ObservableArray.java	Fri May 31 14:31:54 2013 -0700
+++ b/javafx-beans/src/javafx/collections/ObservableArray.java	Fri May 31 15:21:09 2013 -0700
@@ -27,15 +27,15 @@
 import javafx.beans.Observable;
 
 /**
- * An array that allows listeners to track changes when they occur. To achieve
- * that internal array is encapsulated and there is no direct access available
- * from outside. Bulk operations are supported but they always do copy of the 
- * data range. You can find them in subclasses as they deal with primitive
- * arrays directly.
+ * {@code ObservableArray} is an array that allows listeners to track changes
+ * when they occur. In order to track changes, the internal array
+ * is encapsulated and there is no direct access available from the outside.
+ * Bulk operations are supported but they always do a copy of the data range.
+ * You can find them in subclasses as they deal with primitive arrays directly.
  *
- * Implementations have both {@code capacity} which is internal array length
- * and {@code size}. If size needs to be increased beyond capacity the capacity
- * increases to match that new size. Use {@link #trimToSize() } method
+ * <p>Implementations have both {@code capacity}, which is internal array length,
+ * and {@code size}. If size needs to be increased beyond capacity, the capacity
+ * increases to match that new size. Use {@link #trimToSize()} method
  * to shrink it.
  * 
  * @see ArrayChangeListener
@@ -47,38 +47,44 @@
     /**
      * Add a listener to this observable array.
      * @param listener the listener for listening to the array changes
+     * @throws NullPointerException if {@code listener} is {@code null}
      */    
     public void addListener(ArrayChangeListener<T> listener);
 
     /**
-     * Tries to removed a listener from this observable array. If the listener is not
+     * Tries to remove a listener from this observable array. If the listener is not
      * attached to this array, nothing happens.
      * @param listener a listener to remove
+     * @throws NullPointerException if {@code listener} is {@code null}
      */    
     public void removeListener(ArrayChangeListener<T> listener);
 
     /**
-     * Sets new length of data in this array. This method ensures capacity for
-     * the new array length but never shrinks it. To avoid data copying
-     * call {@link #clear() } before setting it to new value. New elements
-     * will be set to 0.
+     * Sets new length of data in this array. This method grows capacity
+     * if necessary but never shrinks it. Resulting array will contain existing
+     * data for indexes that are less than the current size and zeroes for
+     * indexes that are greater than the current size.
+     * @param size new length of data in this array
+     * @throws NegativeArraySizeException if size is negative
      */
     public void resize(int size);
 
     /**
-     * Grows capacity if it is less then given {@code value}, does nothing if
-     * it already exceeds the {@code value}.
+     * Grows the capacity of this array if the current capacity is less than
+     * given {@code capacity}, does nothing if it already exceeds
+     * the {@code capacity}.
      * @param capacity
      */
     public void ensureCapacity(int capacity);
 
     /**
-     * Shrinks capacity to the current size of data in the array.
+     * Shrinks the capacity to the current size of data in the array.
      */
     public void trimToSize();
 
     /**
-     * Sets size of array to 0. No data removed nor capacity changes.
+     * Empties the array by resizing it to 0. Capacity is not changed.
+     * @see #trimToSize()
      */
     public void clear();
 
--- a/javafx-beans/src/javafx/collections/ObservableFloatArray.java	Fri May 31 14:31:54 2013 -0700
+++ b/javafx-beans/src/javafx/collections/ObservableFloatArray.java	Fri May 31 15:21:09 2013 -0700
@@ -25,10 +25,10 @@
 package javafx.collections;
 
 /**
- * A float[] array that allows listeners to track changes when they occur. To achieve
- * that internal array is encapsulated and there is no direct access available
- * from outside. Bulk operations are supported but they always do copy of the 
- * data range.
+ * {@code ObservableFloatArray} is a {@code float[]} array that allows listeners
+ * to track changes when they occur. In order to track changes, the internal
+ * array is encapsulated and there is no direct access available from the outside.
+ * Bulk operations are supported but they always do a copy of the data range.
  * 
  * @see ArrayChangeListener
  * @since JavaFX 8.0
@@ -38,13 +38,23 @@
     /**
      * Copies specified portion of array into {@code dest} array. Throws
      * the same exceptions as {@link System#arraycopy(java.lang.Object,
-     * int, java.lang.Object, int, int) }
+     * int, java.lang.Object, int, int) System.arraycopy()} method.
      * @param srcIndex starting position in the observable array
      * @param dest destination array
      * @param destIndex starting position in destination array
      * @param length length of portion to copy
      */
     public void copyTo(int srcIndex, float[] dest, int destIndex, int length);
+
+    /**
+     * Copies specified portion of array into {@code dest} observable array.
+     * Throws the same exceptions as {@link System#arraycopy(java.lang.Object,
+     * int, java.lang.Object, int, int) System.arraycopy()} method.
+     * @param srcIndex starting position in the observable array
+     * @param dest destination observable array
+     * @param destIndex starting position in destination observable array
+     * @param length length of portion to copy
+     */
     public void copyTo(int srcIndex, ObservableFloatArray dest, int destIndex, int length);
 
     /**
@@ -57,31 +67,96 @@
      */
     public float get(int index);
 
+    /**
+     * Appends given {@code elements} to the end of this array. Capacity is increased
+     * if necessary to match the new size of the data.
+     * @param elements elements to append
+     */
     public void addAll(float... elements);
+
+    /**
+     * Appends content of a given observable array to the end of this array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src observable array with elements to append
+     */
     public void addAll(ObservableFloatArray src);
+
+    /**
+     * Appends a portion of given array to the end of this array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source array
+     * @param srcIndex starting position in source array
+     * @param length length of portion to append
+     */
     public void addAll(float[] src, int srcIndex, int length);
+
+    /**
+     * Appends a portion of given observable array to the end of this array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source observable array
+     * @param srcIndex starting position in source array
+     * @param length length of portion to append
+     */
     public void addAll(ObservableFloatArray src, int srcIndex, int length);
 
     /**
-     * Sets observable array to a copy of given array
-     * @param elements source array to copy.
-     * @throws NullPointerException if {@code array} is null
+     * Replaces this observable array content with given elements.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param elements elements to put into array content
+     * @throws NullPointerException if {@code src} is null
      */
     public void setAll(float... elements);
+
+    /**
+     * Replaces this observable array content with a copy of portion of
+     * a given array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source array to copy.
+     * @param srcIndex starting position in source observable array
+     * @param length length of a portion to copy
+     * @throws NullPointerException if {@code src} is null
+     */
+    public void setAll(float[] src, int srcIndex, int length);
+
+    /**
+     * Replaces this observable array content with a copy of given observable array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source observable array to copy.
+     * @throws NullPointerException if {@code src} is null
+     */
     public void setAll(ObservableFloatArray src);
-    public void setAll(float[] src, int srcIndex, int length);
+
+    /**
+     * Replaces this observable array content with a portion of a given
+     * observable array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source observable array to copy.
+     * @param srcIndex starting position in source observable array
+     * @param length length of a portion to copy
+     * @throws NullPointerException if {@code src} is null
+     */
     public void setAll(ObservableFloatArray src, int srcIndex, int length);
 
     /**
-     * Sets portion of observable array to a copy of given array. Throws 
+     * Copies a portion of specified array into this observable array. Throws
      * the same exceptions as {@link System#arraycopy(java.lang.Object, 
-     * int, java.lang.Object, int, int) }
-     * @param destIndex the starting destination index in this observable array
+     * int, java.lang.Object, int, int) System.arraycopy()} method.
+     * @param destIndex the starting destination position in this observable array
      * @param src source array to copy
      * @param srcIndex starting position in source array
      * @param length length of portion to copy
      */
     public void set(int destIndex, float[] src, int srcIndex, int length);
+
+    /**
+     * Copies a portion of specified observable array into this observable array.
+     * Throws the same exceptions as {@link System#arraycopy(java.lang.Object,
+     * int, java.lang.Object, int, int) System.arraycopy()} method.
+     * @param destIndex the starting destination position in this observable array
+     * @param src source observable array to copy
+     * @param srcIndex starting position in source array
+     * @param length length of portion to copy
+     */
     public void set(int destIndex, ObservableFloatArray src, int srcIndex, int length);
 
     /**
@@ -100,7 +175,7 @@
      * If the observable array fits in the specified array, it is copied therein. 
      * Otherwise, a new array is allocated with the size of the observable array.
      *
-     * @param array the array into which the observable array to be copied, 
+     * @param dest the array into which the observable array to be copied,
      *          if it is big enough; otherwise, a new float array is allocated. 
      *          Ignored, if null.
      * @return a float array containing the copy of the observable array
--- a/javafx-beans/src/javafx/collections/ObservableIntegerArray.java	Fri May 31 14:31:54 2013 -0700
+++ b/javafx-beans/src/javafx/collections/ObservableIntegerArray.java	Fri May 31 15:21:09 2013 -0700
@@ -25,10 +25,10 @@
 package javafx.collections;
 
 /**
- * An int[] array that allows listeners to track changes when they occur. To achieve
- * that internal array is encapsulated and there is no direct access available
- * from outside. Bulk operations are supported but they always do copy of the 
- * data range.
+ * {@code ObservableIntegerArray} is a {@code int[]} array that allows listeners
+ * to track changes when they occur. In order to track changes, the internal
+ * array is encapsulated and there is no direct access available from the outside.
+ * Bulk operations are supported but they always do a copy of the data range.
  * 
  * @see ArrayChangeListener
  * @since JavaFX 8.0
@@ -38,13 +38,23 @@
     /**
      * Copies specified portion of array into {@code dest} array. Throws
      * the same exceptions as {@link System#arraycopy(java.lang.Object,
-     * int, java.lang.Object, int, int) }
+     * int, java.lang.Object, int, int) System.arraycopy()} method.
      * @param srcIndex starting position in the observable array
      * @param dest destination array
      * @param destIndex starting position in destination array
      * @param length length of portion to copy
      */
     public void copyTo(int srcIndex, int[] dest, int destIndex, int length);
+
+    /**
+     * Copies specified portion of array into {@code dest} observable array.
+     * Throws the same exceptions as {@link System#arraycopy(java.lang.Object,
+     * int, java.lang.Object, int, int) System.arraycopy()} method.
+     * @param srcIndex starting position in the observable array
+     * @param dest destination observable array
+     * @param destIndex starting position in destination observable array
+     * @param length length of portion to copy
+     */
     public void copyTo(int srcIndex, ObservableIntegerArray dest, int destIndex, int length);
 
     /**
@@ -58,43 +68,102 @@
     public int get(int index);
 
     /**
-     * Appends given {@code elements} to the end of array. Capacity is increased
+     * Appends given {@code elements} to the end of this array. Capacity is increased
      * if necessary to match the new size of the data.
-     * @param elements
+     * @param elements elements to append
      */
     public void addAll(int... elements);
+
+    /**
+     * Appends content of a given observable array to the end of this array. 
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src observable array with elements to append
+     */
     public void addAll(ObservableIntegerArray src);
+
+    /**
+     * Appends a portion of given array to the end of this array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source array
+     * @param srcIndex starting position in source array
+     * @param length length of portion to append
+     */
     public void addAll(int[] src, int srcIndex, int length);
+
+    /**
+     * Appends a portion of given observable array to the end of this array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source observable array
+     * @param srcIndex starting position in source array
+     * @param length length of portion to append
+     */
     public void addAll(ObservableIntegerArray src, int srcIndex, int length);
 
     /**
-     * Sets observable array to a copy of given array. Capacity is increased
-     * if necessary to match the new size of the data
-     * @param elements source array to copy.
-     * @throws NullPointerException if {@code array} is null
+     * Replaces this observable array content with given elements.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param elements elements to put into array content
+     * @throws NullPointerException if {@code src} is null
      */
     public void setAll(int... elements);
+
+    /**
+     * Replaces this observable array content with a copy of portion of
+     * a given array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source array to copy.
+     * @param srcIndex starting position in source observable array
+     * @param length length of a portion to copy
+     * @throws NullPointerException if {@code src} is null
+     */
     public void setAll(int[] src, int srcIndex, int length);
+
+    /**
+     * Replaces this observable array content with a copy of given observable array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source observable array to copy.
+     * @throws NullPointerException if {@code src} is null
+     */
     public void setAll(ObservableIntegerArray src);
+
+    /**
+     * Replaces this observable array content with a portion of a given
+     * observable array.
+     * Capacity is increased if necessary to match the new size of the data.
+     * @param src source observable array to copy.
+     * @param srcIndex starting position in source observable array
+     * @param length length of a portion to copy
+     * @throws NullPointerException if {@code src} is null
+     */
     public void setAll(ObservableIntegerArray src, int srcIndex, int length);
 
     /**
-     * Sets portion of observable array to a copy of given array. Throws 
+     * Copies a portion of specified array into this observable array. Throws
      * the same exceptions as {@link System#arraycopy(java.lang.Object, 
-     * int, java.lang.Object, int, int) }
-     * @param destIndex the starting destination index in this observable array
+     * int, java.lang.Object, int, int) System.arraycopy()} method.
+     * @param destIndex the starting destination position in this observable array
      * @param src source array to copy
      * @param srcIndex starting position in source array
      * @param length length of portion to copy
      */
     public void set(int destIndex, int[] src, int srcIndex, int length);
+
+    /**
+     * Copies a portion of specified observable array into this observable array.
+     * Throws the same exceptions as {@link System#arraycopy(java.lang.Object,
+     * int, java.lang.Object, int, int) System.arraycopy()} method.
+     * @param destIndex the starting destination position in this observable array
+     * @param src source observable array to copy
+     * @param srcIndex starting position in source array
+     * @param length length of portion to copy
+     */
     public void set(int destIndex, ObservableIntegerArray src, int srcIndex, int length);
 
     /**
      * Sets a single value in the array. Avoid using this method if many values
      * are updated, use {@linkplain #setAll(int, int[], int, int)} update method
      * instead with as minimum number of invocations as possible.
-     * @param index index of the value to setAll
+     * @param index index of the value to set
      * @param value new value for the given index
      * @throws ArrayIndexOutOfBoundsException if {@code index} is outside
      * array bounds
--- a/javafx-beans/test/javafx/collections/ObservableArrayTest.java	Fri May 31 14:31:54 2013 -0700
+++ b/javafx-beans/test/javafx/collections/ObservableArrayTest.java	Fri May 31 15:21:09 2013 -0700
@@ -32,6 +32,7 @@
 import java.util.Collection;
 import java.util.Collections;
 import java.util.List;
+import javafx.beans.InvalidationListener;
 
 import static org.junit.Assert.*;
 import org.junit.Ignore;
@@ -78,7 +79,10 @@
         abstract A toArray(A dest);
         abstract A toArray(int srcIndex, A dest, int length);
 
-        abstract A createPrimitiveArray(int size);
+        A createPrimitiveArray(int size) {
+            return createPrimitiveArray(size, true);
+        }
+        abstract A createPrimitiveArray(int size, boolean fillWithData);
         abstract A clonePrimitiveArray(A array);
         abstract int arrayLength(A array);
         abstract P get(A array, int index);
@@ -110,10 +114,12 @@
             array.set(index, value);
         }
 
-        @Override int[] createPrimitiveArray(int size) {
+        @Override int[] createPrimitiveArray(int size, boolean fillWithData) {
             int[] res = new int[size];
-            for (int i = 0; i < size; i++) {
-                res[i] = nextValue++;
+            if (fillWithData) {
+                for (int i = 0; i < size; i++) {
+                    res[i] = nextValue++;
+                }
             }
             return res;
         }
@@ -229,10 +235,12 @@
             array.set(index, value);
         }
 
-        @Override float[] createPrimitiveArray(int size) {
+        @Override float[] createPrimitiveArray(int size, boolean fillWithData) {
             float[] res = new float[size];
-            for (int i = 0; i < size; i++) {
-                res[i] = nextValue++;
+            if (fillWithData) {
+                for (int i = 0; i < size; i++) {
+                    res[i] = nextValue++;
+                }
             }
             return res;
         }
@@ -462,6 +470,50 @@
         mao.check0();
     }
 
+    @Test (expected = NullPointerException.class)
+    public void testAddNullArrayChangeListener() {
+        try {
+            array.addListener((ArrayChangeListener) null);
+        } finally {
+            mao.check0();
+            array.resize(1);
+            mao.check1();
+        }
+    }
+
+    @Test (expected = NullPointerException.class)
+    public void testAddNullInvalidationListener() {
+        try {
+            array.addListener((InvalidationListener) null);
+        } finally {
+            mao.check0();
+            array.resize(1);
+            mao.check1();
+        }
+    }
+
+    @Test (expected = NullPointerException.class)
+    public void testRemoveNullArrayChangeListener() {
+        try {
+            array.removeListener((ArrayChangeListener) null);
+        } finally {
+            mao.check0();
+            array.resize(1);
+            mao.check1();
+        }
+    }
+
+    @Test (expected = NullPointerException.class)
+    public void testRemoveNullInvalidationListener() {
+        try {
+            array.removeListener((InvalidationListener) null);
+        } finally {
+            mao.check0();
+            array.resize(1);
+            mao.check1();
+        }
+    }
+
     // ========== resize tests ==========
 
     private void testResize(boolean noChange, int newSize, int matchingElements) {
@@ -476,6 +528,8 @@
         assertEquals(newSize, array.size());
         assertEquals(newSize, wrapper.arrayLength(actual));
         wrapper.assertElementsEqual(actual, 0, matchingElements, expected, 0);
+        wrapper.assertElementsEqual(actual, matchingElements, newSize,
+                wrapper.createPrimitiveArray(Math.max(0, newSize - matchingElements)), 0);
     }
 
     @Test public void testResizeTo0() {
@@ -2189,7 +2243,7 @@
             assertUnchanged();
         }
     }
-    
+
     @Test (expected = ArrayIndexOutOfBoundsException.class)
     public void testCopyToANegativeAfterEnsureCapacity() {
         array.ensureCapacity(INITIAL_SIZE * 2);
@@ -2524,7 +2578,7 @@
         mao.reset();
 
         array.trimToSize();
-        
+
         assertUnchanged();
     }