Annotation Type Cursor

Indicates if the associated cursor should be a rowset cursor when the SQL statement is run statically, if the database supports rowset cursors and the database driver is the IBM Data Server Driver for JDBC and SQLJ. true causes pureQuery to use a rowset cursor for SQL statements that are run statically whenever the database supports rowset cursors and the database driver is the IBM Data Server Driver for JDBC and SQLJ. false causes pureQuery to never be a rowset cursor for SQL statements that are run statically.

The value of this attribute is permitted to be true only when all of the following things are true:

• The SQL statement that is run by the annotated method is provided in the @Select annotation and is an SQL SELECT statement.
• The cursor that the SQL statement creates is a read-only cursor. An annotated method defines a read-only cursor if the value of the @Cursor(concurrency=...) attribute is ResultSet.CONCUR_READ_ONLY and if the SQL statement does not contain the clause "FOR UPDATE". The results of using rowsets for an updatable cursor can be unpredictable.
• The query result of the SQL statement does not contain any columns that have a LOB or XML data type.
• The annotated method does not define an SQL statement that the pureQuery Generator will optimize as a single-row select.

The value of the allowStaticRowsetCursors attribute must never be true on any annotated methods that the user will run inside of a stored procedure. It also must never be true on any annotated methods that open updatable cursors.

When an annotated method that has @Cursor(allowStaticRowsetCursors=true) is run against a database that does not support rowset cursors or with a database driver that is not the IBM Data Server Driver for JDBC and SQLJ, pureQuery does not attempt to use a rowset cursor for the SQL statement.

Defines the concurrency for the associated cursor. The valid possible values are ResultSet.CONCUR_READ_ONLY and ResultSet.CONCUR_UPDATABLE. The default value is ResultSet.CONCUR_READ_ONLY.

Defines the name for the associated cursor. An interface must not contain two annotated methods that have the @Cursor(cursorName=...) attribute set to the same value.

Annotated methods can run positioned UPDATE and DELETE statements for updatable cursors. This is done by declaring in a single interface a method that defines an updatable cursor and one or more annotated methods that define positioned UPDATE or DELETE statements for that cursor. The annotated method that defines the updatable cursor must have the @Select annotation and the @Cursor annotation. The annotated methods that define the positioned UPDATE and DELETE statements must have the @Update annotation. The value of the @Cursor(cursorName=...) attribute on the method that defines the cursor must be the same as the values of the @Update(positionedCursorName=...) attributes on the methods that define the positioned UPDATE and DELETE statements.

For an annotated method that defines an SQL SELECT statement, the cursor of the statement is updatable if the @Cursor(concurrency=...) attribute is set to ResultSet.CONCUR_UPDATABLE, or if the SQL SELECT statement that is provided contains the clause "FOR UPDATE".

If an annotated method defines a cursor that is used by a positioned UPDATE or DELETE statement in the same interface, pureQuery requires that the return type of the annotated method be either Iterator or ResultSet. For those two return types, pureQuery keeps the database cursor open until it is closed (explicitly or implicitly) by the user. The annotated method that defines the updatable cursor must always be run before any annotated method that defines a positioned UPDATE or DELETE statement for that cursor is run. When the positioned UPDATE or DELETE method is run, it updates or deletes the row that was most recently retrieved from the Iterator or ResultSet instance.

For pureQuery to know which cursor to update or delete, an application must never have two cursors with the same name open at the same time. An annotated method leaves a cursor open after the method is finished running if all of the following things occur:

• The method runs a SELECT statement.
• The method has a cursor name that is defined by the @Cursor annotation.
• The return type of the method is either Iterator or ResultSet.

Therefore, when an application invokes such a method, it must not invoke the method again until it closes the cursor. If the query result is ResultSet, the application can close the cursor by invoking ResultSet.close(). If the return type is Iterator, the application can close the cursor by invoking ResultIterator.close(), or by iterating through the entire query result.

When cursorName is set to "", pureQuery uses a default name for the cursor and does not allow positioned updates and deletes for the cursor.

This is an example of a declaration of an annotated method that defines an updatable cursor:
    @Select(sql = "SELECT * FROM EMPLOYEE")
    @Cursor(cursorName = "EMPLOYEECURSOR", concurrency = java.sql.ResultSet.CONCUR_UPDATABLE)
    Iterator<EmployeeBean> selectAllEmployees ();


This is an example of a declaration of an annotated method that defines a positioned UPDATE statement for the updatable cursor:
    @Update(sql = "UPDATE EMPLOYEE SET workdept = ?1.departmentNumber", positionedCursorName = "EMPLOYEECURSOR")
    int updateEmployeeDepartment (EmployeeBean employeeBean);


Defines the holdability for the associated cursor. The valid possible values are ResultSet.HOLD_CURSORS_OVER_COMMIT and ResultSet.CLOSE_CURSORS_AT_COMMIT. The default value is ResultSet.CLOSE_CURSORS_AT_COMMIT.

Defines the type of the associated cursor. The valid possible values are ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_SENSITIVE, and ResultSet.TYPE_SCROLL_INSENSITIVE. The default value is ResultSet.TYPE_FORWARD_ONLY.