Class rude::Database
Constructor Summary |
protected |
Database( const char* contextName )
Database objects cannot be instantiated directly - instead, call instance() to obtain a reference to the object. |
|
virtual ~Database()
|
Method Summary |
static void |
addContext( const char* contextname, const char* database, const char* username, const char* password, const char* server, int port )
Specifies a database, username, password, server and port that will be identified by contextname. |
const char* |
column( int index )
Returns the value located at the specified column within the current row set |
static char* |
escape( const char* string, int length )
Escapes illegal characters within a string |
bool |
executeQuery( const char* query )
Sends queries that do not return a result (UPDATE, DELETE, CREATE, INSERT, ALTER, etc...) |
static void |
finish()
Closes all open database connections |
bool |
freeResult()
Frees resources consumed by a query result set |
const char* |
getError()
Returns the last known error |
int |
insertQuery( const char* query )
Sends an INSERT query and returns the insert id |
static Database* |
instance( const char* contextname )
Returns the singleton database object for a given context |
bool |
nextRow()
Selects the next row from query result set |
const char* |
singleValueQuery( const char* query )
Send a query that expects a single value result |
const char* |
stat()
Returns MYSQL server status information |
bool |
storeResultQuery( const char* query )
Sends a query that expects a result set - obtains results from server all at once (time friendly) |
bool |
useResultQuery( const char* query )
Sends a query that expects a result set - obtains results from server one row at a time (memory / network friendly) |
Database
protected Database( const char* contextName );
- Database objects cannot be instantiated directly - instead, call instance() to obtain a reference to the object.
This component uses the Singleton design pattern to ensure global accessability and improve performance.
This architecture allows multiple parts of your program to access a particular database without
having to worry about connecting or disconnecting to/from the database. If every section of your program
needed to use a database and was responsible for connecting/disconnecting, then multiple connections
would be opened and closed - consuming both resources and time. Our architecture ensures that a connection
is established once - and then only if necessary - and can be shared throughout the program. Multiple contexts
allow multiple connections to different databases or database accounts simultaneously.
~Database
public virtual ~Database();
-
addContext
public static void addContext( const char* contextname, const char* database, const char* username, const char* password, const char* server, int port );
- Specifies a database, username, password, server and port that will be identified by contextname.
The context name can be anything and is simply used as an identifier to the context.
After a context is added, the database represented by the context name can be obtained by
calling the Database::instance(contextname) method.
Any number of contexts can be added. Each context should have a unique contextname.
column
public const char* column( int index );
- Returns the value located at the specified column within the current row set
first index is 0.
will return NULL when out of range.
Example
if(database->storeResultQuery("SELECT fname, lname, address, age from tbl_contacts"))
{
while(database->nextRow())
{
const char *first_name = database->column(0);
const char *last_name = database->column(1);
const char *address = database->column(2);
// convert the age to integer
//
int age = atoi( database->column(3) );
// do stuff with data.....
}
database->freeResult();
}
else
{
std::cout << database->getError() << "\n";
}
escape
public static char* escape( const char* string, int length );
- Escapes illegal characters within a string
This ensures that string or binary data won't mess up your queries.
You should escape all string data that can possibly be tainted (eg. you are not sure what is in it).
The caller (you) is responsible for deleting the resulting string.
Note: To avoid memory leaks, you MUST delete the resulting string.
As such, the following sequence should always be followed when using this method:
// 1. Obtain safe strings ( as a static method, it can be called through an object or directly from the class )
//
const char *safe_string = database->escape( unsafe_string , strlen(unsafe_string) );
const char *safe_string2 = rude::Database::escape( another_string, strlen(another_string) );
// 2. ... use the safe strings
// 3. Delete the safe strings
//
delete [] safe_string
delete [] safe_string2
Example:
// Obtain database object
//
rude::Database *database = rude::Database::instance("stock");
const char *catname="A very ''' Awkward ===== Category Name !!'' \"\"\" ****** Indeed!!";
// Escape illegal characters in the new category name
//
char *safe_name = database->escape( catname, strlen(catname));
// Build the SQL statement
// string / character data (whether escaped or not) should be surrounded by single quotes.
//
std::string sqlstatement = "INSERT INTO tbl_category SET name='";
sqlstatement += safe_name;
sqlstatement += "'";
// REMEMBER to delete the escaped string
//
delete [] safe_name;
// Perform the INSERT
//
int newid = database->insertQuery(sqlstatement.c_str());
executeQuery
public bool executeQuery( const char* query );
- Sends queries that do not return a result (UPDATE, DELETE, CREATE, INSERT, ALTER, etc...)
Returns true if successful, false otherwise.
NOTE: Use insertQuery() for INSERT's when you want to know the resulting insert-id.
Example:
if( db_database->executeQuery( "DELETE FROM tbl_color WHERE color='blue'" ) )
{
std::cout << "Deleted the color blue"\n";
}
else
{
std::cout << db_database->getError() << "\n";
}
finish
public static void finish();
- Closes all open database connections
You can safely call this even if no connections were open and no instances were accessed.
We recommend that this method be called at the end of your main() method in any application that
may use the database object.
freeResult
public bool freeResult();
- Frees resources consumed by a query result set
For every call to useResultQuery() or storeResultQuery() in your application,
there should be an accompanying freeResult() call as well.
getError
public const char* getError();
- Returns the last known error
Example
std::cout << database->getError() << "\n";
insertQuery
public int insertQuery( const char* query );
- Sends an INSERT query and returns the insert id
This is only applicable for tables with an AUTO_INCREMENT primary key.
For tables without an AUTO_INCREMENT primary key, use executeQuery() instead.
Returns 0 if an error occurs.
Example:
if( int insertid = db_database->insertQuery( "INSERT INTO tbl_color SET color='blue'" ) )
{
std::cout << "Inserted a color with id of " << y << "\n";
}
else
{
std::cout << db_database->getError() << "\n";
}
instance
public static Database* instance( const char* contextname );
- Returns the singleton database object for a given context
Example:
rude::Database *database = rude::Database::instance("context1");
// use the database object...
nextRow
public bool nextRow();
- Selects the next row from query result set
Returns true if the next row is selected
Returns false if there are no more rows.
Must be called to get the first row.
Example
if(database->storeResultQuery("SELECT category_name tbl_categories"))
{
if(database->nextRow())
{
// We got some data back
std::cout << "Current Categories:\n";
do
{
std::cout << database->column(0) << "\n";
}
while(database->netxRow())
}
else
{
// The result set was empty
std::cout << "There are no categories at this time\n";
}
database->freeResult();
}
else
{
std::cout << database->getError() << "\n";
}
singleValueQuery
public const char* singleValueQuery( const char* query );
- Send a query that expects a single value result
Use this method when you expect a single value to be the result.
Returns c-string (const char *) representation of data if successful
Returns null if a result could not be obtained or an error occurs
Example:
const char *username = db_database->singleValueQuery( "SELECT username form tbl_users where userid=348" );
if(username)
{
std::cout << "Username for givevn ID is " << username << "\n";
}
else
{
std::cout << "Userid 348 does not exist: " << db_database->getError() << "\n";
}
stat
public const char* stat();
- Returns MYSQL server status information
Example
std::cout << database->stat() << "\n";
storeResultQuery
public bool storeResultQuery( const char* query );
- Sends a query that expects a result set - obtains results from server all at once (time friendly)
This is the faster alternative to calling useResultQuery(),
and is the preferred method when small result sets are expected.
Returns false if an error occurs.
If it returns true, use nextRow() and column() to access the results.
If the first call to nextRow() returns false, then the result set is empty.
After you are done with the results, call freeResult() to free the system resources.
Example
if(database->storeResultQuery("SELECT username, password from tbl_users"))
{
while(database->nextRow())
{
std::string username = database->column(0);
std::string password = database->column(1);
std::cout << "Username: << username << " Password: " << password << "\n";
}
database->freeResult();
}
else
{
std::cout << database->getError() << "\n";
}
useResultQuery
public bool useResultQuery( const char* query );
- Sends a query that expects a result set - obtains results from server one row at a time (memory / network friendly)
This uses less memory and network resources than calling useResultQuery(),
and is the preferred method when large result sets are expected
Returns false if an error occurs.
If it returns true, use nextRow() and column() to access the results
If the first call to nextRow() returns false, then the result set is empty.
After you are done with the results, call freeResult() to free the system resources.
Example
if(database->storeResultQuery("SELECT username, password from tbl_users"))
{
while(database->nextRow())
{
std::string username = database->column(0);
std::string password = database->column(1);
std::cout << "Username: << username << " Password: " << password << "\n";
}
database->freeResult();
}
else
{
std::cout << database->getError() << "\n";
}
DETAIL: FIELD | CONSTR | METHOD |
Database
Generated on July 30, 2003 at 22:15 |
|