Исходный код

001/*
002 * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025package javafx.collections;
026
027import javafx.beans.Observable;
028
029/**
030 * An array that allows listeners to track changes when they occur. To achieve
031 * that internal array is encapsulated and there is no direct access available
032 * from outside. Bulk operations are supported but they always do copy of the 
033 * data range. You can find them in subclasses as they deal with primitive
034 * arrays directly.
035 *
036 * Implementations have both {@code capacity} which is internal array length
037 * and {@code size}. If size needs to be increased beyond capacity the capacity
038 * increases to match that new size. Use {@link #trimToSize() } method
039 * to shrink it.
040 * 
041 * @see ArrayChangeListener
042 * @param <T> actual array instance type
043 */
044public interface ObservableArray<T extends ObservableArray<T>> extends Observable {
045
046    /**
047     * Add a listener to this observable array.
048     * @param listener the listener for listening to the array changes
049     */    
050    public void addListener(ArrayChangeListener<T> listener);
051
052    /**
053     * Tries to removed a listener from this observable array. If the listener is not
054     * attached to this array, nothing happens.
055     * @param listener a listener to remove
056     */    
057    public void removeListener(ArrayChangeListener<T> listener);
058
059    /**
060     * Sets new length of data in this array. This method ensures capacity for
061     * the new array length but never shrinks it. To avoid data copying
062     * call {@link #clear() } before setting it to new value. New elements
063     * will be set to 0.
064     */
065    public void resize(int size);
066
067    /**
068     * Grows capacity if it is less then given {@code value}, does nothing if
069     * it already exceeds the {@code value}.
070     * @param capacity
071     */
072    public void ensureCapacity(int capacity);
073
074    /**
075     * Shrinks capacity to the current size of data in the array.
076     */
077    public void trimToSize();
078
079    /**
080     * Sets size of array to 0. No data removed nor capacity changes.
081     */
082    public void clear();
083
084    /**
085     * Retrieves length of data in this array.
086     * @return length of data in this array
087     */
088    public int size();
089}