You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
229 lines
8.0 KiB
C++
229 lines
8.0 KiB
C++
/*=========================================================================
|
|
|
|
Program: Visualization Toolkit
|
|
Module: vtkSQLQuery.h
|
|
|
|
Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
|
|
All rights reserved.
|
|
See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
|
|
|
|
This software is distributed WITHOUT ANY WARRANTY; without even
|
|
the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
PURPOSE. See the above copyright notice for more information.
|
|
|
|
=========================================================================*/
|
|
/*-------------------------------------------------------------------------
|
|
Copyright 2008 Sandia Corporation.
|
|
Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
|
|
the U.S. Government retains certain rights in this software.
|
|
-------------------------------------------------------------------------*/
|
|
/**
|
|
* @class vtkSQLQuery
|
|
* @brief executes an sql query and retrieves results
|
|
*
|
|
*
|
|
* The abstract superclass of SQL query classes. Instances of subclasses
|
|
* of vtkSQLQuery are created using the GetQueryInstance() function in
|
|
* vtkSQLDatabase. To implement a query connection for a new database
|
|
* type, subclass both vtkSQLDatabase and vtkSQLQuery, and implement the
|
|
* required functions. For the query class, this involves the following:
|
|
*
|
|
* Execute() - Execute the query on the database. No results need to be
|
|
* retrieved at this point, unless you are performing caching.
|
|
*
|
|
* GetNumberOfFields() - After Execute() is performed, returns the number
|
|
* of fields in the query results.
|
|
*
|
|
* GetFieldName() - The name of the field at an index.
|
|
*
|
|
* GetFieldType() - The data type of the field at an index.
|
|
*
|
|
* NextRow() - Advances the query results by one row, and returns whether
|
|
* there are more rows left in the query.
|
|
*
|
|
* DataValue() - Extract a single data value from the current row.
|
|
*
|
|
* Begin/Rollback/CommitTransaction() - These methods are optional but
|
|
* recommended if the database supports transactions.
|
|
*
|
|
* @par Thanks:
|
|
* Thanks to Andrew Wilson from Sandia National Laboratories for his work
|
|
* on the database classes.
|
|
*
|
|
* @sa
|
|
* vtkSQLDatabase
|
|
*/
|
|
|
|
#ifndef vtkSQLQuery_h
|
|
#define vtkSQLQuery_h
|
|
|
|
#include "vtkIOSQLModule.h" // For export macro
|
|
#include "vtkRowQuery.h"
|
|
#include "vtkStdString.h" // for EscapeString()
|
|
|
|
class vtkSQLDatabase;
|
|
class vtkVariant;
|
|
class vtkVariantArray;
|
|
|
|
class VTKIOSQL_EXPORT vtkSQLQuery : public vtkRowQuery
|
|
{
|
|
public:
|
|
vtkTypeMacro(vtkSQLQuery, vtkRowQuery);
|
|
void PrintSelf(ostream& os, vtkIndent indent) override;
|
|
|
|
//@{
|
|
/**
|
|
* The query string to be executed. Since some databases will
|
|
* process the query string as soon as it's set, this method returns
|
|
* a boolean to indicate success or failure.
|
|
*/
|
|
virtual bool SetQuery(const char* query);
|
|
virtual const char* GetQuery();
|
|
//@}
|
|
|
|
/**
|
|
* Return true if the query is active (i.e. execution was successful
|
|
* and results are ready to be fetched). Returns false on error or
|
|
* inactive query.
|
|
*/
|
|
bool IsActive() override { return this->Active; }
|
|
|
|
/**
|
|
* Execute the query. This must be performed
|
|
* before any field name or data access functions
|
|
* are used.
|
|
*/
|
|
bool Execute() override = 0;
|
|
|
|
/**
|
|
* Begin, commit, or roll back a transaction. If the underlying
|
|
* database does not support transactions these calls will do
|
|
* nothing.
|
|
*/
|
|
virtual bool BeginTransaction() { return true; }
|
|
virtual bool CommitTransaction() { return true; }
|
|
virtual bool RollbackTransaction() { return true; }
|
|
|
|
//@{
|
|
/**
|
|
* Return the database associated with the query.
|
|
*/
|
|
vtkGetObjectMacro(Database, vtkSQLDatabase);
|
|
//@}
|
|
|
|
/**
|
|
* Bind a parameter to a placeholder in a query. A full discussion
|
|
* of this feature is beyond the scope of this header file, but in
|
|
* short, here's how it works:
|
|
|
|
* Instead of saying "SELECT foo FROM mytable WHERE myfield = 12345"
|
|
* you can say "SELECT foo FROM mytable WHERE myfield = ?". The ?
|
|
* character is a placeholder for a parameter that must then be
|
|
* bound. Call BindParameter(0, 12345) to bind the integer value
|
|
* 12345 to that field. Placeholders are indexed starting at 0.
|
|
|
|
* You are responsible for making sure that the types match when you
|
|
* call BindParameter. You don't have to get it precisely correct:
|
|
* in general, the SQL driver is smart enough to do things like cast
|
|
* a short to a long or a float to a double.
|
|
|
|
* Bound parameters were introduced in ANSI SQL 92. Please see that
|
|
* standard for more information.
|
|
|
|
* Most of these methods are excluded from wrapping because the Java
|
|
* wrapper treats all integer types from char up through 64-bit long
|
|
* as 'int'. This is incorrect behavior but what else am I going to
|
|
* do?
|
|
|
|
* Finally, the default implementation for BindParameter(int,
|
|
* vtkVariant) dispatches to one of the more type-specific versions. It
|
|
* should be OK to use in database drivers without modification.
|
|
*/
|
|
|
|
virtual bool BindParameter(int index, unsigned char value);
|
|
virtual bool BindParameter(int index, unsigned short value);
|
|
virtual bool BindParameter(int index, unsigned int value);
|
|
virtual bool BindParameter(int index, unsigned long value);
|
|
// The C and C++ standards leave it up to each compiler to decide
|
|
// whether chars are signed or unsigned by default. All the other
|
|
// types are signed unless otherwise specified.
|
|
virtual bool BindParameter(int index, signed char value);
|
|
virtual bool BindParameter(int index, short value);
|
|
|
|
virtual bool BindParameter(int index, int value);
|
|
|
|
virtual bool BindParameter(int index, long value);
|
|
virtual bool BindParameter(int index, unsigned long long value);
|
|
virtual bool BindParameter(int index, long long value);
|
|
|
|
virtual bool BindParameter(int index, float value);
|
|
virtual bool BindParameter(int index, double value);
|
|
/**
|
|
* Bind a string value -- string must be null-terminated
|
|
*/
|
|
virtual bool BindParameter(int index, const char* stringValue);
|
|
/**
|
|
* Bind a string value by specifying an array and a size
|
|
*/
|
|
virtual bool BindParameter(int index, const char* stringValue, size_t length);
|
|
|
|
virtual bool BindParameter(int index, const vtkStdString& string);
|
|
|
|
virtual bool BindParameter(int index, vtkVariant var);
|
|
/**
|
|
* Bind a blob value. Not all databases support blobs as a data
|
|
* type. Check vtkSQLDatabase::IsSupported(VTK_SQL_FEATURE_BLOB) to
|
|
* make sure.
|
|
*/
|
|
virtual bool BindParameter(int index, const void* data, size_t length);
|
|
/**
|
|
* Reset all parameter bindings to nullptr.
|
|
*/
|
|
virtual bool ClearParameterBindings();
|
|
|
|
/**
|
|
* Escape a string for inclusion into an SQL query.
|
|
* If \a addSurroundingQuotes is true, then quotation marks appropriate to the
|
|
* backend database will be added to enclose the escaped string. This argument
|
|
* defaults to true.
|
|
|
|
* A default, simple-minded implementation is provided for
|
|
* database backends that do not provde a way to escape
|
|
* strings for use inside queries.
|
|
*/
|
|
virtual vtkStdString EscapeString(vtkStdString s, bool addSurroundingQuotes = true);
|
|
|
|
/**
|
|
* Escape a string for inclusion into an SQL query.
|
|
* This method exists to provide a wrappable version of
|
|
* the method that takes and returns vtkStdString objects.
|
|
* You are responsible for calling delete [] on the
|
|
* character array returned by this method.
|
|
* This method simply calls the vtkStdString variant and thus
|
|
* need not be re-implemented by subclasses.
|
|
*/
|
|
char* EscapeString(const char* src, bool addSurroundingQuotes);
|
|
|
|
protected:
|
|
vtkSQLQuery();
|
|
~vtkSQLQuery() override;
|
|
|
|
/**
|
|
* Set the database associated with the query.
|
|
* This is only to be called by the corresponding
|
|
* database class on creation of the query in
|
|
* GetQueryInstance().
|
|
*/
|
|
void SetDatabase(vtkSQLDatabase* db);
|
|
|
|
char* Query;
|
|
vtkSQLDatabase* Database;
|
|
bool Active;
|
|
|
|
private:
|
|
vtkSQLQuery(const vtkSQLQuery&) = delete;
|
|
void operator=(const vtkSQLQuery&) = delete;
|
|
};
|
|
|
|
#endif // vtkSQLQuery_h
|