import "sbIDatabaseQuery.idl";
Public Member Functions | |
void | setAsyncQuery (in PRBool bAsyncQuery) |
Set the query to run asynchronously (ie: execute() does not block). | |
PRBool | isAyncQuery () |
Return whether or not the query will run asynchronously. | |
void | addSimpleQueryCallback (in sbIDatabaseSimpleQueryCallback dbPersistCB) |
Add a sbIDatabaseSimpleQueryCallback instance to the query. | |
void | removeSimpleQueryCallback (in sbIDatabaseSimpleQueryCallback dbPersistCB) |
Remove a sbIDatabaseSimpleQueryCallback instance from the query. | |
void | setDatabaseGUID (in AString dbGUID) |
Set the database to be queried. | |
AString | getDatabaseGUID () |
Get the database identifier string. | |
void | addQuery (in AString strQuery) |
Add a SQL query string to the queue. | |
sbIDatabasePreparedStatement | prepareQuery (in AString strQuery) |
Create a prepared statement object to reduce overhead for repeated queries. | |
void | addPreparedStatement (in sbIDatabasePreparedStatement PreparedStatement) |
Add a prepared query to the queue. | |
unsigned long | getQueryCount () |
Return the number of query strings enqueued for execution. | |
sbIDatabasePreparedStatement | getQuery (in unsigned long nIndex) |
Get the query at the Nth index. | |
void | resetQuery () |
Clear out the query and make it all sparkly new. | |
sbIDatabaseResult | getResultObject () |
Get the results object for the query that has executed. | |
long | getLastError () |
Get the last error on the query that has executed. | |
void | setLastError (in long dbError) |
Set the last error on the query. | |
long | execute () |
Execute the queries enqueued in the object. | |
long | waitForCompletion () |
Wait until the query has finished executing asynchronously. | |
boolean | isExecuting () |
Return whether or not the query is currently executing. | |
unsigned long | currentQuery () |
Return the current index in the queue being indexed. | |
boolean | abort () |
Abort a currently executing query. | |
void | bindUTF8StringParameter (in unsigned long aParamIndex, in AUTF8String aValue) |
Binds a UTF8String to the last added query. | |
void | bindStringParameter (in unsigned long aParamIndex, in AString aValue) |
Binds a String to the last added query. | |
void | bindDoubleParameter (in unsigned long aParamIndex, in double aValue) |
Binds a double to the last added query. | |
void | bindInt32Parameter (in unsigned long aParamIndex, in long aValue) |
Binds an int32 to the last added query. | |
void | bindInt64Parameter (in unsigned long aParamIndex, in long long aValue) |
Binds an int64 to the last added query. | |
void | bindNullParameter (in unsigned long aParamIndex) |
Binds a null to the last added query. | |
Public Attributes | |
attribute nsIURI | databaseLocation |
Set a specific folder/directory URI for the database. | |
attribute unsigned long long | rollingLimit |
Set the rolling limit for this query. | |
attribute unsigned long | rollingLimitColumnIndex |
The index of the column used to add to the limit total. | |
attribute unsigned long | rollingLimitResult |
The number of the row (1 is the first row) that met or exceeded the limit. |
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()
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 167 of file sbIDatabaseQuery.idl.
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) |
PRBool sbIDatabaseQuery::isAyncQuery | ( | ) |
Return whether or not the query will run asynchronously.
void sbIDatabaseQuery::addSimpleQueryCallback | ( | in sbIDatabaseSimpleQueryCallback | dbPersistCB | ) |
Add a sbIDatabaseSimpleQueryCallback instance to the query.
dbPersistCB | The callback instance |
void sbIDatabaseQuery::removeSimpleQueryCallback | ( | in sbIDatabaseSimpleQueryCallback | dbPersistCB | ) |
Remove a sbIDatabaseSimpleQueryCallback instance from the query.
dbPersistCB | The callback instance |
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 |
AString sbIDatabaseQuery::getDatabaseGUID | ( | ) |
Get the database identifier string.
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 |
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::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. |
unsigned long sbIDatabaseQuery::getQueryCount | ( | ) |
Return the number of query strings enqueued for execution.
sbIDatabasePreparedStatement sbIDatabaseQuery::getQuery | ( | in unsigned long | nIndex | ) |
Get the query at the Nth index.
nIndex | The index into the queue |
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.
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.
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.
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::execute | ( | ) |
Execute the queries enqueued in the object.
long sbIDatabaseQuery::waitForCompletion | ( | ) |
Wait until the query has finished executing asynchronously.
If the query is not executing, this immediately returns.
boolean sbIDatabaseQuery::isExecuting | ( | ) |
Return whether or not the query is currently executing.
unsigned long sbIDatabaseQuery::currentQuery | ( | ) |
Return the current index in the queue being indexed.
boolean sbIDatabaseQuery::abort | ( | ) |
Abort a currently executing query.
This method blocks until the query has aborted
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 |
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::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 |
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 179 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 371 of file sbIDatabaseQuery.idl.