1 /*
   2  * Copyright (c) 2010, 2015, 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 }