1 /*
   2  * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javafx.collections;
  26 
  27 /**
  28  * {@code ObservableIntegerArray} is a {@code int[]} array that allows listeners
  29  * to track changes when they occur. In order to track changes, the internal
  30  * array is encapsulated and there is no direct access available from the outside.
  31  * Bulk operations are supported but they always do a copy of the data range.
  32  *
  33  * @see ArrayChangeListener
  34  * @since JavaFX 8.0
  35  */
  36 public interface ObservableIntegerArray extends ObservableArray<ObservableIntegerArray> {
  37 
  38     /**
  39      * Copies specified portion of array into {@code dest} array. Throws
  40      * the same exceptions as {@link System#arraycopy(java.lang.Object,
  41      * int, java.lang.Object, int, int) System.arraycopy()} method.
  42      * @param srcIndex starting position in the observable array
  43      * @param dest destination array
  44      * @param destIndex starting position in destination array
  45      * @param length length of portion to copy
  46      */
  47     public void copyTo(int srcIndex, int[] dest, int destIndex, int length);
  48 
  49     /**
  50      * Copies specified portion of array into {@code dest} observable array.
  51      * Throws the same exceptions as {@link System#arraycopy(java.lang.Object,
  52      * int, java.lang.Object, int, int) System.arraycopy()} method.
  53      * @param srcIndex starting position in the observable array
  54      * @param dest destination observable array
  55      * @param destIndex starting position in destination observable array
  56      * @param length length of portion to copy
  57      */
  58     public void copyTo(int srcIndex, ObservableIntegerArray dest, int destIndex, int length);
  59 
  60     /**
  61      * Gets a single value of array. This is generally as fast as direct access
  62      * to an array and eliminates necessity to make a copy of array.
  63      * @param index index of element to get
  64      * @return value at the given index
  65      * @throws ArrayIndexOutOfBoundsException if {@code index} is outside
  66      * array bounds
  67      */
  68     public int get(int index);
  69 
  70     /**
  71      * Appends given {@code elements} to the end of this array. Capacity is increased
  72      * if necessary to match the new size of the data.
  73      * @param elements elements to append
  74      */
  75     public void addAll(int... elements);
  76 
  77     /**
  78      * Appends content of a given observable array to the end of this array.
  79      * Capacity is increased if necessary to match the new size of the data.
  80      * @param src observable array with elements to append
  81      */
  82     public void addAll(ObservableIntegerArray src);
  83 
  84     /**
  85      * Appends a portion of given array to the end of this array.
  86      * Capacity is increased if necessary to match the new size of the data.
  87      * @param src source array
  88      * @param srcIndex starting position in source array
  89      * @param length length of portion to append
  90      */
  91     public void addAll(int[] src, int srcIndex, int length);
  92 
  93     /**
  94      * Appends a portion of given observable array to the end of this array.
  95      * Capacity is increased if necessary to match the new size of the data.
  96      * @param src source observable array
  97      * @param srcIndex starting position in source array
  98      * @param length length of portion to append
  99      */
 100     public void addAll(ObservableIntegerArray src, int srcIndex, int length);
 101 
 102     /**
 103      * Replaces this observable array content with given elements.
 104      * Capacity is increased if necessary to match the new size of the data.
 105      * @param elements elements to put into array content
 106      * @throws NullPointerException if {@code src} is null
 107      */
 108     public void setAll(int... elements);
 109 
 110     /**
 111      * Replaces this observable array content with a copy of portion of
 112      * a given array.
 113      * Capacity is increased if necessary to match the new size of the data.
 114      * @param src source array to copy.
 115      * @param srcIndex starting position in source observable array
 116      * @param length length of a portion to copy
 117      * @throws NullPointerException if {@code src} is null
 118      */
 119     public void setAll(int[] src, int srcIndex, int length);
 120 
 121     /**
 122      * Replaces this observable array content with a copy of given observable array.
 123      * Capacity is increased if necessary to match the new size of the data.
 124      * @param src source observable array to copy.
 125      * @throws NullPointerException if {@code src} is null
 126      */
 127     public void setAll(ObservableIntegerArray src);
 128 
 129     /**
 130      * Replaces this observable array content with a portion of a given
 131      * observable array.
 132      * Capacity is increased if necessary to match the new size of the data.
 133      * @param src source observable array to copy.
 134      * @param srcIndex starting position in source observable array
 135      * @param length length of a portion to copy
 136      * @throws NullPointerException if {@code src} is null
 137      */
 138     public void setAll(ObservableIntegerArray src, int srcIndex, int length);
 139 
 140     /**
 141      * Copies a portion of specified array into this observable array. Throws
 142      * the same exceptions as {@link System#arraycopy(java.lang.Object,
 143      * int, java.lang.Object, int, int) System.arraycopy()} method.
 144      * @param destIndex the starting destination position in this observable array
 145      * @param src source array to copy
 146      * @param srcIndex starting position in source array
 147      * @param length length of portion to copy
 148      */
 149     public void set(int destIndex, int[] src, int srcIndex, int length);
 150 
 151     /**
 152      * Copies a portion of specified observable array into this observable array.
 153      * Throws the same exceptions as {@link System#arraycopy(java.lang.Object,
 154      * int, java.lang.Object, int, int) System.arraycopy()} method.
 155      * @param destIndex the starting destination position in this observable array
 156      * @param src source observable array to copy
 157      * @param srcIndex starting position in source array
 158      * @param length length of portion to copy
 159      */
 160     public void set(int destIndex, ObservableIntegerArray src, int srcIndex, int length);
 161 
 162     /**
 163      * Sets a single value in the array. Avoid using this method if many values
 164      * are updated, use {@linkplain #set(int, int[], int, int)} update method
 165      * instead with as minimum number of invocations as possible.
 166      * @param index index of the value to set
 167      * @param value new value for the given index
 168      * @throws ArrayIndexOutOfBoundsException if {@code index} is outside
 169      * array bounds
 170      */
 171     public void set(int index, int value);
 172 
 173     /**
 174      * Returns an array containing copy of the observable array.
 175      * If the observable array fits in the specified array, it is copied therein.
 176      * Otherwise, a new array is allocated with the size of the observable array.
 177      *
 178      * @param dest the array into which the observable array to be copied,
 179      *          if it is big enough; otherwise, a new int array is allocated.
 180      *          Ignored, if null.
 181      * @return an int array containing the copy of the observable array
 182      */
 183     public int[] toArray(int[] dest);
 184 
 185     /**
 186      * Returns an array containing copy of specified portion of the observable array.
 187      * If specified portion of the observable array fits in the specified array,
 188      * it is copied therein. Otherwise, a new array of given length is allocated.
 189      *
 190      * @param srcIndex starting position in the observable array
 191      * @param dest the array into which specified portion of the observable array
 192      *          to be copied, if it is big enough;
 193      *          otherwise, a new int array is allocated.
 194      *          Ignored, if null.
 195      * @param length length of portion to copy
 196      * @return an int array containing the copy of specified portion the observable array
 197      */
 198     public int[] toArray(int srcIndex, int[] dest, int length);
 199 
 200 }