源码学习之Spliterator

以下源码摘自JDK8

public interface Spliterator<T> {
    /**
     * 如果还有剩余元素，则用action操作剩余元素，返回ture，否则返回false。
     * 如果Spliterator是顺序的，action操作的是下一个按顺序获取的元素。
     * action重复执行则抛异常
     */
    boolean tryAdvance(Consumer<? super T> action);
    
    /**
     * 对每个剩余的元素操作所给的action，在当前线程顺序执行，直到所有元素都执行过或者执行抛出异常。
     * 如果Spliterator是顺序的，action按顺序执行，action重复执行则抛异常。
     * 默认的实现方式，调用tryAdvance()方法，直到返回false。只要可能，本方法必须重写。
     */
    default void forEachRemaining(Consumer<? super T> action) {
        do { } while (tryAdvance(action));
    }
    
    /**
     * 返回一个Spliterator包含部分元素，如果不能分割，返回null值。
     * 如果Spliterator包含有限个元素，循环调用trySplit()必然最终返回null。
     */
    Spliterator<T> trySplit();
    
    /**
     * 返回一个遍历元素时的元素个数估计值，如果元素无限，则返回Long型的最大值，或unknown。
     */
    long estimateSize();
   
    /**
     * 如果Spliterator是SIZED的，返回estimateSize()的值，否则返回-1。
     */
    default long getExactSizeIfKnown() {
        return (characteristics() & SIZED) == 0 ? -1L : estimateSize();
    }

    /**
     * 返回Spliterator和其元素的一系列特征的ORed values。
     * 对于Spliterator和分割后的子Spliterator，特征可能不一致。
     * 特征集合：ORDERED，DISTINCT，SORTED，SIZED，NONNULL，IMMUTABLE，CONCURRENT
     */
    int characteristics();

    /**
     * 是否包含某个特征
     */
    default boolean hasCharacteristics(int characteristics) {
        return (characteristics() & characteristics) == characteristics;
    }

    /**
     * 如果Spliterator的源对Comparator来说是已排序的，返回该Comparator。如果是自然排序的，返回null。
     * 如果源不是已排序的，抛出异常。
     */
    default Comparator<? super T> getComparator() {
        throw new IllegalStateException();
    }

    /**
     * 有序性，如List类是有序的，Set类是无序的
     */
    public static final int ORDERED    = 0x00000010;

    /**
     * 不可重复性，如set的元素
     */
    public static final int DISTINCT   = 0x00000001;

    /**
     * 已排序性，如果实现了Comparator接口，getComparator()则返回该接口，否则返回null。
     * 含SORTED特征必然含ORDERED特征。NavigableSet和SortedSet是已排序的。
     */
    public static final int SORTED     = 0x00000004;

    /**
     * 有限大小性，大部分Collection的Spliterators是SIZED的。
     * HashSet的Sub-spliterators是非SIZED的。
     */
    public static final int SIZED      = 0x00000040;

    /**
     * 元素非null性
     */
    public static final int NONNULL    = 0x00000100;

    /**
     * 源的结构不可改变性。即元素不能添加、替换或者移除。
     */
    public static final int IMMUTABLE  = 0x00000400;

    /**
     * 并发性。元素可以在多线程中做修改而不需要而外的同步操作。
     * 最高级别的Spliterator不能同时有CONCURRENT和SIZED。这是由于有限大小的源在多线程遍历中
     * 可能改变大小。
     */
    public static final int CONCURRENT = 0x00001000;

    /**
     * 该属性意味着所有trySplit()得到的Spliterators都是SIZED
     */
    public static final int SUBSIZED = 0x00004000;

    /**
     * @param <T> 基本数据类型的包装类，如Integer
     * @param <T_CONS> 基本数据类型的消费者类，如IntConsumer
     * @param <T_SPLITR> Spliterator下的基本类型对应类，如Spliterator.OfInt
     */
    public interface OfPrimitive<T, T_CONS, T_SPLITR extends Spliterator.OfPrimitive<T, T_CONS, T_SPLITR>>
            extends Spliterator<T> {
        @Override
        T_SPLITR trySplit();
      
        @SuppressWarnings("overloads")
        boolean tryAdvance(T_CONS action);
       
        @SuppressWarnings("overloads")
        default void forEachRemaining(T_CONS action) {
            do { } while (tryAdvance(action));
        }
    }

    public interface OfInt extends OfPrimitive<Integer, IntConsumer, OfInt> {

        @Override
        OfInt trySplit();

        @Override
        boolean tryAdvance(IntConsumer action);

        @Override
        default void forEachRemaining(IntConsumer action) {
            do { } while (tryAdvance(action));
        }

        @Override
        default boolean tryAdvance(Consumer<? super Integer> action) {
            if (action instanceof IntConsumer) {
                return tryAdvance((IntConsumer) action);
            }
            else {
                if (Tripwire.ENABLED)
                    Tripwire.trip(getClass(),
                            "{0} calling Spliterator.OfInt.tryAdvance((IntConsumer) action::accept)");
                return tryAdvance((IntConsumer) action::accept);
            }
        }
        
        @Override
        default void forEachRemaining(Consumer<? super Integer> action) {
            if (action instanceof IntConsumer) {
                forEachRemaining((IntConsumer) action);
            }
            else {
                if (Tripwire.ENABLED)
                    Tripwire.trip(getClass(),
                            "{0} calling Spliterator.OfInt.forEachRemaining((IntConsumer) action::accept)");
                forEachRemaining((IntConsumer) action::accept);
            }
        }
    }

  
    public interface OfLong extends OfPrimitive<Long, LongConsumer, OfLong> {

        @Override
        OfLong trySplit();

        @Override
        boolean tryAdvance(LongConsumer action);

        @Override
        default void forEachRemaining(LongConsumer action) {
            do { } while (tryAdvance(action));
        }

        
        @Override
        default boolean tryAdvance(Consumer<? super Long> action) {
            if (action instanceof LongConsumer) {
                return tryAdvance((LongConsumer) action);
            }
            else {
                if (Tripwire.ENABLED)
                    Tripwire.trip(getClass(),
                            "{0} calling Spliterator.OfLong.tryAdvance((LongConsumer) action::accept)");
                return tryAdvance((LongConsumer) action::accept);
            }
        }

        
        @Override
        default void forEachRemaining(Consumer<? super Long> action) {
            if (action instanceof LongConsumer) {
                forEachRemaining((LongConsumer) action);
            }
            else {
                if (Tripwire.ENABLED)
                    Tripwire.trip(getClass(),
                            "{0} calling Spliterator.OfLong.forEachRemaining((LongConsumer) action::accept)");
                forEachRemaining((LongConsumer) action::accept);
            }
        }
    }

  
    public interface OfDouble extends OfPrimitive<Double, DoubleConsumer, OfDouble> {

        @Override
        OfDouble trySplit();

        @Override
        boolean tryAdvance(DoubleConsumer action);

        @Override
        default void forEachRemaining(DoubleConsumer action) {
            do { } while (tryAdvance(action));
        }

        
        @Override
        default boolean tryAdvance(Consumer<? super Double> action) {
            if (action instanceof DoubleConsumer) {
                return tryAdvance((DoubleConsumer) action);
            }
            else {
                if (Tripwire.ENABLED)
                    Tripwire.trip(getClass(),
                            "{0} calling Spliterator.OfDouble.tryAdvance((DoubleConsumer) action::accept)");
                return tryAdvance((DoubleConsumer) action::accept);
            }
        }

       
        @Override
        default void forEachRemaining(Consumer<? super Double> action) {
            if (action instanceof DoubleConsumer) {
                forEachRemaining((DoubleConsumer) action);
            }
            else {
                if (Tripwire.ENABLED)
                    Tripwire.trip(getClass(),
                            "{0} calling Spliterator.OfDouble.forEachRemaining((DoubleConsumer) action::accept)");
                forEachRemaining((DoubleConsumer) action::accept);
            }
        }
    }
}