// SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
// SPDX-FileCopyrightText: Copyright 2008 Sandia Corporation
// SPDX-License-Identifier: LicenseRef-BSD-3-Clause-Sandia-USGov
/**
 * @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()

VTK_ABI_NAMESPACE_BEGIN
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;
};

VTK_ABI_NAMESPACE_END
#endif // vtkSQLQuery_h