WARNING: USE THIS SOFTWARE AT YOUR OWN RISK! THIS IS EXPERIMENTAL SOFTWARE NOT INTENDED FOR PRODUCTION USE! Zuble is currently an early stage prototype. As such Zuble is minimally tested and inherently unstable. It is provided for experimental, development, and demonstration purposes only. Zuble QML Types   |  Zuble C++ Classes   |  Zuble Overview
Zuble  0.1
Zuble Framework C++/QML extension API
Public Types | Signals | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Static Protected Attributes | Properties | List of all members
Zbl::ZsqlQuery Class Reference

A javascript wrapper class for QSqlQuery objects. This object represents a query on a database connection. More...

#include <ZsqlQuery.h>

Inheritance diagram for Zbl::ZsqlQuery:
Inheritance graph
[legend]
Collaboration diagram for Zbl::ZsqlQuery:
Collaboration graph
[legend]

Public Types

enum  BatchExecutionMode { ValuesAsRows = QSqlQuery::ValuesAsRows, ValuesAsColumns = QSqlQuery::ValuesAsColumns }
 
enum  ParamType { In = QSql::In, Out = QSql::Out, InOut = QSql::InOut, Binary = QSql::Binary }
 
enum  ResultType { StringSequence = 0, TableModel }
 
typedef QList< QString > zMetaRow
 

Signals

void queryResult (QObject *qResult)
 

Public Member Functions

 ZsqlQuery (QSqlQuery *query, QObject *parent=0)
 
virtual ~ZsqlQuery ()
 
QSqlQuery & queryObject () const
 
bool getTableModel (ZTableModel *model)
 
QVariant getTags ()
 Obtains a javascript dictionary object that maps constants, enumerations and flags for use with ZsqlQuery objects. More...
 
bool isValid () const
 
bool isActive () const
 
bool isForwardOnly () const
 
void setForwardOnly (bool forward)
 
int getPosition () const
 
QString lastQuery () const
 
int numRowsAffected () const
 
QObject * getLastError ()
 
bool isSelect () const
 
int size () const
 
void setNumericalPrecisionPolicy (int policy)
 
int getNumericalPrecisionPolicy () const
 
QVariant getBoundValues () const
 
QString getExecutedQuery () const
 
QVariant getLastInsertId () const
 
zMetaRow getMetaRow () const
 
QVariant getJsMetaRow () const
 
Q_INVOKABLE void release ()
 Releases references from this object to wrapped Qt C++ objects. More...
 
Q_INVOKABLE void bindValue (const QString &placeholder, const QVariant &value, int paramType)
 
Q_INVOKABLE QVariant boundValue (const QString &placeholder) const
 
Q_INVOKABLE QVariant value (const QString &name) const
 
Q_INVOKABLE bool isNull (int field) const
 
Q_INVOKABLE bool exec ()
 
Q_INVOKABLE bool prepare (const QString &query)
 
Q_INVOKABLE bool exec (const QString &query, int resultType, QObject *tableModel)
 Executes the specified SQL query against the database. More...
 
Q_INVOKABLE QVariant value (int i) const
 Returns the value of field index in the current record. More...
 
Q_INVOKABLE bool seek (int i, bool relative=false)
 
Q_INVOKABLE bool next ()
 Retrieves the next record in the result, if available, and positions the query on the retrieved record. More...
 
Q_INVOKABLE bool previous ()
 Retrieves the previous record in the result, if available, and positions the query on the retrieved record. More...
 
Q_INVOKABLE bool first ()
 Retrieves the first record in the result, if available, and positions the query on the retrieved record. More...
 
Q_INVOKABLE bool last ()
 Retrieves the last record in the result, if available, and positions the query on the retrieved record. More...
 
Q_INVOKABLE void clear ()
 Clears the result set and releases any resources held by the query. Sets the query state to inactive. More...
 
Q_INVOKABLE void finish ()
 Instruct the database driver that no more data will be fetched from this query until it is re-executed. More...
 
Q_INVOKABLE bool nextResult ()
 Discards the current result set and navigates to the next if available. More...
 
Q_INVOKABLE QObject * record ()
 Obtains a ZsqlRecord object representing the query result. More...
 
Q_INVOKABLE bool populateTableModel (QObject *model)
 Populates an empty ZTableModel object with the query result. More...
 
Q_INVOKABLE QVariant boundValue (int pos) const
 Returns the value for the placeholder at position pos. More...
 
Q_INVOKABLE bool execBatch (int mode=ValuesAsRows)
 Executes a previously prepared SQL query in a batch. More...
 
Q_INVOKABLE void bindValue (int pos, const QVariant &val, ParamType type=In)
 Set the placeholder in position pos to be bound to value val in the prepared statement. More...
 
Q_INVOKABLE void addBindValue (const QVariant &val, ZsqlQuery::ParamType=In)
 Adds the value val to the list of values when using positional value binding. More...
 

Static Public Member Functions

static ZsqlQuerynewQuery (ZsqlDatabase &database)
 Constructs an empty ZsqlQuery object for the specified database connection. More...
 

Protected Member Functions

void initGetTableModel ()
 Checks that the embedded QSqlQuery object can populate a Zuble table model from it's result sets and throws a ZblException if not. More...
 
void validateQuery () const
 Checks that the embedded QSqlQuery object exists and throws a ZblException if not. More...
 
void createTags ()
 Create the m_tag object that presents a Javascript interface for ZsqlQuery enumeration values. More...
 
void ensureParamType (int paramType)
 Checks the specified value and throws a ZblException if it isn't a ZsqlQuery::ParamType value. More...
 

Protected Attributes

QSqlQuery * m_q
 Encapsulated QSqlQuery object. More...
 

Static Protected Attributes

static QVariant m_tags
 A QVariantMap used to pass ZsqlQuery enumeration values to Javascript programs. More...
 

Properties

QVariant tags
 Obtains a javascript dictionary object that maps constants, enumerations and flags for use with ZsqlQuery objects. More...
 
bool isValid
 Determines if the query is currently positioned on a valid record. More...
 
bool isActive
 Determines if the query is currently active. More...
 
bool forewardOnly
 Determines if the query is a forward only query. More...
 
int position
 Determines the position of the current record. More...
 
QString lastQuery
 Returns the text of the last query. More...
 
int numRowsAffected
 Returns the number of rows affected by the last query. More...
 
QObject lastError
 Returns a ZsqlError object representing the last error encountered by this query. More...
 
bool isSelect
 Determines if this query is a SELECT statement. More...
 
int size
 Determines the number of rows returned by this query. More...
 
int numericalPrecisionPolicy
 Determines the numerical precision policy of the query. More...
 
QVariant boundValues
 Returns a list of bound values for the query. More...
 
QString executedQuery
 Returns the text of the last executed query. More...
 
QVariant lastInsertId
 Returns the ID of the last inserted row. More...
 
QVariant metaRow
 Returns the ID of the last inserted row. More...
 

Detailed Description

A javascript wrapper class for QSqlQuery objects. This object represents a query on a database connection.

ZsqlQuery objects are children of the ZsqlDatabase object that created them. They're destroyed when their parent ZsqlDatabase object is destroyed.

Call ZsqlQuery::release() to delete the encapsulated QSqlQuery object.

ZsqlQuery object methods are reentrant unless explicitly noted to be "thread-safe". Reentrant methods should only be called by the thread that created the ZsqlQuery object.

See also
ZsqlDatabase
ZsqlDatabase::newQuery()
ZsqlDatabase::release()
ZsqlQuery::release()

Definition at line 67 of file ZsqlQuery.h.

Member Typedef Documentation

◆ zMetaRow

typedef QList<QString> Zbl::ZsqlQuery::zMetaRow

Definition at line 71 of file ZsqlQuery.h.

Member Enumeration Documentation

◆ BatchExecutionMode

Enumerator
ValuesAsRows 
ValuesAsColumns 

Definition at line 75 of file ZsqlQuery.h.

◆ ParamType

Enumerator
In 
Out 
InOut 
Binary 

Definition at line 83 of file ZsqlQuery.h.

◆ ResultType

Enumerator
StringSequence 
TableModel 

Definition at line 93 of file ZsqlQuery.h.

Constructor & Destructor Documentation

◆ ZsqlQuery()

Zbl::ZsqlQuery::ZsqlQuery ( QSqlQuery *  query,
QObject *  parent = 0 
)
explicit

Definition at line 40 of file ZsqlQuery.cpp.

Referenced by newQuery().

◆ ~ZsqlQuery()

Zbl::ZsqlQuery::~ZsqlQuery ( )
virtual

Definition at line 48 of file ZsqlQuery.cpp.

Member Function Documentation

◆ addBindValue()

void Zbl::ZsqlQuery::addBindValue ( const QVariant &  val,
ZsqlQuery::ParamType  type = In 
)

Adds the value val to the list of values when using positional value binding.

The order of the addBindValue() calls determines which placeholder a value will be bound to in the prepared query. If paramType is QSql::Out or QSql::InOut, the placeholder will be overwritten with data from the database after the exec() call.

Parameters
valvalue to bind to next placeholder position
typeparameter type must be one of: In, Out, InOut, Binary

Definition at line 621 of file ZsqlQuery.cpp.

◆ bindValue() [1/2]

void Zbl::ZsqlQuery::bindValue ( const QString &  placeholder,
const QVariant &  value,
int  paramType 
)
Parameters

Definition at line 205 of file ZsqlQuery.cpp.

Referenced by bindValue().

◆ bindValue() [2/2]

void Zbl::ZsqlQuery::bindValue ( int  pos,
const QVariant &  val,
ZsqlQuery::ParamType  type = In 
)

Set the placeholder in position pos to be bound to value val in the prepared statement.

Field numbering starts at 0. If paramType is QSql::Out or QSql::InOut, the placeholder will be overwritten with data from the database after the exec() call.

Parameters
posfield position of the value to bind
valvalue to bind to specified field position
typeparameter type must be one of: In, Out, InOut, Binary

Definition at line 612 of file ZsqlQuery.cpp.

◆ boundValue() [1/2]

QVariant Zbl::ZsqlQuery::boundValue ( const QString &  placeholder) const
Parameters

Definition at line 215 of file ZsqlQuery.cpp.

Referenced by boundValue().

◆ boundValue() [2/2]

QVariant Zbl::ZsqlQuery::boundValue ( int  pos) const

Returns the value for the placeholder at position pos.

Parameters
posfield position of the bound value to return
Returns
the specified bound value

Definition at line 589 of file ZsqlQuery.cpp.

◆ clear()

void Zbl::ZsqlQuery::clear ( )

Clears the result set and releases any resources held by the query. Sets the query state to inactive.

Definition at line 563 of file ZsqlQuery.cpp.

◆ createTags()

void Zbl::ZsqlQuery::createTags ( )
protected

Create the m_tag object that presents a Javascript interface for ZsqlQuery enumeration values.

Definition at line 54 of file ZsqlQuery.cpp.

Referenced by ZsqlQuery().

◆ ensureParamType()

void Zbl::ZsqlQuery::ensureParamType ( int  paramType)
protected

Checks the specified value and throws a ZblException if it isn't a ZsqlQuery::ParamType value.

Definition at line 72 of file ZsqlQuery.cpp.

Referenced by addBindValue(), and bindValue().

◆ exec() [1/2]

bool Zbl::ZsqlQuery::exec ( )
Returns

Definition at line 263 of file ZsqlQuery.cpp.

Referenced by exec().

◆ exec() [2/2]

bool Zbl::ZsqlQuery::exec ( const QString &  query,
int  resultType,
QObject *  tableModel 
)

Executes the specified SQL query against the database.

Use ResultType = ResultType::StringSequence to receive a sequence of 'query result' signals; // TBD: DEPRECATE?

Use ResultType = ResultType::TableModel to receive a single 'table-model' signal

Parameters
queryA string containing the SQL query to execute
resultTypedetermines how query results will be returned
Returns
true if success, false if an error occurred

Definition at line 314 of file ZsqlQuery.cpp.

◆ execBatch()

bool Zbl::ZsqlQuery::execBatch ( int  mode = ValuesAsRows)

Executes a previously prepared SQL query in a batch.

All the bound parameters have to be lists of variants. If the database doesn't support batch executions, the driver will simulate it using conventional exec() calls.

Parameters
modeBatch execution mode, ValuesAsRows or ValuesAsColumns
Returns
true if the query is executed successfully, false otherwise

Definition at line 597 of file ZsqlQuery.cpp.

◆ finish()

void Zbl::ZsqlQuery::finish ( )

Instruct the database driver that no more data will be fetched from this query until it is re-executed.

There is normally no need to call this function, but it may be helpful in order to free resources such as locks or cursors if you intend to re-use the query at a later time.

Sets the query to inactive. Bound values retain their values.

Definition at line 572 of file ZsqlQuery.cpp.

◆ first()

bool Zbl::ZsqlQuery::first ( )

Retrieves the first record in the result, if available, and positions the query on the retrieved record.

Note that the result must be in the active state and isSelect() must return true before calling this function or it will do nothing and return false.

Returns
true if successful, false if failed

Definition at line 547 of file ZsqlQuery.cpp.

◆ getBoundValues()

QVariant Zbl::ZsqlQuery::getBoundValues ( ) const

Definition at line 490 of file ZsqlQuery.cpp.

◆ getExecutedQuery()

QString Zbl::ZsqlQuery::getExecutedQuery ( ) const

Definition at line 498 of file ZsqlQuery.cpp.

◆ getJsMetaRow()

QVariant Zbl::ZsqlQuery::getJsMetaRow ( ) const

Definition at line 382 of file ZsqlQuery.cpp.

◆ getLastError()

QObject * Zbl::ZsqlQuery::getLastError ( )

Definition at line 417 of file ZsqlQuery.cpp.

◆ getLastInsertId()

QVariant Zbl::ZsqlQuery::getLastInsertId ( ) const

Definition at line 506 of file ZsqlQuery.cpp.

◆ getMetaRow()

ZsqlQuery::zMetaRow Zbl::ZsqlQuery::getMetaRow ( ) const

Definition at line 366 of file ZsqlQuery.cpp.

Referenced by getJsMetaRow(), and getTableModel().

◆ getNumericalPrecisionPolicy()

int Zbl::ZsqlQuery::getNumericalPrecisionPolicy ( ) const

Definition at line 482 of file ZsqlQuery.cpp.

◆ getPosition()

int Zbl::ZsqlQuery::getPosition ( ) const

Definition at line 289 of file ZsqlQuery.cpp.

◆ getTableModel()

bool Zbl::ZsqlQuery::getTableModel ( ZTableModel model)

Definition at line 100 of file ZsqlQuery.cpp.

Referenced by exec(), and populateTableModel().

◆ getTags()

QVariant Zbl::ZsqlQuery::getTags ( )

Obtains a javascript dictionary object that maps constants, enumerations and flags for use with ZsqlQuery objects.

Returns
a javascript dictionary

Definition at line 189 of file ZsqlQuery.cpp.

◆ initGetTableModel()

void Zbl::ZsqlQuery::initGetTableModel ( )
protected

Checks that the embedded QSqlQuery object can populate a Zuble table model from it's result sets and throws a ZblException if not.

Definition at line 86 of file ZsqlQuery.cpp.

Referenced by getTableModel().

◆ isActive()

bool Zbl::ZsqlQuery::isActive ( ) const

Referenced by isNull().

◆ isForwardOnly()

bool Zbl::ZsqlQuery::isForwardOnly ( ) const

Definition at line 254 of file ZsqlQuery.cpp.

◆ isNull()

bool Zbl::ZsqlQuery::isNull ( int  field) const
Parameters

Definition at line 231 of file ZsqlQuery.cpp.

◆ isSelect()

bool Zbl::ZsqlQuery::isSelect ( ) const

Referenced by getLastError().

◆ isValid()

bool Zbl::ZsqlQuery::isValid ( ) const

Referenced by isNull().

◆ last()

bool Zbl::ZsqlQuery::last ( )

Retrieves the last record in the result, if available, and positions the query on the retrieved record.

Note that the result must be in the active state and isSelect() must return true before calling this function or it will do nothing and return false.

Returns
true if successful, false if failed

Definition at line 555 of file ZsqlQuery.cpp.

◆ lastQuery()

QString Zbl::ZsqlQuery::lastQuery ( ) const

Referenced by getPosition().

◆ newQuery()

ZsqlQuery * Zbl::ZsqlQuery::newQuery ( ZsqlDatabase database)
static

Constructs an empty ZsqlQuery object for the specified database connection.

Parameters
databaseAn open database connection for which a ZsqlQuery object is returned
Returns
a ZsqlQuery object for the specified database

Definition at line 149 of file ZsqlQuery.cpp.

Referenced by Zbl::ZsqlDatabase::newQuery().

◆ next()

bool Zbl::ZsqlQuery::next ( )

Retrieves the next record in the result, if available, and positions the query on the retrieved record.

Note that the result must be in the active state and isSelect() must return true before calling this function or it will do nothing and return false.

Returns
true if successful, false if failed

Definition at line 531 of file ZsqlQuery.cpp.

◆ nextResult()

bool Zbl::ZsqlQuery::nextResult ( )

Discards the current result set and navigates to the next if available.

Returns
true if another result was available, false otherwise

Definition at line 581 of file ZsqlQuery.cpp.

◆ numRowsAffected()

int Zbl::ZsqlQuery::numRowsAffected ( ) const

Referenced by getPosition().

◆ populateTableModel()

bool Zbl::ZsqlQuery::populateTableModel ( QObject *  model)

Populates an empty ZTableModel object with the query result.

This method modifies the current position of the query. Upon return from this method the query's current position is undefined.

Parameters
modelA ZTableModel object to receive the query data
Returns
true if successful, false if error

Definition at line 354 of file ZsqlQuery.cpp.

◆ prepare()

bool Zbl::ZsqlQuery::prepare ( const QString &  query)
Parameters

Definition at line 271 of file ZsqlQuery.cpp.

◆ previous()

bool Zbl::ZsqlQuery::previous ( )

Retrieves the previous record in the result, if available, and positions the query on the retrieved record.

Note that the result must be in the active state and isSelect() must return true before calling this function or it will do nothing and return false.

Returns
true if successful, false if failed

Definition at line 539 of file ZsqlQuery.cpp.

◆ queryObject()

QSqlQuery & Zbl::ZsqlQuery::queryObject ( ) const
inline

Definition at line 568 of file ZsqlQuery.h.

◆ queryResult

void Zbl::ZsqlQuery::queryResult ( QObject *  qResult)
signal

Referenced by exec().

◆ record()

QObject * Zbl::ZsqlQuery::record ( )

Obtains a ZsqlRecord object representing the query result.

Returns
a ZsqlRecord object for this query

Definition at line 630 of file ZsqlQuery.cpp.

Referenced by Zbl::ZsqlDatabase::record().

◆ release()

void Zbl::ZsqlQuery::release ( )

Releases references from this object to wrapped Qt C++ objects.

The C++ objects may be deleted by this function if no other Javascript objects reference them at the time this method is called.

WARNING: The ZsqlQuery object can't be used again once this function is called.

Definition at line 194 of file ZsqlQuery.cpp.

Referenced by Zbl::ZsqlDatabase::release(), and ~ZsqlQuery().

◆ seek()

bool Zbl::ZsqlQuery::seek ( int  i,
bool  relative = false 
)
Parameters

Definition at line 523 of file ZsqlQuery.cpp.

◆ setForwardOnly()

void Zbl::ZsqlQuery::setForwardOnly ( bool  forward)

Definition at line 280 of file ZsqlQuery.cpp.

◆ setNumericalPrecisionPolicy()

void Zbl::ZsqlQuery::setNumericalPrecisionPolicy ( int  policy)

Definition at line 456 of file ZsqlQuery.cpp.

◆ size()

int Zbl::ZsqlQuery::size ( ) const

Referenced by getLastError().

◆ validateQuery()

void Zbl::ZsqlQuery::validateQuery ( ) const
inlineprotected

◆ value() [1/2]

QVariant Zbl::ZsqlQuery::value ( const QString &  name) const
Parameters

Definition at line 223 of file ZsqlQuery.cpp.

Referenced by value().

◆ value() [2/2]

QVariant Zbl::ZsqlQuery::value ( int  i) const

Returns the value of field index in the current record.

The fields are numbered from left to right using the text of the SELECT statement, e.g. in "SELECT forename, surname FROM people;" field 0 is forename and field 1 is surname. Using SELECT * is not recommended because the order of the fields in the query is undefined.

An invalid QVariant is returned if field index does not exist, if the query is inactive, or if the query is positioned on an invalid record.

Parameters
ifield index of the current record
Returns
value of the current field index

Definition at line 514 of file ZsqlQuery.cpp.

Member Data Documentation

◆ m_q

QSqlQuery* Zbl::ZsqlQuery::m_q
protected

◆ m_tags

QVariant Zbl::ZsqlQuery::m_tags
staticprotected

A QVariantMap used to pass ZsqlQuery enumeration values to Javascript programs.

This object is automatically converted to a Javascript object by Qt.

Definition at line 555 of file ZsqlQuery.h.

Referenced by createTags(), and getTags().

Property Documentation

◆ boundValues

QVariant Zbl::ZsqlQuery::boundValues
read

Returns a list of bound values for the query.

Definition at line 194 of file ZsqlQuery.h.

◆ executedQuery

QString Zbl::ZsqlQuery::executedQuery
read

Returns the text of the last executed query.

Definition at line 199 of file ZsqlQuery.h.

◆ forewardOnly

bool Zbl::ZsqlQuery::forewardOnly
readwrite

Determines if the query is a forward only query.

Returns
true if query is forwared, false otherwise

Definition at line 144 of file ZsqlQuery.h.

◆ isActive

bool Zbl::ZsqlQuery::isActive
read

Determines if the query is currently active.

A query is active if it has successfully completed exec() and has not since had finish() or clear() called.

Returns
true if query is active, false otherwise

Definition at line 138 of file ZsqlQuery.h.

◆ isSelect

bool Zbl::ZsqlQuery::isSelect
read

Determines if this query is a SELECT statement.

Returns
true if this query is a SELECT statement, false otherwise

Definition at line 175 of file ZsqlQuery.h.

◆ isValid

bool Zbl::ZsqlQuery::isValid
read

Determines if the query is currently positioned on a valid record.

Returns
true if current record is valid, false otherwise

Definition at line 129 of file ZsqlQuery.h.

◆ lastError

QObject Zbl::ZsqlQuery::lastError
read

Returns a ZsqlError object representing the last error encountered by this query.

Returns
ZsqlError object

Definition at line 169 of file ZsqlQuery.h.

◆ lastInsertId

QVariant Zbl::ZsqlQuery::lastInsertId
read

Returns the ID of the last inserted row.

Definition at line 204 of file ZsqlQuery.h.

◆ lastQuery

QString Zbl::ZsqlQuery::lastQuery
read

Returns the text of the last query.

Returns
query text

Definition at line 156 of file ZsqlQuery.h.

◆ metaRow

QVariant Zbl::ZsqlQuery::metaRow
read

Returns the ID of the last inserted row.

Definition at line 209 of file ZsqlQuery.h.

Referenced by getJsMetaRow(), getMetaRow(), and getTableModel().

◆ numericalPrecisionPolicy

int Zbl::ZsqlQuery::numericalPrecisionPolicy
readwrite

Determines the numerical precision policy of the query.

Definition at line 189 of file ZsqlQuery.h.

◆ numRowsAffected

int Zbl::ZsqlQuery::numRowsAffected
read

Returns the number of rows affected by the last query.

Returns
query text

Definition at line 162 of file ZsqlQuery.h.

◆ position

int Zbl::ZsqlQuery::position
read

Determines the position of the current record.

Returns
true if query is forwared, false otherwise

Definition at line 150 of file ZsqlQuery.h.

◆ size

int Zbl::ZsqlQuery::size
read

Determines the number of rows returned by this query.

Note: Use ZsqlQuery::numRowsAffected for non-SELECT statement queries.

Returns
an integer representing the number of rows returned.

Definition at line 183 of file ZsqlQuery.h.

◆ tags

QVariant Zbl::ZsqlQuery::tags
read

Obtains a javascript dictionary object that maps constants, enumerations and flags for use with ZsqlQuery objects.

Returns
a javascript dictionary

Definition at line 123 of file ZsqlQuery.h.


The documentation for this class was generated from the following files: