kexi
KexiDB::Cursor Class Reference
#include <cursor.h>
Inheritance diagram for KexiDB::Cursor:

Detailed Description
Provides database cursor functionality.Cursor can be defined in two ways:
- by passing QuerySchema object to Connection::executeQuery() or Connection::prepareQuery(); then query is defined for in engine-independent way -- this is recommended usage
- by passing raw query statement string to Connection::executeQuery() or Connection::prepareQuery(); then query may be defined for in engine-dependent way -- this is not recommended usage, but convenient when we can't or do not want to allocate QuerySchema object, while we know that the query statement is syntactically and logically ok in our context.
You can move cursor to next record with moveNext() and move back with movePrev(). The cursor is always positioned on record, not between records, with exception that ofter open() it is positioned before first record (if any) -- then bof() equals true, and can be positioned after the last record (if any) with moveNext() -- then eof() equals true, For example, if you have four records 1, 2, 3, 4, then after calling moveNext(), moveNext(), moveNext(), movePrev() you are going through records: 1, 2, 3, 2.
Cursor can be buffered or unbuferred. Buffering in this class is not related to any SQL engine capatibilities for server-side cursors (eg. like 'DECLARE CURSOR' statement) - buffered data is at client (application) side. Any record retrieved in buffered cursor will be stored inside an internal buffer and reused when needed. Unbuffered cursor always requires one record fetching from db connection at every step done with moveNext(), movePrev(), etc.
Notes:
- Do not use delete operator for Cursor objects - this will fail; use Connection::deleteCursor() instead.
- QuerySchema object is not owned by Cursor object that uses it.
Definition at line 66 of file cursor.h.
Public Types | |
enum | Options { NoOptions = 0, Buffered = 1 } |
Public Member Functions | |
virtual | ~Cursor () |
Connection * | connection () const |
bool | open () |
bool | reopen () |
virtual bool | close () |
QuerySchema * | query () const |
QValueList< QVariant > | queryParameters () const |
void | setQueryParameters (const QValueList< QVariant > ¶ms) |
QString | rawStatement () const |
uint | options () const |
bool | isOpened () const |
bool | isBuffered () const |
void | setBuffered (bool buffered) |
bool | moveFirst () |
virtual bool | moveLast () |
virtual bool | moveNext () |
virtual bool | movePrev () |
bool | eof () const |
bool | bof () const |
Q_LLONG | at () const |
uint | fieldCount () const |
bool | containsROWIDInfo () const |
virtual QVariant | value (uint i)=0 |
virtual const char ** | rowData () const=0 |
void | setOrderByColumnList (const QStringList &columnNames) |
void | setOrderByColumnList (const QString &column1, const QString &column2=QString::null, const QString &column3=QString::null, const QString &column4=QString::null, const QString &column5=QString::null) |
QueryColumnInfo::Vector | orderByColumnList () const |
virtual void | storeCurrentRow (RowData &data) const =0 |
bool | updateRow (RowData &data, RowEditBuffer &buf, bool useROWID=false) |
bool | insertRow (RowData &data, RowEditBuffer &buf, bool getROWID=false) |
bool | deleteRow (RowData &data, bool useROWID=false) |
bool | deleteAllRows () |
virtual int | serverResult () |
virtual QString | serverResultName () |
virtual QString | serverErrorMsg () |
QString | debugString () const |
void | debug () const |
Protected Types | |
enum | FetchResult { FetchError = 0, FetchOK = 1, FetchEnd = 2 } |
Protected Member Functions | |
Cursor (Connection *conn, const QString &statement, uint options=NoOptions) | |
Cursor (Connection *conn, QuerySchema &query, uint options=NoOptions) | |
void | init () |
bool | getNextRecord () |
virtual bool | drv_open ()=0 |
virtual bool | drv_close ()=0 |
virtual void | drv_getNextRecord ()=0 |
virtual void | drv_appendCurrentRecordToBuffer ()=0 |
virtual void | drv_bufferMovePointerNext ()=0 |
virtual void | drv_bufferMovePointerPrev ()=0 |
virtual void | drv_bufferMovePointerTo (Q_LLONG at)=0 |
virtual void | drv_clearBuffer () |
void | clearBuffer () |
virtual void | drv_clearServerResult ()=0 |
Protected Attributes | |
QGuardedPtr< Connection > | m_conn |
QuerySchema * | m_query |
QString | m_rawStatement |
bool | m_opened: 1 |
bool | m_atLast: 1 |
bool | m_afterLast: 1 |
bool | m_validRecord: 1 |
bool | m_containsROWIDInfo: 1 |
Q_LLONG | m_at |
uint | m_fieldCount |
uint | m_logicalFieldCount |
uint | m_options |
char | m_result |
int | m_records_in_buf |
bool | m_buffering_completed: 1 |
QueryColumnInfo::Vector * | m_fieldsExpanded |
QueryColumnInfo::Vector * | m_orderByColumnList |
QValueList< QVariant > * | m_queryParameters |
Member Enumeration Documentation
enum KexiDB::Cursor::FetchResult [protected] |
Constructor & Destructor Documentation
Cursor::Cursor | ( | Connection * | conn, | |
const QString & | statement, | |||
uint | options = NoOptions | |||
) | [protected] |
Cursor will operate on conn, raw statement will be used to execute query.
Definition at line 40 of file cursor.cpp.
Cursor::Cursor | ( | Connection * | conn, | |
QuerySchema & | query, | |||
uint | options = NoOptions | |||
) | [protected] |
Cursor will operate on conn, query schema will be used to execute query.
Definition at line 53 of file cursor.cpp.
Member Function Documentation
Connection* KexiDB::Cursor::connection | ( | ) | const [inline] |
bool Cursor::open | ( | ) |
Opens the cursor using data provided on creation. The data might be either QuerySchema or raw sql statement.
Definition at line 131 of file cursor.cpp.
bool Cursor::reopen | ( | ) |
Closes and then opens again the same cursor. If the cursor is not opened it is just opened and result of this open is returned. Otherwise, true is returned if cursor is successfully closed and then opened.
Definition at line 198 of file cursor.cpp.
bool Cursor::close | ( | ) | [virtual] |
Closes previously opened cursor. If the cursor is closed, nothing happens.
Definition at line 178 of file cursor.cpp.
QuerySchema* KexiDB::Cursor::query | ( | ) | const [inline] |
QValueList< QVariant > Cursor::queryParameters | ( | ) | const |
void Cursor::setQueryParameters | ( | const QValueList< QVariant > & | params | ) |
QString KexiDB::Cursor::rawStatement | ( | ) | const [inline] |
- Returns:
- raw query statement used to define this cursor or null string if raw statement instead (but QuerySchema is defined instead).
uint KexiDB::Cursor::options | ( | ) | const [inline] |
- Returns:
- logically or'd cursor's options, selected from Cursor::Options enum.
bool KexiDB::Cursor::isOpened | ( | ) | const [inline] |
bool Cursor::isBuffered | ( | ) | const |
void Cursor::setBuffered | ( | bool | buffered | ) |
Sets this cursor to buffered type or not. See description of buffered and nonbuffered cursors in class description. This method only works if cursor is not opened (isOpened()==false). You can close already opened cursor and then switch this option on/off.
Definition at line 361 of file cursor.cpp.
bool Cursor::moveFirst | ( | ) |
Moves current position to the first record and retrieves it.
- Returns:
- true if the first record was retrieved. False could mean that there was an error or there is no record available.
Definition at line 205 of file cursor.cpp.
bool Cursor::moveLast | ( | ) | [virtual] |
Moves current position to the last record and retrieves it.
- Returns:
- true if the last record was retrieved. False could mean that there was an error or there is no record available.
Definition at line 254 of file cursor.cpp.
bool Cursor::moveNext | ( | ) | [virtual] |
Moves current position to the next record and retrieves it.
Definition at line 292 of file cursor.cpp.
bool Cursor::movePrev | ( | ) | [virtual] |
Moves current position to the next record and retrieves it. Currently it's only supported for buffered cursors.
Definition at line 303 of file cursor.cpp.
bool Cursor::eof | ( | ) | const |
bool Cursor::bof | ( | ) | const |
Q_LLONG Cursor::at | ( | ) | const |
- Returns:
- current internal position of the cursor's query. We are counting records from 0. Value -1 means that cursor does not point to any valid record (this happens eg. after open(), close(), and after moving after last record or before first one.
Definition at line 349 of file cursor.cpp.
uint KexiDB::Cursor::fieldCount | ( | ) | const [inline] |
bool KexiDB::Cursor::containsROWIDInfo | ( | ) | const [inline] |
- Returns:
- true if ROWID information is appended with every row. ROWID information is available if DriverBehaviour::ROW_ID_FIELD_RETURNS_LAST_AUTOINCREMENTED_VALUE == false for a KexiDB database driver and the master table has no primary key defined. Phisically, ROWID value is returned after last returned field, so data vector's length is expanded by one.
virtual QVariant KexiDB::Cursor::value | ( | uint | i | ) | [pure virtual] |
- Returns:
- a value stored in column number i (counting from 0). Is has unspecified behaviour if the cursor is not at valid record. Note for driver developers: If i is >= than m_fieldCount, null QVariant value should be returned. To return a value typically you can use a pointer to internal structure that contain current row data (buffered or unbuffered).
Implemented in KexiDB::MySqlCursor, KexiDB::pqxxSqlCursor, and KexiDB::SQLiteCursor.
virtual const char** KexiDB::Cursor::rowData | ( | ) | const [pure virtual] |
[PROTOTYPE]
- Returns:
- current record data or NULL if there is no current records.
Implemented in KexiDB::MySqlCursor, KexiDB::pqxxSqlCursor, and KexiDB::SQLiteCursor.
void Cursor::setOrderByColumnList | ( | const QStringList & | columnNames | ) |
Sets a list of columns for ORDER BY section of the query. Only works when the cursor has been created using QuerySchema object (i.e. when query()!=0; does not work with raw statements). Each name on the list must be a field or alias present within the query and must not be covered by aliases. If one or more names cannot be found within the query, the method will have no effect. Any previous ORDER BY settings will be removed.
The order list provided here has priority over a list defined in the QuerySchema object itseld (using QuerySchema::setOrderByColumnList()). The QuerySchema object itself is not modifed by this method: only order of records retrieved by this cursor is affected.
Use this method before calling open(). You can also call reopen() after calling this method to see effects of applying records order.
- Todo:
- implement this:
Definition at line 529 of file cursor.cpp.
void Cursor::setOrderByColumnList | ( | const QString & | column1, | |
const QString & | column2 = QString::null , |
|||
const QString & | column3 = QString::null , |
|||
const QString & | column4 = QString::null , |
|||
const QString & | column5 = QString::null | |||
) |
Convenience method, similar to setOrderByColumnList(const QStringList&).
- Todo:
- implement this, like above
add ORDER BY info to debugString()
Definition at line 541 of file cursor.cpp.
QueryColumnInfo::Vector Cursor::orderByColumnList | ( | ) | const |
- Returns:
- a list of fields contained in ORDER BY section of the query.
- See also:
- setOrderBy(const QStringList&)
Definition at line 553 of file cursor.cpp.
virtual void KexiDB::Cursor::storeCurrentRow | ( | RowData & | data | ) | const [pure virtual] |
Puts current record's data into data (makes a deep copy). This have unspecified behaviour if the cursor is not at valid record. Note: For reimplementation in driver's code. Shortly, this method translates a row data from internal representation (probably also used in buffer) to simple public RecordData representation.
Implemented in KexiDB::MySqlCursor, KexiDB::pqxxSqlCursor, and KexiDB::SQLiteCursor.
bool Cursor::updateRow | ( | RowData & | data, | |
RowEditBuffer & | buf, | |||
bool | useROWID = false | |||
) |
Definition at line 461 of file cursor.cpp.
bool Cursor::insertRow | ( | RowData & | data, | |
RowEditBuffer & | buf, | |||
bool | getROWID = false | |||
) |
Definition at line 470 of file cursor.cpp.
bool Cursor::deleteRow | ( | RowData & | data, | |
bool | useROWID = false | |||
) |
Definition at line 479 of file cursor.cpp.
bool Cursor::deleteAllRows | ( | ) |
Definition at line 488 of file cursor.cpp.
virtual int KexiDB::Cursor::serverResult | ( | ) | [inline, virtual] |
- Returns:
- a code of last executed operation's result at the server side. This code is engine dependent and may be even engine-version dependent. It can be visible in applications mainly after clicking a "Details>>" button or something like that -- this just can be useful for advanced users and for testing. Note for driver developers: Return here the value you usually store as result of most lower-level operations. By default this method returns 0.
Reimplemented from KexiDB::Object.
Reimplemented in KexiDB::MySqlCursor, and KexiDB::SQLiteCursor.
virtual QString KexiDB::Cursor::serverResultName | ( | ) | [inline, virtual] |
- Returns:
- (not i18n'd) name of last executed operation's result at the server side. Sometimes engines have predefined its result names that can be used e.g. to refer a documentation. SQLite is one of such engines. Note for driver developers: Leave the default implementation (null string is returned ) if your engine has no such capability.
Reimplemented from KexiDB::Object.
Reimplemented in KexiDB::MySqlCursor, and KexiDB::SQLiteCursor.
virtual QString KexiDB::Cursor::serverErrorMsg | ( | ) | [inline, virtual] |
- Returns:
- (not i18n'd) description text (message) of last operation's error/result. In most cases engines do return such a messages, any user can then use this to refer a documentation. Note for driver developers: Leave the default implementation (null string is returned ) if your engine has no such capability.
Reimplemented from KexiDB::Object.
Reimplemented in KexiDB::MySqlCursor, and KexiDB::SQLiteCursor.
QString Cursor::debugString | ( | ) | const |
void Cursor::debug | ( | ) | const |
bool Cursor::getNextRecord | ( | ) | [protected] |
Internal: cares about proper flag setting depending on result of drv_getNextRecord() and depending on wherher a cursor is buffered.
if (m_at < (m_records_in_buf-1)) {//we have next record already buffered:
Definition at line 381 of file cursor.cpp.
virtual void KexiDB::Cursor::drv_appendCurrentRecordToBuffer | ( | ) | [protected, pure virtual] |
Stores currently fetched record's values in appropriate place of the buffer. Note for driver developers: This place can be computed using m_at. Do not change value of m_at or any other Cursor members, only change your internal structures like pointer to current row, etc. If your database engine's API function (for record fetching) do not allocates such a space, you want to allocate a space for current record. Otherwise, reuse existing structure, what could be more efficient. All functions like drv_appendCurrentRecordToBuffer() operates on the buffer, i.e. array of stored rows. You are not forced to have any particular fixed structure for buffer item or buffer itself - the structure is internal and only methods like storeCurrentRecord() visible to public.
Implemented in KexiDB::MySqlCursor, KexiDB::pqxxSqlCursor, and KexiDB::SQLiteCursor.
virtual void KexiDB::Cursor::drv_bufferMovePointerNext | ( | ) | [protected, pure virtual] |
Moves pointer (that points to the buffer) -- to next item in this buffer. Note for driver developers: probably just execute "your_pointer++" is enough.
Implemented in KexiDB::MySqlCursor, KexiDB::pqxxSqlCursor, and KexiDB::SQLiteCursor.
virtual void KexiDB::Cursor::drv_bufferMovePointerPrev | ( | ) | [protected, pure virtual] |
Like drv_bufferMovePointerNext() but execute "your_pointer--".
Implemented in KexiDB::MySqlCursor, KexiDB::pqxxSqlCursor, and KexiDB::SQLiteCursor.
virtual void KexiDB::Cursor::drv_bufferMovePointerTo | ( | Q_LLONG | at | ) | [protected, pure virtual] |
Moves pointer (that points to the buffer) to a new place: at.
Implemented in KexiDB::MySqlCursor, KexiDB::pqxxSqlCursor, and KexiDB::SQLiteCursor.
virtual void KexiDB::Cursor::drv_clearBuffer | ( | ) | [inline, protected, virtual] |
Clears cursor's buffer if this was allocated (only for buffered cursor type). Otherwise do nothing. For reimplementing. Default implementation does nothing.
Reimplemented in KexiDB::SQLiteCursor.
virtual void KexiDB::Cursor::drv_clearServerResult | ( | ) | [protected, pure virtual] |
Clears an internal member that is used to storing last result code, the same that is returend by serverResult().
Reimplemented from KexiDB::Object.
Implemented in KexiDB::MySqlCursor, KexiDB::pqxxSqlCursor, and KexiDB::SQLiteCursor.
Member Data Documentation
bool KexiDB::Cursor::m_validRecord [protected] |
uint KexiDB::Cursor::m_fieldCount [protected] |
uint KexiDB::Cursor::m_logicalFieldCount [protected] |
uint KexiDB::Cursor::m_options [protected] |
char KexiDB::Cursor::m_result [protected] |
int KexiDB::Cursor::m_records_in_buf [protected] |
bool KexiDB::Cursor::m_buffering_completed [protected] |
QueryColumnInfo::Vector* KexiDB::Cursor::m_fieldsExpanded [protected] |
The documentation for this class was generated from the following files: