Polypheny JDBC Driver - ResultSet

The ResultSet class within the Polypheny JDBC Driver represents a table of data generated by executing a statement in the Polypheny database. This class offers methods for retrieving the results row-by-row, reading column values in the current row, and handling data types in a manner compliant with the JDBC specification.

next

public boolean next()
            throws SQLException

The next() method of the ResultSet object in the Polypheny JDBC Driver is crucial for navigating the rows of data in the result set. By sequentially calling this method, you can move from one row to the next, and each call retrieves the next row from the result. This enables applications to process each row in the result one by one. Once there are no more rows left, the method returns false, indicating the end of the result set.

Return Values:

This method throws an SQLException if there’s a database access error or if it’s called on a closed result set.

Usage:

The next() method is often used in a loop to iterate over the rows of the result set. Here’s an example:

try (
        Connection connection = DriverManager.getConnection( "jdbc:polypheny://localhost:20590" );
        Statement statement = connection.createStatement();
) {
    ResultSet resultSet = statement.executeQuery( "SELECT * FROM emps" );
    while ( resultSet.next() ) {
        String columnValue = resultSet.getString( "name" );
        // Process the current row...
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

previous

public boolean previous()
            throws SQLException

Moves the cursor one row back in the ResultSet object. It returns true if the cursor is on a valid row or false if it has moved off the result set.

Usage:

if ( rs.previous() ) {
    System.out.println( "Moved to the previous row successfully." );
} else {
    System.out.println( "Reached the beginning of the ResultSet." );
}

absolute

public boolean absolute(int row)
            throws SQLException

Moves the cursor to the specified row number in the ResultSet object. If the row number is positive, the cursor moves to the said row number with respect to the beginning of the ResultSet. If it’s negative, the cursor moves to an absolute row position relative to the end of the ResultSet. If the specified postion is after the last row of the rsult set, the curset will be set at the last row. If the position dpecified is before the first row, the cursor will be set to before the first row.

Usage:

// Moves to the third row from the beginning
rs.absolute( 3 );

// Moves to the third row from the end
rs.absolute( -3 );

relative

public boolean relative(int rows)
            throws SQLException

Moves the cursor a relative number of rows, either positive or negative, from the current position. For example, calling relative(2) would move the cursor two rows forward, while relative( -3 ) would move it three rows backward. If the specified postion is after the last row of the rsult set, the curset will be set at the last row.

Usage:

// Assuming cursor is currently on row 5
rs.relative( 2 );  // Cursor will now be on row 7
rs.relative( -3 ); // Cursor will now be back on row 4

beforeFirst

public void beforeFirst()
            throws SQLException

This method moves the cursor to the position just before the first row in the ResultSet object, allowing you to iterate over the rows again from the beginning.

afterLast

public void afterLast()
            throws SQLException

This method positions the cursor just after the last row in the ResultSet object. This can be useful if you wish to iterate over the rows in reverse order.

first

public boolean first()
            throws SQLException

This method moves the cursor to the first row of the ResultSet object. If the ResultSet is empty, it returns false; otherwise, it returns true.

last

public boolean last()
            throws SQLException

This method moves the cursor to the last row of the ResultSet object. Similar to first(), if the ResultSet is empty, it returns false; otherwise, it returns true.

isBeforeFirst

public boolean isBeforeFirst()
            throws SQLException

This method determines if the cursor is positioned before the first row in the ResultSet object. If the ResultSet is empty or ‘next()’ has not ben called on a new ResultSet, this method will return true. It provides a way to check if the cursor is still in its initial position or if there are any rows to iterate over.

isAfterLast

public boolean isAfterLast()
            throws SQLException

This method determines if the cursor is positioned after the last row in the ResultSet object. This provides an indication that all rows have been processed or that the ResultSet is empty.

isFirst

public boolean isFirst()
            throws SQLException

This method checks if the cursor is currently positioned at the first row of the ResultSet object.

isLast

public boolean isLast()
            throws SQLException

This method checks if the cursor is currently positioned at the last row of the ResultSet object.

close

public void close()
            throws SQLException

The close() method of the ResultSet object in the Polypheny JDBC Driver is designed to release the resources associated with a particular result set. Once a result set is closed, all methods on the ResultSet object (except for the isClosed() method) will throw an SQLException if they are called.

This method throws an SQLException if there’s a database access error.

Usage:

Closing a result set is a standard best practice in JDBC:

try (
    Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
    Statement statement = connection.createStatement();
) {
    ResultSet resultSet = statement.executeQuery( "SELECT * FROM my_table" );
    while ( resultSet.next() ) {
        String columnValue = resultSet.getString( "column_name" );
        // Process the current row...
    }
    resultSet.close(); // Close the result set
} catch ( SQLException e ) {
    e.printStackTrace();
}

isClosed

public boolean isClosed()
            throws SQLException

The isClosed() method determines whether the ResultSet object has been closed. A ResultSet is closed automatically once all data from it has been fetched, or explicitly via the close() method.

When a ResultSet is closed, further operations on it (with some exceptions like isClosed()) will throw an exception.

Usage:

ResultSet rs = statement.executeQuery( "SELECT * FROM myTable" );

// ... some operations with the ResultSet

boolean isResultSetClosed = rs.isClosed();

if ( isResultSetClosed ) {
    System.out.println( "The ResultSet is closed." );
} else {
    System.out.println( "The ResultSet is still open." );
}

Note: Always ensure that resources like ResultSet are closed after their operations to avoid potential resource leaks or unexpected behavior.

getWarnings

public SQLWarning getWarnings()
            throws SQLException

The method getWarnings() of the ResultSet object in the Polypheny JDBC Driver retrieves the first SQLWarning object for this statement if any. SQLWarning objects are a subclass of SQLException that deal with database access warnings. Warnings do not stop the execution of an application, as exceptions do; they simply alert the user that something did not happen as planned.

Return Value:

clearWarnings

public void clearWarnings()
            throws SQLException

The clearWarnings() method of the ResultSet object in the Polypheny JDBC Driver is used to clear all SQLWarning objects that have been reported for this connection. After calling this method, the getWarnings method will return null until a new warning is reported for the connection.

getCursorName

public String getCursorName()
            throws SQLException

Retrieves the name of the SQL cursor that’s associated with this ResultSet object. The cursor name is set by the database when the statement is executed and can be used in SQL positioned update/delete statements to identify the current row in the ResultSet object.

getMetaData

public ResultSetMetaData getMetaData()
            throws SQLException

This method retrieves the ResultSetMetaData object that can be used to obtain metadata about the columns in the ResultSet object. The metadata includes information like column names, types, precision, and more.

Usage:

ResultSet rs = statement.executeQuery( "SELECT * FROM myTable" );
ResultSetMetaData rsMetaData = rs.getMetaData();
int columnCount = rsMetaData.getColumnCount();

findColumn

public int findColumn(String columnLabel)
            throws SQLException

This method retrieves the index of the specified column label in the ResultSet object. If the label is not found, a SQLException will be thrown. The returned index can then be used to fetch column data from the ResultSet.

Usage:

ResultSet rs = statement.executeQuery( "SELECT name, age FROM users" );
int nameColumnIndex = rs.findColumn( "name" );
String userName = rs.getString( nameColumnIndex );

wasNull

public boolean wasNull()
            throws SQLException

The wasNull() method in the ResultSet object of the Polypheny JDBC Driver is employed to check whether the last column value read was SQL NULL. This method is particularly useful when retrieving optional values, as it allows developers to distinguish between a real value and a NULL placeholder. One should call this method immediately after retrieving a column value to ensure correctness, as the returned value is based on the most recent column accessed.

This method throws an SQLException if there’s a database access error or if the method is called on a closed result set.

Usage:

try (
    Connection connection = DriverManager.getConnection( "jdbc:polypheny://..." );
    Statement statement = connection.createStatement();
) {
    ResultSet resultSet = statement.executeQuery( "SELECT optional_column FROM my_table WHERE id = 1" );
    if ( resultSet.next() ) {
        String value = resultSet.getString( "optional_column" );
        if ( resultSet.wasNull() ) {
            System.out.println( "Value was NULL" );
        } else {
            System.out.println( "Retrieved value: " + value );
        }
    }
} catch ( SQLException e ) {
    e.printStackTrace();
}

Value Getter Methods in ResultSet

In the Polypheny JDBC Sriver’s ResultSet object, there’s an array of getter methods tailored to retrieve data of specific types from the current row. When fetching data, you can reference columns either by their index (starting from 1) or by their name. Below the methods using the column index are listed in alphabetically ascending order. The methods for retrieval by column name have identical signatures but have the parameter String columnName instead of int columnIndex.

setFetchDirection

public void setFetchDirection(int direction)
            throws SQLException

This method sets the ResultSet object’s fetch direction to the given type. The fetch direction determines the order in which rows are retrieved from the database. The fetchDirection argument can be one of the following constants:

• ResultSet.FETCH_FORWARD
• ResultSet.FETCH_REVERSE
• ResultSet.FETCH_UNKNOWN

By default, the fetch direction is ResultSet.FETCH_FORWARD.

Polpyheny currently ignores this parameter.

Usage:

// Set fetch direction to reverse
rs.setFetchDirection( ResultSet.FETCH_REVERSE );

getFetchDirection

public int getFetchDirection()
            throws SQLException

This method retrieves the current fetch direction for the ResultSet object. It returns one of the fetch direction constants mentioned above.

Usage:

int direction = rs.getFetchDirection();
if ( direction == ResultSet.FETCH_FORWARD ) {
    System.out.println( "Fetching in forward direction." );
} else if ( direction == ResultSet.FETCH_REVERSE ) {
    System.out.println( "Fetching in reverse direction." );
} else {
    System.out.println( "Fetch direction is unknown." );
}

setFetchSize

public void setFetchSize(int rows)
            throws SQLException

This method provides a hint to the Polypheny JDBC driver about the number of rows that should be fetched from the database on each trip when more rows are needed. This option helps to optimize the number of network round trips required to satisfy the request. If set to 0 the driver uses the default setting.

The rows parameter specifies the number of rows to fetch.

Usage:

// Set fetch size to 50 rows at a time
rs.setFetchSize( 50 );

getFetchSize

public int getFetchSize()
            throws SQLException

This method retrieves the current fetch size for the ResultSet object.

Usage:

int fetchSize = rs.getFetchSize();
System.out.println( "Current fetch size: " + fetchSize + " rows." );

getType

public int getType()
            throws SQLException

The getType() method of the ResultSet in the Polypheny JDBC Driver returns the type of the ResultSet object. These are the resultset types supported by Polypheny:

• ResultSet.TYPE_FORWARD_ONLY: The result set cannot be scrolled; its cursor can move only forward.
• ResultSet.TYPE_SCROLL_INSENSITIVE: The result can be scrolled, but changes made by others to the database are not visible in the result.

Usage:

int resultSetType = rs.getType();

switch ( resultSetType ) {
    case ResultSet.TYPE_FORWARD_ONLY:
        System.out.println( "The ResultSet is TYPE_FORWARD_ONLY." );
        break;
    case ResultSet.TYPE_SCROLL_INSENSITIVE:
        System.out.println( "The ResultSet is TYPE_SCROLL_INSENSITIVE." );
        break;
    case ResultSet.TYPE_SCROLL_SENSITIVE:
        // This case will never happen as polpyheny des not support this result set type
        System.out.println( "The ResultSet is TYPE_SCROLL_SENSITIVE." );
        break;
}

getConcurrency

public int getConcurrency()
            throws SQLException

The getConcurrency() method of the ResultSet in the Polypheny JDBC Driver returns the concurrency mode of the ResultSet object. ResultSet.CONCUR_READ_ONLY is the only supported concurrency mode:

getStatement

public Statement getStatement()
            throws SQLException

The getStatement() method retrieves the Statement object that produced the current ResultSet instance. This allows developers to reference the original statement that was used to generate the result set, potentially for accessing other related resources or information about the execution context.

Usage:

ResultSet rs = statement.executeQuery("SELECT * FROM myTable");
Statement originalStatement = rs.getStatement();

// Optionally, you can cast it back to the specific Statement type if needed:
if (originalStatement instanceof PreparedStatement) {
    PreparedStatement originalPreparedStatement = (PreparedStatement) originalStatement;
    // Further operations with originalPreparedStatement
}

Note that the returned Statement object might be an instance of any of the subinterfaces of Statement (like PreparedStatement or CallableStatement) depending on the actual type of the statement that produced the ResultSet.

getHoldability

public int getHoldability()
            throws SQLException

The getHoldability() method retrieves the holdability of the ResultSet object. Polpyheny only supports and thus returns ResultSet.CLOSE_CURSORS_AT_COMMIT. This implies that the result set will be automatically closed when the commit operation is invoked.

isWrapperFor

public boolean isWrapperFor(Class<?> iface)
            throws SQLException

The isWrapperFor( Class<?> iface ) method determines if the ResultSet instance can be unwrapped to an instance of the specified class or interface type. This method helps users to check whether the ResultSet object can be cast to a specific interface or class without causing a ClassCastException.

Usage:

ResultSet rs = statement.executeQuery( "SELECT * FROM myTable" );

if ( rs.isWrapperFor( YourSpecificClassOrInterface.class ) ) {
    System.out.println( "The ResultSet can be unwrapped to the specified class or interface." );
} else {
    System.out.println( "The ResultSet cannot be unwrapped to the specified class or interface." );
}

unwrap

public <T> T unwrap(Class<T> iface)
            throws SQLException

The unwrap( Class<T> iface ) method unwraps the ResultSet object to return an object of the desired type. If the ResultSet object doesn’t support the desired type, it throws a SQLException.

Usage:

ResultSet rs = statement.executeQuery( "SELECT * FROM myTable" );

try {
    YourSpecificClassOrInterface unwrappedObject = rs.unwrap( YourSpecificClassOrInterface.class );
    // Use the unwrapped object as needed
} catch ( SQLException e ) {
    System.out.println( "Failed to unwrap the ResultSet: " + e.getMessage() );
}

Note: Before invoking the unwrap method, it’s advisable to check if the ResultSet supports unwrapping to the desired type using the isWrapperFor method to avoid potential exceptions.

Unsupported Features

Polypheny supports only the CONCUR_READ_ONLY concurrency mode for ResultSet. This implies that the result set is non-updatable, and any changes made to the result set do not reflect in the underlying database.

As a result, all setter methods on the ResultSet object (methods intended to modify the data in the result set or underlying database) are not yet supported in Polypheny. Theses are:

• rowUpdated(): Returns true if the current row has been updates.
• rowInserted(): Returns true it the current row has been inserted.
• rowDeleted(): returns true if the current row has been deleted.
• insertRow(): Intended for inserting a new row into the current ResultSet and the underlying database.
• updateRow(): Aimed at updating the current row in the ResultSet and the database.
• deleteRow(): Designed for deleting the current row from the ResultSet and the database.
• refreshRow(): For refreshing the current row with the database’s latest values.
• cancelRowUpdates(): Cancels the modifications made to a row.
• moveToInsertRow(): Moves the cursor to the insert row, where new rows can be added.
• moveToCurrentRow(): Moves the cursor to the current row.

Previous

Prepared Statement

Next

Java