Classes | Public Member Functions | Private Types | Private Member Functions | Private Attributes | Friends

ASql::Query Class Reference

Class for storing query data to be passed and retrieved from statements. More...

#include <asql.hpp>

List of all members.

Classes

struct  SharedData
 Sub-structure to store shared data for the query. More...

Public Member Functions

 Query ()
 Calling the default constructor will set FLAG_ORIGINAL and create new shared data.
 Query (const Query &x)
 Calling the copy constructor will not set FLAG_ORIGINAL or create new shared data.
 ~Query ()
 If the original object, cancel() is called.
unsigned int insertId () const
 Returns the insert ID returned from the query or 0 if nothing.
unsigned int rows () const
 Returns the rows affected/available from the query or 0 if nothing.
bool busy () const
 Returns true if copies of this query still exist (query is still working in another thread).
Error error () const
 Return the error object associated with the query.
void setCallback (boost::function< void()> callback=boost::function< void()>())
 Set the callback function to be called at the end of the query.
bool isCallback ()
 Return true if a callback is associated with this query.
boost::function< void()> getCallback ()
 Get the callback function.
void keepAlive (bool x)
 Set true if you want the query to not be cancelled when the original object is destroyed.
void cancel ()
 Call this function to cancel the query.
void clearCancel ()
 Call for some reason if you want to clear a cancel request.
void enableRows ()
 Call this function to enable the retrieval of a row count (affected/available rows)
void enableInsertId ()
 Call this function to enable the retrieval of an auto-increment insert ID.
void setResults (Data::Set *results)
 Set's the shared data to point to the passed single row result set.
void setResults (Data::SetContainer *results)
 Set's the shared data to point to the passed multi-row result set.
void setParameters (Data::Set *parameters)
 Set's the shared data to point to the passed single row parameter set.
void setParameters (Data::SetContainer *parameters)
 Set's the shared data to point to the passed multi-row parameter set.
void manageResults (bool manage)
 Set whether or not the Query object should manage destruction of the result data.
void manageParameters (bool manage)
 Set whether or not the Query object should manage destruction of the parameter data.
template<class T >
T * createResults ()
 Little inline helper function to create result sets of a specific type.
template<class T >
T * createParameters ()
 Little inline helper function to create parameter sets of a specific type.
void relinquishResults ()
 Relinquishes control over the result set.
void relinquishParameters ()
 Relinquishes control over the parameter set.
void * results ()
 Return a void pointer to the result set.
void * parameters ()
 Return a void pointer to the parameter set.
void clearResults ()
 Destroy the result set (if suppose to) and relinquish.
void clearParameters ()
 Destroy the parameter set (if suppose to) relinquish.
void reset ()
 Reset the query object as though you are making it anew from the default constructor.

Private Types

enum  Flags { FLAG_ORIGINAL = 1, FLAG_KEEPALIVE = 1<<1 }

Private Member Functions

void callback ()
 Lock and call the callback function of it exists.

Private Attributes

boost::shared_ptr< SharedDatam_sharedData
 Shared pointer to query data.
unsigned char m_flags
 Flags for individual query object.

Friends

class ConnectionPar

Detailed Description

Class for storing query data to be passed and retrieved from statements.

This will contain all data associated with an individual query. With it one can retrieve results, set arguments, and set various query parameters that can be checked/set with the public access functions.

Most of the data is stored in a shared data structure that is referenced by copies of a Query object. The only non-shared data stored in the class is the m_flags object which set's two possible flags. If the query is built from the default constructor, the FLAG_ORIGINAL flag is set. This serves the purpose of keeping track of which query object actually owns the original data. With this, one can have the query cancelled in it's handler thread if the original query object goes out of scope in it's own thread. If one wishes to avoid this behaviour they can have the FLAG_KEEPALIVE flag set with the keepAlive() function.

Definition at line 705 of file asql.hpp.


Member Enumeration Documentation

enum ASql::Query::Flags [private]
Enumerator:
FLAG_ORIGINAL 
FLAG_KEEPALIVE 

Definition at line 835 of file asql.hpp.


Constructor & Destructor Documentation

ASql::Query::Query (  ) [inline]

Calling the default constructor will set FLAG_ORIGINAL and create new shared data.

Definition at line 854 of file asql.hpp.

ASql::Query::Query ( const Query x ) [inline]

Calling the copy constructor will not set FLAG_ORIGINAL or create new shared data.

Parameters:
xMay be a copy or original Query object.

Definition at line 860 of file asql.hpp.

ASql::Query::~Query (  ) [inline]

If the original object, cancel() is called.

Definition at line 864 of file asql.hpp.

References cancel(), FLAG_ORIGINAL, and m_flags.


Member Function Documentation

bool ASql::Query::busy (  ) const [inline]

Returns true if copies of this query still exist (query is still working in another thread).

Definition at line 883 of file asql.hpp.

References m_sharedData.

void ASql::Query::callback (  ) [inline, private]

Lock and call the callback function of it exists.

Definition at line 840 of file asql.hpp.

References m_sharedData.

Referenced by ASql::ConnectionPar< T >::intHandler(), and setCallback().

void ASql::Query::cancel (  ) [inline]

Call this function to cancel the query.

This will cancel the query at the earliest opportunity. Calling a cancel will rollback any changes in the associated transaction.

Definition at line 924 of file asql.hpp.

References m_sharedData.

Referenced by ~Query().

void ASql::Query::clearCancel (  ) [inline]

Call for some reason if you want to clear a cancel request.

Definition at line 928 of file asql.hpp.

References m_sharedData.

void ASql::Query::clearParameters (  ) [inline]

Destroy the parameter set (if suppose to) relinquish.

Definition at line 1050 of file asql.hpp.

References m_sharedData, and relinquishParameters().

void ASql::Query::clearResults (  ) [inline]

Destroy the result set (if suppose to) and relinquish.

Definition at line 1046 of file asql.hpp.

References m_sharedData, and relinquishResults().

Referenced by ASql::ConnectionPar< T >::intHandler().

template<class T >
T* ASql::Query::createParameters (  ) [inline]

Little inline helper function to create parameter sets of a specific type.

It will return a pointer to the newly created object and set it as the Query objects parameter set.

Template Parameters:
TType to create. Must be derived from either Data::Set or Data::SetContainer. Suggest using one of the template wrapper types defined in Data.

Definition at line 1010 of file asql.hpp.

References parameters(), and setParameters().

template<class T >
T* ASql::Query::createResults (  ) [inline]

Little inline helper function to create result sets of a specific type.

It will return a pointer to the newly created object and set it as the Query objects result set.

Template Parameters:
TType to create. Must be derived from either Data::Set or Data::SetContainer. Suggest using one of the template wrapper types defined in Data.

Definition at line 1001 of file asql.hpp.

References results(), and setResults().

void ASql::Query::enableInsertId (  ) [inline]

Call this function to enable the retrieval of an auto-increment insert ID.

Definition at line 940 of file asql.hpp.

References m_sharedData.

void ASql::Query::enableRows (  ) [inline]

Call this function to enable the retrieval of a row count (affected/available rows)

Definition at line 932 of file asql.hpp.

References m_sharedData.

Error ASql::Query::error (  ) const [inline]

Return the error object associated with the query.

Note this will be a default Error object if there was no error.

Definition at line 889 of file asql.hpp.

References m_sharedData.

boost::function<void()> ASql::Query::getCallback (  ) [inline]

Get the callback function.

Definition at line 908 of file asql.hpp.

References m_sharedData.

Referenced by ASql::ConnectionPar< T >::intHandler().

unsigned int ASql::Query::insertId (  ) const [inline]

Returns the insert ID returned from the query or 0 if nothing.

Definition at line 872 of file asql.hpp.

References m_sharedData.

bool ASql::Query::isCallback (  ) [inline]

Return true if a callback is associated with this query.

Definition at line 904 of file asql.hpp.

References m_sharedData.

Referenced by ASql::ConnectionPar< T >::intHandler().

void ASql::Query::keepAlive ( bool  x ) [inline]

Set true if you want the query to not be cancelled when the original object is destroyed.

Note that the default is to cancel and this must be called from the original query.

Definition at line 917 of file asql.hpp.

References FLAG_KEEPALIVE, and m_flags.

Referenced by reset().

void ASql::Query::manageParameters ( bool  manage ) [inline]

Set whether or not the Query object should manage destruction of the parameter data.

True means that it will destroy the parameter data when it sees fit. False leaves that responsibility to you (the memory will leak if you don't explicitly delete it at some point. This obviously defaults to true.

Be very careful with this. Often times relinquishParameters() will be a better option for what you might be trying to do.

Definition at line 991 of file asql.hpp.

References ASql::Query::SharedData::FLAG_NO_MANAGE_PARAMETERS, and m_sharedData.

void ASql::Query::manageResults ( bool  manage ) [inline]

Set whether or not the Query object should manage destruction of the result data.

True means that it will destroy the result data when it sees fit. False leaves that responsibility to you (the memory will leak if you don't explicitly delete it at some point. This obviously defaults to true.

Be very careful with this. Often times relinquishResults() will be a better option for what you might be trying to do.

Definition at line 982 of file asql.hpp.

References ASql::Query::SharedData::FLAG_NO_MANAGE_RESULTS, and m_sharedData.

void* ASql::Query::parameters (  ) [inline]

Return a void pointer to the parameter set.

Usually you would keep the original typed pointer around but if you lost it for some reason you can use this and cast it.

Definition at line 1041 of file asql.hpp.

References m_sharedData.

Referenced by createParameters(), ASql::ConnectionPar< T >::intHandler(), and setParameters().

void ASql::Query::relinquishParameters (  ) [inline]

Relinquishes control over the parameter set.

Calling this will disassociate the query object (and it's copies) from the parameter set but won't delete it. Use this if you are done with your query object but want to keep your parameter set around. The end result in the query object (and it's copies) is to have no parameter set associated with it.

Definition at line 1028 of file asql.hpp.

References ASql::Query::SharedData::FLAG_SINGLE_PARAMETERS, and m_sharedData.

Referenced by clearParameters().

void ASql::Query::relinquishResults (  ) [inline]

Relinquishes control over the result set.

Calling this will disassociate the query object (and it's copies) from the result set but won't delete it. Use this if you are done with your query object but want to keep your result set around. The end result in the query object (and it's copies) is to have no result set associated with it.

Definition at line 1020 of file asql.hpp.

References m_sharedData.

Referenced by clearResults().

void ASql::Query::reset (  ) [inline]

Reset the query object as though you are making it anew from the default constructor.

This is effectively like destroying the query object and creating a brand new one with the same name. Note that FLAG_ORIGINAL will be set after doing this.

Definition at line 1058 of file asql.hpp.

References FLAG_ORIGINAL, keepAlive(), m_flags, and m_sharedData.

void* ASql::Query::results (  ) [inline]

Return a void pointer to the result set.

Usually you would keep the original typed pointer around but if you lost it for some reason you can use this and cast it.

Definition at line 1035 of file asql.hpp.

References m_sharedData.

Referenced by createResults(), ASql::ConnectionPar< T >::intHandler(), and setResults().

unsigned int ASql::Query::rows (  ) const [inline]

Returns the rows affected/available from the query or 0 if nothing.

Note that if using for the number of rows from a query this will represent the number of rows available before a LIMIT.

Definition at line 879 of file asql.hpp.

References m_sharedData.

void ASql::Query::setCallback ( boost::function< void()>  callback = boost::function<void()>() ) [inline]

Set the callback function to be called at the end of the query.

Note that this will be called even if there is an error or the query can cancelled.

Definition at line 896 of file asql.hpp.

References callback(), and m_sharedData.

Referenced by ASql::ConnectionPar< T >::intHandler().

void ASql::Query::setParameters ( Data::SetContainer parameters ) [inline]

Set's the shared data to point to the passed multi-row parameter set.

Note that the Query class assumes responsibility for destroying the parameter set unless explicitly told not to with manageParameters().

Definition at line 973 of file asql.hpp.

References m_sharedData, and parameters().

void ASql::Query::setParameters ( Data::Set parameters ) [inline]

Set's the shared data to point to the passed single row parameter set.

Note that the Query class assumes responsibility for destroying the parameter set unless explicitly told not to with manageParameters().

Definition at line 966 of file asql.hpp.

References ASql::Query::SharedData::FLAG_SINGLE_PARAMETERS, m_sharedData, and parameters().

Referenced by createParameters().

void ASql::Query::setResults ( Data::SetContainer results ) [inline]

Set's the shared data to point to the passed multi-row result set.

Note that the Query class assumes responsibility for destroying the result set unless explicitly told not to with manageResults().

Definition at line 959 of file asql.hpp.

References m_sharedData, and results().

void ASql::Query::setResults ( Data::Set results ) [inline]

Set's the shared data to point to the passed single row result set.

Note that the Query class assumes responsibility for destroying the result set unless explicitly told not to with manageResults().

Definition at line 952 of file asql.hpp.

References ASql::Query::SharedData::FLAG_SINGLE_RESULTS, m_sharedData, and results().

Referenced by createResults().


Friends And Related Function Documentation

friend class ConnectionPar [friend]

Definition at line 848 of file asql.hpp.


Member Data Documentation

unsigned char ASql::Query::m_flags [private]

Flags for individual query object.

FLAG_ORIGINAL: Set only if this query object was constructed with the default constructor. Never set if constructed from the copy constructor.

FLAG_KEEPALIVE: Set if the query should not be cancelled if the original object goes out of scope before the query is complete.

Definition at line 833 of file asql.hpp.

Referenced by keepAlive(), reset(), and ~Query().

boost::shared_ptr<SharedData> ASql::Query::m_sharedData [private]

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