HHH-19266 add getPosition() and deprecate get/setRowNumber()

since position() was a dupe of setRowNumber()

Author: gavinking

hibernate-core/src/main/java/org/hibernate/ScrollableResults.java

@@ -57,19 +57,41 @@ public interface ScrollableResults<R> extends AutoCloseable {
 	 * position.
 	 *
 	 * @param positions a positive (forward) or negative (backward)
-	 *                  number of rows
+	 *                  number of positions
 	 *
 	 * @return {@code true} if there is a result at the new location
 	 */
 	boolean scroll(int positions);
 
 	/**
-	 * Moves the result cursor to the specified position.
+	 * Moves the result cursor to the specified position. The index
+	 * may be a positive value, and the position may be reached by
+	 * counting forward from the first result at position {@code 1},
+	 * or it may be a negative value, so that the position may be
+	 * reached by counting backward from the last result at position
+	 * {@code -1}.
+	 *
+	 * @param position an absolute positive (from the start) or
+	 *                 negative (from the end) position within the
+	 *                 query results
 	 *
 	 * @return {@code true} if there is a result at the new location
 	 */
 	boolean position(int position);
 
+	/**
+	 * The current position within the query results. The first
+	 * query result, if any, is at position {@code 1}. An empty
+	 * or newly-created instance has position {@code 0}.
+	 *
+	 * @return the current position, a positive integer index
+	 *         starting at {@code 1}, or {@code 0} if this
+	 *         instance is empty or newly-created
+	 *
+	 * @since 7.0
+	 */
+	int getPosition();
+
 	/**
 	 * Go to the last result.
 	 *
@@ -119,7 +141,10 @@ public interface ScrollableResults<R> extends AutoCloseable {
 	 *
 	 * @return The current position number, numbered from 1;
 	 *         -1 indicates that there is no current row
+	 *
+	 * @deprecated Use {@link #getPosition()}
 	 */
+	@Deprecated(since = "7", forRemoval = true)
 	int getRowNumber();
 
 	/**
@@ -136,7 +161,10 @@ public interface ScrollableResults<R> extends AutoCloseable {
 	 *                  from the last row.
 	 *
 	 * @return true if there is a row at that row number
+	 *
+	 * @deprecated Use {@link #position(int)}
 	 */
+	@Deprecated(since = "7", forRemoval = true)
 	boolean setRowNumber(int rowNumber);
 
 	/**

hibernate-core/src/main/java/org/hibernate/internal/EmptyScrollableResults.java

@@ -81,6 +81,11 @@ public int getRowNumber() {
 		return 0;
 	}
 
+	@Override
+	public int getPosition() {
+		return 0;
+	}
+
 	@Override
 	public boolean setRowNumber(int rowNumber) {
 		return false;

hibernate-core/src/main/java/org/hibernate/internal/FetchingScrollableResultsImpl.java

@@ -270,6 +270,11 @@ public int getRowNumber() {
 		return currentPosition;
 	}
 
+	@Override
+	public int getPosition() {
+		return currentPosition;
+	}
+
 	@Override
 	public boolean setRowNumber(int rowNumber) {
 		if ( rowNumber == 1 ) {

hibernate-core/src/main/java/org/hibernate/internal/ScrollableResultsImpl.java

@@ -107,7 +107,12 @@ public boolean isLast() {
 
 	@Override
 	public int getRowNumber() {
-		return getRowProcessingState().getPosition() + 1;
+		return getPosition();
+	}
+
+	@Override
+	public int getPosition() {
+		return getRowProcessingState().getPosition();
 	}
 
 	@Override

hibernate-core/src/main/java/org/hibernate/sql/results/jdbc/internal/JdbcValuesCacheHit.java

@@ -71,7 +71,7 @@ protected boolean processScroll(int numberOfRows, RowProcessingState rowProcessi
 
 		position += numberOfRows;
 
-		if ( position > this.numberOfRows ) {
+		if ( position >= this.numberOfRows ) {
 			position = this.numberOfRows;
 			return false;
 		}
@@ -81,7 +81,7 @@ protected boolean processScroll(int numberOfRows, RowProcessingState rowProcessi
 
 	@Override
 	public int getPosition() {
-		return position;
+		return position + 1;
 	}
 
 	@Override
@@ -93,8 +93,12 @@ protected boolean processPosition(int position, RowProcessingState rowProcessing
 			// we need to subtract it from `numberOfRows`
 			position = numberOfRows + position;
 		}
+		else {
+			// internally, positions are indexed from zero
+			position--;
+		}
 
-		if ( position > numberOfRows ) {
+		if ( position >= numberOfRows ) {
 			this.position = numberOfRows;
 			return false;
 		}

hibernate-core/src/main/java/org/hibernate/sql/results/jdbc/internal/JdbcValuesResultSetImpl.java

@@ -170,7 +170,7 @@ private boolean scrollRows(final int numberOfRows) {
 	@Override
 	public int getPosition() {
 		try {
-			return resultSet.getRow() - 1;
+			return resultSet.getRow();
 		}
 		catch (SQLException e) {
 			throw makeExecutionException( "Error calling ResultSet#getRow", e );

hibernate-core/src/test/java/org/hibernate/orm/test/hql/ScrollableCollectionFetchingTest.java

@@ -354,6 +354,8 @@ public void testScrollingJoinFetchesWithNext(SessionFactoryScope scope) {
 							.setParameter( "desc", "root%" )
 							.scroll()) {
 
+						assertEquals( 0, results.getRowNumber() );
+
 						assertTrue( results.next() );
 						Animal animal = (Animal) results.get();
 						assertEquals( data.root1Id, animal.getId(), "next() did not return expected row" );
@@ -384,6 +386,8 @@ public void testScrollingNoJoinFetchesWithNext(SessionFactoryScope scope) {
 							.setParameter( "desc", "root%" )
 							.scroll()) {
 
+						assertEquals( 0, results.getRowNumber() );
+
 						assertTrue( results.next() );
 						Animal animal = (Animal) results.get();
 						assertEquals( data.root1Id, animal.getId(), "next() did not return expected row" );