jdk-sandbox: comparison src/jdk.incubator.adba/share/classes/jdk/incubator/sql2/Result.java

equal deleted inserted replaced

-:4f7713e6a308
+:c9cbac2979fb
 *
 */
 public interface Result {
 /**
-* A {@link Result} that is just a number of rows modified, a {@link Long}.
+* A {@code Result} that is just a number of rows modified, a {@link Long}.
 *
 * Note: It is certainly true that this is not needed; {@link Long} could be
 * used instead. Seems like there might be a documentational advantage to
 * having this type. If you don't like it, just mentally replace it with
 * {@link Long} everywhere it appears.
 }
 /**
 * A mutable handle to one value of an ordered sequence of columns of a row or
 * of out parameters. Columns have a 1-based index and optionally an
-* identifier. Identifiers are not guaranteed to be unique. Only {@code clone}
+* identifier. Identifiers are not guaranteed to be unique.
-* and {@code slice} create new instances. All other methods return this
+* <br>
-* instance (modifying it if necessary) including {@code forEach},
+* A newly created Column is initially positioned on the first column of
-* {@code next}, and {@code iterator}.
+* it's sequence. The position is modified by calls to {@link #at(int)},
+* {@link #at(String)}, {@link #next()}, or {@link #next(int)}.
+* The methods {@link #clone()}, {@link #slice(int)},
+* {@link #forEach(Consumer)}, and {@link #iterator()} create new instances.
+* All other methods return this instance (modifying it if necessary)
+* including {@link #next()}, and {@link #forEachRemaining(Consumer)}.
+* <br>
+* In cases where the result of an operation has no columns, an instance of
+* this class may represent an empty sequence of columns. Instances
+* associated to the empty sequence return 0 from calls to {@link #index()}
+* and {@link #absoluteIndex()}. It is illegal to modify the position or
+* accesses any attribute of a column if the sequence is empty.
 */
 public interface Column extends Result, Iterable<Column>, Iterator<Column>, Cloneable {
 /**
 * Return the value of this column as an instance of the given type.
 *
 * @param <T>
 * @param type
 * @return the value of this {@link Column}
+* @throws IllegalStateException if the column sequence is empty.
 */
 public <T> T get(Class<T> type);
 /**
 * Return the value of this {@link Column} as an instance of the default
 * Java type for this column.
 *
 * @param <T>
 * @return the value of this {@link Column}
+* @throws IllegalStateException if the column sequence is empty.
 */
 public default <T> T get() {
 return get(javaType());
 }
 /**
 * Return the identifier of this {@link Column}. May be null.
 *
 * @return the identifier of this {@link Column}. May be null
+* @throws IllegalStateException if the column sequence is empty.
 */
 public String identifier();
 /**
-* Return the 1-based index of this {@link Column}. The returned value is
+* Return the 1-based index of this {@link Column}. If the column
-* relative to the slice if this {@link Column} is the result of a call to
+* sequence is empty, the return value is 0.
-* {@code slice()}. {@code
+* <br>
-* col.slice(n).index() == 1}.
+* The returned value is relative to the slice if this {@link Column} is
-*
+* the result of a call to {@link #slice(int)}.
+* <br>
+* {@code col.slice(n).index() == 1}.
+* <br>
+* {@code col.slice(n).next().index() == 2}.
+*
 * @return the index of this {@link Column}
 */
 public int index();
 /**
 * Return the 1-based index of this {@link Column} relative to the original
-* sequence of values.
+* sequence of values. If the column sequence is empty, the return value
+* is 0.
+* <br>
 * {@code col.absoluteIndex() == col.slice(n).absoluteIndex()}.
 *
 * @return the absolute 1-based index of this {@link Column}
 */
 public int absoluteIndex();
 /**
 * Return the SQL type of the value of this {@link Column}.
 *
 * @return the SQL type of this value
+* @throws IllegalStateException if the column sequence is empty.
 */
 public SqlType sqlType();
 /**
 * Return the Java type that best represents the value of this
 * {@link Column}.
 *
 * @param <T>
 * @return a {@link Class} that best represents the value of this
 * {@link Column}
+* @throws IllegalStateException if the column sequence is empty.
 */
 public <T>Class<T> javaType();
 /**
 * The length of the current value if defined.
 *
 * @return
 * @throws UnsupportedOperationException if the length of the current value
 * is undefined
+* @throws IllegalStateException if the column sequence is empty.
 */
 public long length();
 /**
 * Return the number of remaining values accessible by this {@link Column}
 * information.
 *
 * @param id an identifier. Not null
 * @return this {@link Column}
 * @throws NoSuchElementException if id does not identify exactly one value
+* @throws IllegalStateException if the column sequence is empty.
 */
 public Column at(String id);
 /**
 * Modify this {@link Column} to point to the value at {@code index}. The
 * first value is at index 1. Negative numbers count back from the last
 * value. The last value is at index -1.
 *
 * @param index a new index
 * @return this {@link Column}
-* @throws NoSuchElementException if {@code index > length} or
+* @throws NoSuchElementException if {@code index > length},
-* {@code index < -length}
+* {@code index < -length}, or {@code index == 0}
+* @throws IllegalStateException if the column sequence is empty.
 */
 public Column at(int index);
 /**
 * Modify this {@link Column} to point to the value at the current index +
 * {@code offset}. If {@code offset} is 0 this is a noop. If {@code offset}
 * is negative the new index is less than the current index. If the new
-* index would be less than 1 or greater than length this {@link Column} is
+* index would be less than 1 or greater than the sequence length this
-* not modified and {@link IllegalArgumentException} is thrown.
+* {@link Column} is not modified and {@link IllegalArgumentException} is
+* thrown.
 *
 * @param offset an increment to the current index
 * @return this {@link Column}
 * @throws NoSuchElementException if the new index would be less than 1 or
-* greater than {@code length}
+* greater than the sequence length.
+* @throws IllegalStateException if the column sequence is empty.
 */
 public default Column next(int offset) {
+if (index() == 0) {
+throw new IllegalStateException();
+}
 int newIndex = index() + offset;
 if (offset > numberOfValuesRemaining() || newIndex < 1) {
 throw new NoSuchElementException();
 }
 return at(newIndex);
 * Return a new {@link Column} that is a handle to a subsequence of the
 * sequence of values referenced by this {@link Column}. The subsequence
 * consists of {@code numValues} number of values. If {@code numValues} is
 * positive the values are the value of this column and its successors. If
 * {@code numValues} is negative the values are the predecessors of this
-* column not including this {@link Column}. The order of the values of the
+* column not including this {@link Column}.
-* new {@link Column} is the same as the order of the values of this
+* <br>
-* {@link Column}. The returned {@link Column} points to the first value of
+* The returned {@link Column} is positioned on the first value of the
-* the slice. This {@link Column} is not modified.
+* slice.
+* <br>
+* The order of the values of the new {@link Column} is the same as the
+* order of the values of this {@link Column}. This {@link Column}
+* is not modified.
 *
 * @param numValues the number of columns to include in the slice
 * @return a new {@link Column}.
 * @throws NoSuchElementException if the current index plus
-* {@code numValues} is greater than the number of values of this
+* {@code numValues} is greater than the sequence length or less than 1
-* {@link Column} or less than 1
+* @throws IllegalStateException if the column sequence is empty.
 */
 public Column slice(int numValues);
 /**
 * Return a new {@link Column} that is a duplicate of this {@link Column}.
 /**
 * Modify this {@link Column} to point to the next value in the sequence.
 *
 * @return this {@link Column}
 * @throws NoSuchElementException if the new index would be greater than
-* {@code length}
+* the sequence length.
-*/
+* @throws IllegalStateException if the column sequence is empty.
-@Override
+*/
 public default Column next() {
 return next(1);
 }
+/**
+* {@inheritDoc}
+*/
 @Override
 public default boolean hasNext() {
 return numberOfValuesRemaining() > 0;
 }
+/**
+* {@inheritDoc}
+*/
 @Override
 public default void forEach(Consumer<? super Column> action) {
-do {
+if (index() == 0) {
-action.accept(this);
+return;
-if (!hasNext()) break;
+}
-next();
+action.accept(this.clone());
-} while (true);
+while (hasNext()) {
-}
+action.accept(next().clone());
+}
+}
+/**
+* {@inheritDoc}
+*/
 @Override
-public default Column iterator() {
+public default Iterator<Column> iterator() {
-return this.clone();
+return new Iterator<Column>() {
+Column next = Column.this.index() == 0 ? null : Column.this.clone();
+@Override
+public boolean hasNext() {
+return next != null;
+}
+@Override
+public Column next() {
+if (!hasNext()) {
+throw new NoSuchElementException();
+}
+Column prev = next.clone();
+if (next.hasNext()) {
+next.next();
+}
+else {
+next = null;
+}
+return prev;
+}
+};
 }
 /**
 * TODO This almost certainly works correctly but it doesn't integrate well
 * with the other access patterns. A better approach would be a Spliterator
 * sequence in arbitrary places invalidating the assumption about column
 * navigation.
 *
 * @return a {@link java.util.Spliterator}
 */
+/**
+* {@inheritDoc}
+*/
 @Override
 public default Spliterator<Column> spliterator() {
-List list = new ArrayList<>(numberOfValuesRemaining());
+List<Column> list = new ArrayList<>(numberOfValuesRemaining());
 this.clone().forEach(c -> list.add(c.slice(1)));
 return java.util.Spliterators.spliterator(list.toArray(), numberOfValuesRemaining());
 }
 }
 * For the first row in the row sequence the {@code rowNumber} is 0.
 *
 * @return the count of rows in the row sequence preceeding this
 * {@link RowColumn}
 * @throws IllegalStateException if the call that was passed this
-* {@link Result} has ended
+* {@code Result} has ended
 */
 public long rowNumber();
 /**
 * Terminate processing of the rows in this {@link RowOperation}. No further

branch	JDK-8188051-branch
changeset 56997	c9cbac2979fb
parent 56824	62e92191354d