Back to index...

	/*
	* Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
	* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
	*
	* This code is free software; you can redistribute it and/or modify it
	* under the terms of the GNU General Public License version 2 only, as
	* published by the Free Software Foundation. Oracle designates this
	* particular file as subject to the "Classpath" exception as provided
	* by Oracle in the LICENSE file that accompanied this code.
	*
	* This code is distributed in the hope that it will be useful, but WITHOUT
	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	* version 2 for more details (a copy is included in the LICENSE file that
	* accompanied this code).
	*
	* You should have received a copy of the GNU General Public License version
	* 2 along with this work; if not, write to the Free Software Foundation,
	* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
	*
	* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	* or visit www.oracle.com if you need additional information or have any
	* questions.
	*/
	package java.util.stream;

	import java.util.Spliterator;
	import java.util.function.Consumer;
	import java.util.function.DoubleConsumer;
	import java.util.function.IntConsumer;
	import java.util.function.IntFunction;
	import java.util.function.LongConsumer;

	/**
	* An immutable container for describing an ordered sequence of elements of some
	* type {@code T}.
	*
	* <p>A {@code Node} contains a fixed number of elements, which can be accessed
	* via the {@link #count}, {@link #spliterator}, {@link #forEach},
	* {@link #asArray}, or {@link #copyInto} methods. A {@code Node} may have zero
	* or more child {@code Node}s; if it has no children (accessed via
	* {@link #getChildCount} and {@link #getChild(int)}, it is considered <em>flat
	* </em> or a <em>leaf</em>; if it has children, it is considered an
	* <em>internal</em> node. The size of an internal node is the sum of sizes of
	* its children.
	*
	* @apiNote
	* <p>A {@code Node} typically does not store the elements directly, but instead
	* mediates access to one or more existing (effectively immutable) data
	* structures such as a {@code Collection}, array, or a set of other
	* {@code Node}s. Commonly {@code Node}s are formed into a tree whose shape
	* corresponds to the computation tree that produced the elements that are
	* contained in the leaf nodes. The use of {@code Node} within the stream
	* framework is largely to avoid copying data unnecessarily during parallel
	* operations.
	*
	* @param <T> the type of elements.
	* @since 1.8
	*/
	interface Node<T> {

	/**
	* Returns a {@link Spliterator} describing the elements contained in this
	* {@code Node}.
	*
	* @return a {@code Spliterator} describing the elements contained in this
	* {@code Node}
	*/
	Spliterator<T> spliterator();

	/**
	* Traverses the elements of this node, and invoke the provided
	* {@code Consumer} with each element. Elements are provided in encounter
	* order if the source for the {@code Node} has a defined encounter order.
	*
	* @param consumer a {@code Consumer} that is to be invoked with each
	* element in this {@code Node}
	*/
	void forEach(Consumer<? super T> consumer);

	/**
	* Returns the number of child nodes of this node.
	*
	* @implSpec The default implementation returns zero.
	*
	* @return the number of child nodes
	*/
	default int getChildCount() {
	return 0;
	}

	/**
	* Retrieves the child {@code Node} at a given index.
	*
	* @implSpec The default implementation always throws
	* {@code IndexOutOfBoundsException}.
	*
	* @param i the index to the child node
	* @return the child node
	* @throws IndexOutOfBoundsException if the index is less than 0 or greater
	* than or equal to the number of child nodes
	*/
	default Node<T> getChild(int i) {
	throw new IndexOutOfBoundsException();
	}

	/**
	* Return a node describing a subsequence of the elements of this node,
	* starting at the given inclusive start offset and ending at the given
	* exclusive end offset.
	*
	* @param from The (inclusive) starting offset of elements to include, must
	* be in range 0..count().
	* @param to The (exclusive) end offset of elements to include, must be
	* in range 0..count().
	* @param generator A function to be used to create a new array, if needed,
	* for reference nodes.
	* @return the truncated node
	*/
	default Node<T> truncate(long from, long to, IntFunction<T[]> generator) {
	if (from == 0 && to == count())
	return this;
	Spliterator<T> spliterator = spliterator();
	long size = to - from;
	Node.Builder<T> nodeBuilder = Nodes.builder(size, generator);
	nodeBuilder.begin(size);
	for (int i = 0; i < from && spliterator.tryAdvance(e -> { }); i++) { }
	for (int i = 0; (i < size) && spliterator.tryAdvance(nodeBuilder); i++) { }
	nodeBuilder.end();
	return nodeBuilder.build();
	}

	/**
	* Provides an array view of the contents of this node.
	*
	* <p>Depending on the underlying implementation, this may return a
	* reference to an internal array rather than a copy. Since the returned
	* array may be shared, the returned array should not be modified. The
	* {@code generator} function may be consulted to create the array if a new
	* array needs to be created.
	*
	* @param generator a factory function which takes an integer parameter and
	* returns a new, empty array of that size and of the appropriate
	* array type
	* @return an array containing the contents of this {@code Node}
	*/
	T[] asArray(IntFunction<T[]> generator);

	/**
	* Copies the content of this {@code Node} into an array, starting at a
	* given offset into the array. It is the caller's responsibility to ensure
	* there is sufficient room in the array, otherwise unspecified behaviour
	* will occur if the array length is less than the number of elements
	* contained in this node.
	*
	* @param array the array into which to copy the contents of this
	* {@code Node}
	* @param offset the starting offset within the array
	* @throws IndexOutOfBoundsException if copying would cause access of data
	* outside array bounds
	* @throws NullPointerException if {@code array} is {@code null}
	*/
	void copyInto(T[] array, int offset);

	/**
	* Gets the {@code StreamShape} associated with this {@code Node}.
	*
	* @implSpec The default in {@code Node} returns
	* {@code StreamShape.REFERENCE}
	*
	* @return the stream shape associated with this node
	*/
	default StreamShape getShape() {
	return StreamShape.REFERENCE;
	}

	/**
	* Returns the number of elements contained in this node.
	*
	* @return the number of elements contained in this node
	*/
	long count();

	/**
	* A mutable builder for a {@code Node} that implements {@link Sink}, which
	* builds a flat node containing the elements that have been pushed to it.
	*/
	interface Builder<T> extends Sink<T> {

	/**
	* Builds the node. Should be called after all elements have been
	* pushed and signalled with an invocation of {@link Sink#end()}.
	*
	* @return the resulting {@code Node}
	*/
	Node<T> build();

	/**
	* Specialized @{code Node.Builder} for int elements
	*/
	interface OfInt extends Node.Builder<Integer>, Sink.OfInt {
	@Override
	Node.OfInt build();
	}

	/**
	* Specialized @{code Node.Builder} for long elements
	*/
	interface OfLong extends Node.Builder<Long>, Sink.OfLong {
	@Override
	Node.OfLong build();
	}

	/**
	* Specialized @{code Node.Builder} for double elements
	*/
	interface OfDouble extends Node.Builder<Double>, Sink.OfDouble {
	@Override
	Node.OfDouble build();
	}
	}

	public interface OfPrimitive<T, T_CONS, T_ARR,
	T_SPLITR extends Spliterator.OfPrimitive<T, T_CONS, T_SPLITR>,
	T_NODE extends OfPrimitive<T, T_CONS, T_ARR, T_SPLITR, T_NODE>>
	extends Node<T> {

	/**
	* {@inheritDoc}
	*
	* @return a {@link Spliterator.OfPrimitive} describing the elements of
	* this node
	*/
	@Override
	T_SPLITR spliterator();

	/**
	* Traverses the elements of this node, and invoke the provided
	* {@code action} with each element.
	*
	* @param action a consumer that is to be invoked with each
	* element in this {@code Node.OfPrimitive}
	*/
	@SuppressWarnings("overloads")
	void forEach(T_CONS action);

	@Override
	default T_NODE getChild(int i) {
	throw new IndexOutOfBoundsException();
	}

	T_NODE truncate(long from, long to, IntFunction<T[]> generator);

	/**
	* {@inheritDoc}
	*
	* @implSpec the default implementation invokes the generator to create
	* an instance of a boxed primitive array with a length of
	* {@link #count()} and then invokes {@link #copyInto(T[], int)} with
	* that array at an offset of 0.
	*/
	@Override
	default T[] asArray(IntFunction<T[]> generator) {
	if (java.util.stream.Tripwire.ENABLED)
	java.util.stream.Tripwire.trip(getClass(), "{0} calling Node.OfPrimitive.asArray");

	long size = count();
	if (size >= Nodes.MAX_ARRAY_SIZE)
	throw new IllegalArgumentException(Nodes.BAD_SIZE);
	T[] boxed = generator.apply((int) count());
	copyInto(boxed, 0);
	return boxed;
	}

	/**
	* Views this node as a primitive array.
	*
	* <p>Depending on the underlying implementation this may return a
	* reference to an internal array rather than a copy. It is the callers
	* responsibility to decide if either this node or the array is utilized
	* as the primary reference for the data.</p>
	*
	* @return an array containing the contents of this {@code Node}
	*/
	T_ARR asPrimitiveArray();

	/**
	* Creates a new primitive array.
	*
	* @param count the length of the primitive array.
	* @return the new primitive array.
	*/
	T_ARR newArray(int count);

	/**
	* Copies the content of this {@code Node} into a primitive array,
	* starting at a given offset into the array. It is the caller's
	* responsibility to ensure there is sufficient room in the array.
	*
	* @param array the array into which to copy the contents of this
	* {@code Node}
	* @param offset the starting offset within the array
	* @throws IndexOutOfBoundsException if copying would cause access of
	* data outside array bounds
	* @throws NullPointerException if {@code array} is {@code null}
	*/
	void copyInto(T_ARR array, int offset);
	}

	/**
	* Specialized {@code Node} for int elements
	*/
	interface OfInt extends OfPrimitive<Integer, IntConsumer, int[], Spliterator.OfInt, OfInt> {

	/**
	* {@inheritDoc}
	*
	* @param consumer a {@code Consumer} that is to be invoked with each
	* element in this {@code Node}. If this is an
	* {@code IntConsumer}, it is cast to {@code IntConsumer} so the
	* elements may be processed without boxing.
	*/
	@Override
	default void forEach(Consumer<? super Integer> consumer) {
	if (consumer instanceof IntConsumer) {
	forEach((IntConsumer) consumer);
	}
	else {
	if (Tripwire.ENABLED)
	Tripwire.trip(getClass(), "{0} calling Node.OfInt.forEachRemaining(Consumer)");
	spliterator().forEachRemaining(consumer);
	}
	}

	/**
	* {@inheritDoc}
	*
	* @implSpec the default implementation invokes {@link #asPrimitiveArray()} to
	* obtain an int[] array then and copies the elements from that int[]
	* array into the boxed Integer[] array. This is not efficient and it
	* is recommended to invoke {@link #copyInto(Object, int)}.
	*/
	@Override
	default void copyInto(Integer[] boxed, int offset) {
	if (Tripwire.ENABLED)
	Tripwire.trip(getClass(), "{0} calling Node.OfInt.copyInto(Integer[], int)");

	int[] array = asPrimitiveArray();
	for (int i = 0; i < array.length; i++) {
	boxed[offset + i] = array[i];
	}
	}

	@Override
	default Node.OfInt truncate(long from, long to, IntFunction<Integer[]> generator) {
	if (from == 0 && to == count())
	return this;
	long size = to - from;
	Spliterator.OfInt spliterator = spliterator();
	Node.Builder.OfInt nodeBuilder = Nodes.intBuilder(size);
	nodeBuilder.begin(size);
	for (int i = 0; i < from && spliterator.tryAdvance((IntConsumer) e -> { }); i++) { }
	for (int i = 0; (i < size) && spliterator.tryAdvance((IntConsumer) nodeBuilder); i++) { }
	nodeBuilder.end();
	return nodeBuilder.build();
	}

	@Override
	default int[] newArray(int count) {
	return new int[count];
	}

	/**
	* {@inheritDoc}
	* @implSpec The default in {@code Node.OfInt} returns
	* {@code StreamShape.INT_VALUE}
	*/
	default StreamShape getShape() {
	return StreamShape.INT_VALUE;
	}
	}

	/**
	* Specialized {@code Node} for long elements
	*/
	interface OfLong extends OfPrimitive<Long, LongConsumer, long[], Spliterator.OfLong, OfLong> {

	/**
	* {@inheritDoc}
	*
	* @param consumer A {@code Consumer} that is to be invoked with each
	* element in this {@code Node}. If this is an
	* {@code LongConsumer}, it is cast to {@code LongConsumer} so
	* the elements may be processed without boxing.
	*/
	@Override
	default void forEach(Consumer<? super Long> consumer) {
	if (consumer instanceof LongConsumer) {
	forEach((LongConsumer) consumer);
	}
	else {
	if (Tripwire.ENABLED)
	Tripwire.trip(getClass(), "{0} calling Node.OfLong.forEachRemaining(Consumer)");
	spliterator().forEachRemaining(consumer);
	}
	}

	/**
	* {@inheritDoc}
	*
	* @implSpec the default implementation invokes {@link #asPrimitiveArray()}
	* to obtain a long[] array then and copies the elements from that
	* long[] array into the boxed Long[] array. This is not efficient and
	* it is recommended to invoke {@link #copyInto(Object, int)}.
	*/
	@Override
	default void copyInto(Long[] boxed, int offset) {
	if (Tripwire.ENABLED)
	Tripwire.trip(getClass(), "{0} calling Node.OfInt.copyInto(Long[], int)");

	long[] array = asPrimitiveArray();
	for (int i = 0; i < array.length; i++) {
	boxed[offset + i] = array[i];
	}
	}

	@Override
	default Node.OfLong truncate(long from, long to, IntFunction<Long[]> generator) {
	if (from == 0 && to == count())
	return this;
	long size = to - from;
	Spliterator.OfLong spliterator = spliterator();
	Node.Builder.OfLong nodeBuilder = Nodes.longBuilder(size);
	nodeBuilder.begin(size);
	for (int i = 0; i < from && spliterator.tryAdvance((LongConsumer) e -> { }); i++) { }
	for (int i = 0; (i < size) && spliterator.tryAdvance((LongConsumer) nodeBuilder); i++) { }
	nodeBuilder.end();
	return nodeBuilder.build();
	}

	@Override
	default long[] newArray(int count) {
	return new long[count];
	}

	/**
	* {@inheritDoc}
	* @implSpec The default in {@code Node.OfLong} returns
	* {@code StreamShape.LONG_VALUE}
	*/
	default StreamShape getShape() {
	return StreamShape.LONG_VALUE;
	}
	}

	/**
	* Specialized {@code Node} for double elements
	*/
	interface OfDouble extends OfPrimitive<Double, DoubleConsumer, double[], Spliterator.OfDouble, OfDouble> {

	/**
	* {@inheritDoc}
	*
	* @param consumer A {@code Consumer} that is to be invoked with each
	* element in this {@code Node}. If this is an
	* {@code DoubleConsumer}, it is cast to {@code DoubleConsumer}
	* so the elements may be processed without boxing.
	*/
	@Override
	default void forEach(Consumer<? super Double> consumer) {
	if (consumer instanceof DoubleConsumer) {
	forEach((DoubleConsumer) consumer);
	}
	else {
	if (Tripwire.ENABLED)
	Tripwire.trip(getClass(), "{0} calling Node.OfLong.forEachRemaining(Consumer)");
	spliterator().forEachRemaining(consumer);
	}
	}

	//

	/**
	* {@inheritDoc}
	*
	* @implSpec the default implementation invokes {@link #asPrimitiveArray()}
	* to obtain a double[] array then and copies the elements from that
	* double[] array into the boxed Double[] array. This is not efficient
	* and it is recommended to invoke {@link #copyInto(Object, int)}.
	*/
	@Override
	default void copyInto(Double[] boxed, int offset) {
	if (Tripwire.ENABLED)
	Tripwire.trip(getClass(), "{0} calling Node.OfDouble.copyInto(Double[], int)");

	double[] array = asPrimitiveArray();
	for (int i = 0; i < array.length; i++) {
	boxed[offset + i] = array[i];
	}
	}

	@Override
	default Node.OfDouble truncate(long from, long to, IntFunction<Double[]> generator) {
	if (from == 0 && to == count())
	return this;
	long size = to - from;
	Spliterator.OfDouble spliterator = spliterator();
	Node.Builder.OfDouble nodeBuilder = Nodes.doubleBuilder(size);
	nodeBuilder.begin(size);
	for (int i = 0; i < from && spliterator.tryAdvance((DoubleConsumer) e -> { }); i++) { }
	for (int i = 0; (i < size) && spliterator.tryAdvance((DoubleConsumer) nodeBuilder); i++) { }
	nodeBuilder.end();
	return nodeBuilder.build();
	}

	@Override
	default double[] newArray(int count) {
	return new double[count];
	}

	/**
	* {@inheritDoc}
	*
	* @implSpec The default in {@code Node.OfDouble} returns
	* {@code StreamShape.DOUBLE_VALUE}
	*/
	default StreamShape getShape() {
	return StreamShape.DOUBLE_VALUE;
	}
	}
	}

Back to index...