1 /* 2 * Copyright (c) 2010, 2014, 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 26 package javafx.collections; 27 28 import java.text.Collator; 29 import java.util.Collection; 30 import java.util.Comparator; 31 import java.util.List; 32 import java.util.function.Predicate; 33 34 import javafx.beans.Observable; 35 import javafx.collections.transformation.FilteredList; 36 import javafx.collections.transformation.SortedList; 37 38 /** 39 * A list that allows listeners to track changes when they occur. 40 * 41 * @see ListChangeListener 42 * @see ListChangeListener.Change 43 * @param <E> the list element type 44 * @since JavaFX 2.0 45 */ 46 public interface ObservableList<E> extends List<E>, Observable { 47 /** 48 * Add a listener to this observable list. 49 * @param listener the listener for listening to the list changes 50 */ 51 public void addListener(ListChangeListener<? super E> listener); 52 53 /** 54 * Tries to removed a listener from this observable list. If the listener is not 55 * attached to this list, nothing happens. 56 * @param listener a listener to remove 57 */ 58 public void removeListener(ListChangeListener<? super E> listener); 59 60 /** 61 * A convenient method for var-arg adding of elements. 62 * @param elements the elements to add 63 * @return true (as specified by Collection.add(E)) 64 */ 65 public boolean addAll(E... elements); 66 67 /** 68 * Clears the ObservableList and add all the elements passed as var-args. 69 * @param elements the elements to set 70 * @return true (as specified by Collection.add(E)) 71 * @throws NullPointerException if the specified arguments contain one or more null elements 72 */ 73 public boolean setAll(E... elements); 74 75 /** 76 * Clears the ObservableList and add all elements from the collection. 77 * @param col the collection with elements that will be added to this observableArrayList 78 * @return true (as specified by Collection.add(E)) 79 * @throws NullPointerException if the specified collection contains one or more null elements 80 */ 81 public boolean setAll(Collection<? extends E> col); 82 83 /** 84 * A convenient method for var-arg usage of removaAll method. 85 * @param elements the elements to be removed 86 * @return true if list changed as a result of this call 87 */ 88 public boolean removeAll(E... elements); 89 90 /** 91 * A convenient method for var-arg usage of retain method. 92 * @param elements the elements to be retained 93 * @return true if list changed as a result of this call 94 */ 95 public boolean retainAll(E... elements); 96 97 /** 98 * Basically a shortcut to sublist(from, to).clear() 99 * As this is a common operation, ObservableList has this method for convenient usage. 100 * @param from the start of the range to remove (inclusive) 101 * @param to the end of the range to remove (exclusive) 102 * @throws IndexOutOfBoundsException if an illegal range is provided 103 */ 104 public void remove(int from, int to); 105 106 /** 107 * Creates a {@link FilteredList} wrapper of this list using 108 * the specified predicate. 109 * @param predicate the predicate to use 110 * @return new {@code FilteredList} 111 * @since JavaFX 8.0 112 */ 113 public default FilteredList<E> filtered(Predicate<E> predicate) { 114 return new FilteredList<>(this, predicate); 115 } 116 117 /** 118 * Creates a {@link SortedList} wrapper of this list using 119 * the specified comparator. 120 * @param comparator the comparator to use or null for unordered List 121 * @return new {@code SortedList} 122 * @since JavaFX 8.0 123 */ 124 public default SortedList<E> sorted(Comparator<E> comparator) { 125 return new SortedList<>(this, comparator); 126 } 127 128 /** 129 * Creates a {@link SortedList} wrapper of this list with the natural 130 * ordering. 131 * @return new {@code SortedList} 132 * @since JavaFX 8.0 133 */ 134 public default SortedList<E> sorted() { 135 Comparator naturalOrder = new Comparator<E>() { 136 137 @Override 138 public int compare(E o1, E o2) { 139 if (o1 == null && o2 == null) { 140 return 0; 141 } 142 if (o1 == null) { 143 return -1; 144 } 145 if (o2 == null) { 146 return 1; 147 } 148 149 if (o1 instanceof Comparable) { 150 return ((Comparable) o1).compareTo(o2); 151 } 152 153 return Collator.getInstance().compare(o1.toString(), o2.toString()); 154 } 155 }; 156 return sorted(naturalOrder); 157 } 158 }