An object responsible for executing SQL queries on the database. More...
import"sbIDatabaseQuery.idl";
Public Member Functions | |
| void | setAsyncQuery (in PRBool bAsyncQuery) |
| Set the query to run asynchronously (ie: execute() does not block) More... | |
| PRBool | isAyncQuery () |
| Return whether or not the query will run asynchronously. More... | |
| void | addSimpleQueryCallback (in sbIDatabaseSimpleQueryCallback dbPersistCB) |
| Add a sbIDatabaseSimpleQueryCallback instance to the query. More... | |
| void | removeSimpleQueryCallback (in sbIDatabaseSimpleQueryCallback dbPersistCB) |
| Remove a sbIDatabaseSimpleQueryCallback instance from the query. More... | |
| void | setDatabaseGUID (in AString dbGUID) |
| Set the database to be queried. More... | |
| AString | getDatabaseGUID () |
| Get the database identifier string. More... | |
| void | addQuery (in AString strQuery) |
| Add a SQL query string to the queue. More... | |
| sbIDatabasePreparedStatement | prepareQuery (in AString strQuery) |
| Create a prepared statement object to reduce overhead for repeated queries. More... | |
| void | addPreparedStatement (in sbIDatabasePreparedStatement PreparedStatement) |
| Add a prepared query to the queue. More... | |
| unsigned long | getQueryCount () |
| Return the number of query strings enqueued for execution. More... | |
| sbIDatabasePreparedStatement | getQuery (in unsigned long nIndex) |
| Get the query at the Nth index. More... | |
| void | resetQuery () |
| Clear out the query and make it all sparkly new. More... | |
| sbIDatabaseResult | getResultObject () |
| Get the results object for the query that has executed. More... | |
| long | getLastError () |
| Get the last error on the query that has executed. More... | |
| void | setLastError (in long dbError) |
| Set the last error on the query. More... | |
| long | execute () |
| Execute the queries enqueued in the object. More... | |
| long | waitForCompletion () |
| Wait until the query has finished executing asynchronously. More... | |
| boolean | isExecuting () |
| Return whether or not the query is currently executing. More... | |
| unsigned long | currentQuery () |
| Return the current index in the queue being indexed. More... | |
| boolean | abort () |
| Abort a currently executing query. More... | |
| void | bindUTF8StringParameter (in unsigned long aParamIndex, in AUTF8String aValue) |
| Binds a UTF8String to the last added query. More... | |
| void | bindStringParameter (in unsigned long aParamIndex, in AString aValue) |
| Binds a String to the last added query. More... | |
| void | bindDoubleParameter (in unsigned long aParamIndex, in double aValue) |
| Binds a double to the last added query. More... | |
| void | bindInt32Parameter (in unsigned long aParamIndex, in long aValue) |
| Binds an int32 to the last added query. More... | |
| void | bindInt64Parameter (in unsigned long aParamIndex, in long long aValue) |
| Binds an int64 to the last added query. More... | |
| void | bindNullParameter (in unsigned long aParamIndex) |
| Binds a null to the last added query. More... | |
Public Attributes | |
| attribute nsIURI | databaseLocation |
| Set a specific folder/directory URI for the database. More... | |
| attribute unsigned long long | rollingLimit |
| Set the rolling limit for this query. More... | |
| attribute unsigned long | rollingLimitColumnIndex |
| The index of the column used to add to the limit total. More... | |
| attribute unsigned long | rollingLimitResult |
| The number of the row (1 is the first row) that met or exceeded the limit. More... | |
An object responsible for executing SQL queries on the database.
The sbIDatabaseQuery object is used to execute queries on the underlying databases that store library and playlist data.
While client code running from chrome is free to query the databases directly, this object is more commonly passed to the database helper objects that translate their methods into SQL queries placed into the passed sbIDatabaseQuery instance.
The basic loop for using a query is as follows:
1) Object Initialization - setDatabaseGUID(), optionally setAsyncQuery(), set callbacks, etc
2) Query Construction - addQuery(), or calls to the helper objects
3) Execution - execute(), optionally waitForCompletion()
4) Get Results - getResultObject(), the returned object may be null if there was an error. You should always check the value returned by execute.
5) Reset - optionally resetQuery(), if you're going to reuse the object with a new set of query strings
Multiple queries may be added to the object via multiple calls to addQuery, or multiple calls to the helper interfaces. The queries will execute sequentially and the result object will be for the last query executed.
Definition at line 169 of file sbIDatabaseQuery.idl.
| boolean sbIDatabaseQuery::abort | ( | ) |
Abort a currently executing query.
This method blocks until the query has aborted
| void sbIDatabaseQuery::addPreparedStatement | ( | in sbIDatabasePreparedStatement | PreparedStatement | ) |
Add a prepared query to the queue.
This method enqueues a PreparedStatement prepared via prepareQuery().
| PreparedStatement | The prepared query. Must be prepared for use with this Query object. |
| void sbIDatabaseQuery::addQuery | ( | in AString | strQuery | ) |
Add a SQL query string to the queue.
This method enqueues a string to be exectued as a SQL query.
See: http://www.sqlite.org/lang.html for supported query syntax.
| strQuery | The query string |
| void sbIDatabaseQuery::addSimpleQueryCallback | ( | in sbIDatabaseSimpleQueryCallback | dbPersistCB | ) |
Add a sbIDatabaseSimpleQueryCallback instance to the query.
| dbPersistCB | The callback instance |
| void sbIDatabaseQuery::bindDoubleParameter | ( | in unsigned long | aParamIndex, |
| in double | aValue | ||
| ) |
Binds a double to the last added query.
| aParamIndex | The index of the parameter to bind |
| aValue | Value to bind to the specified index |
| void sbIDatabaseQuery::bindInt32Parameter | ( | in unsigned long | aParamIndex, |
| in long | aValue | ||
| ) |
Binds an int32 to the last added query.
| aParamIndex | The index of the parameter to bind |
| aValue | Value to bind to the specified index |
| void sbIDatabaseQuery::bindInt64Parameter | ( | in unsigned long | aParamIndex, |
| in long long | aValue | ||
| ) |
Binds an int64 to the last added query.
| aParamIndex | The index of the parameter to bind |
| aValue | Value to bind to the specified index |
| void sbIDatabaseQuery::bindNullParameter | ( | in unsigned long | aParamIndex | ) |
Binds a null to the last added query.
| aParamIndex | The index of the parameter to bind |
| void sbIDatabaseQuery::bindStringParameter | ( | in unsigned long | aParamIndex, |
| in AString | aValue | ||
| ) |
Binds a String to the last added query.
| aParamIndex | The index of the parameter to bind |
| aValue | Value to bind to the specified index |
| void sbIDatabaseQuery::bindUTF8StringParameter | ( | in unsigned long | aParamIndex, |
| in AUTF8String | aValue | ||
| ) |
Binds a UTF8String to the last added query.
| aParamIndex | The index of the parameter to bind |
| aValue | Value to bind to the specified index |
| unsigned long sbIDatabaseQuery::currentQuery | ( | ) |
Return the current index in the queue being indexed.
| long sbIDatabaseQuery::execute | ( | ) |
Execute the queries enqueued in the object.
| 0 | - No error |
| > | 0 - Error. |
| AString sbIDatabaseQuery::getDatabaseGUID | ( | ) |
Get the database identifier string.
| long sbIDatabaseQuery::getLastError | ( | ) |
Get the last error on the query that has executed.
Don't call this method unless you know the query has completed executing.
| sbIDatabasePreparedStatement sbIDatabaseQuery::getQuery | ( | in unsigned long | nIndex | ) |
Get the query at the Nth index.
| nIndex | The index into the queue |
| unsigned long sbIDatabaseQuery::getQueryCount | ( | ) |
Return the number of query strings enqueued for execution.
| sbIDatabaseResult sbIDatabaseQuery::getResultObject | ( | ) |
Get the results object for the query that has executed.
Don't get this object unless you know the query has completed executing.
| PRBool sbIDatabaseQuery::isAyncQuery | ( | ) |
Return whether or not the query will run asynchronously.
| boolean sbIDatabaseQuery::isExecuting | ( | ) |
Return whether or not the query is currently executing.
| sbIDatabasePreparedStatement sbIDatabaseQuery::prepareQuery | ( | in AString | strQuery | ) |
Create a prepared statement object to reduce overhead for repeated queries.
This method only creates the object, and does not actually compile the statement until first execution. As of first execution, the sqlite database pointer becomes fixed, and from that point on, it will return null if the Engine attempts to execute it via a different database engine.
See: http://www.sqlite.org/lang.html for supported query syntax.
| strQuery | The query string |
| void sbIDatabaseQuery::removeSimpleQueryCallback | ( | in sbIDatabaseSimpleQueryCallback | dbPersistCB | ) |
Remove a sbIDatabaseSimpleQueryCallback instance from the query.
| dbPersistCB | The callback instance |
| void sbIDatabaseQuery::resetQuery | ( | ) |
Clear out the query and make it all sparkly new.
You must call this method if you want to reuse a query object with new query strings.
Otherwise, you may simply call execute again on a query object to reissue the last set of queries.
| void sbIDatabaseQuery::setAsyncQuery | ( | in PRBool | bAsyncQuery | ) |
Set the query to run asynchronously (ie: execute() does not block)
Use callbacks or poll via isExecuting() to know when the query completes.
| bAsyncQuery | If true, do not block on execute (default: false) |
| void sbIDatabaseQuery::setDatabaseGUID | ( | in AString | dbGUID | ) |
Set the database to be queried.
This function associates the query object with a particular database.
The dbGUID parameter is any unique string used as a filename to create a queryable database sandbox.
The special character "*" may be passed to execute a query across all databases tracked by the application.
| dbGUID | The database identifier |
| void sbIDatabaseQuery::setLastError | ( | in long | dbError | ) |
Set the last error on the query.
The database engine calls this. Don't.
| dbError | The error code to insert |
| long sbIDatabaseQuery::waitForCompletion | ( | ) |
Wait until the query has finished executing asynchronously.
If the query is not executing, this immediately returns.
| attribute nsIURI sbIDatabaseQuery::databaseLocation |
Set a specific folder/directory URI for the database.
Set a specific folder URI where you wish your database to reside. For example, you could set the location to be the following: 'file:///C:/MyDB/'
Note that the directory is not created for you and must exist by the time execute() is called on the query.
Definition at line 181 of file sbIDatabaseQuery.idl.
| attribute unsigned long long sbIDatabaseQuery::rollingLimit |
Set the rolling limit for this query.
If set, this query will be a rolling limit query. Rather than return the full result of the query, a rolling limit query will add up the values of the column specified in rollingLimitColumnIndex and stop running once the limit set in rollingLimit is reached. The query result will be a single row containing the row that met or exceeded the limit. The row number of this row will be set in rollingLimitResult. If the limit is not reach, no rows are returned.
Definition at line 377 of file sbIDatabaseQuery.idl.
| attribute unsigned long sbIDatabaseQuery::rollingLimitColumnIndex |
The index of the column used to add to the limit total.
Definition at line 382 of file sbIDatabaseQuery.idl.
| attribute unsigned long sbIDatabaseQuery::rollingLimitResult |
The number of the row (1 is the first row) that met or exceeded the limit.
Definition at line 388 of file sbIDatabaseQuery.idl.
