[Sommaire] [Imprimer]

   1  <?php
   2  /*
   3   *  $Id: Connection.php,v 1.29 2005/10/17 19:03:50 dlawson_mi Exp $
   4   *
   5   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   6   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   7   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   8   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   9   * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  10   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  11   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  12   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  13   * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  14   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  15   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  16   *
  17   * This software consists of voluntary contributions made by many individuals
  18   * and is licensed under the LGPL. For more information please see
  19   * <http://creole.phpdb.org>.
  20   */
  21  
  22  include_once 'creole/ResultSet.php'; // we need this for the fetchmode ResultSet flags (constants) that are passed to executeQuery()
  23  
  24  /**
  25   * Connection is an abstract base class for DB dialect implementations, and must be
  26   * inherited by all such.
  27   * 
  28   * Developer notes:
  29   *  (1) Make sure that your Connection class can be serialized.  See the ConnectionCommon __sleep() and __wakeup() implimentation.
  30   * 
  31   * @author    Hans Lellelid <hans@xmpl.org>
  32   * @version   $Revision: 1.29 $
  33   * @package   creole
  34   */
  35  interface Connection {
  36  
  37      // Constants that define transaction isolation levels.
  38      // [We don't have any code using these yet, so there's no need
  39      // to initialize these values at this point.]
  40      // const TRANSACTION_NONE = 0;
  41      // const TRANSACTION_READ_UNCOMMITTED = 1;
  42      // const TRANSACTION_READ_COMMITTED = 2;
  43      // const TRANSACTION_REPEATABLE_READ = 3;
  44      // const TRANSACTION_SERIALIZABLE = 4;
  45      
  46      /**
  47       * Connect to a database and log in as the specified user.
  48       *
  49       * @param array $dsn The PEAR-style data source hash.
  50       * @param int $flags (optional) Flags for connection (e.g. Creole::PERSISTENT).  These flags
  51       *                   may apply to any of the driver classes.
  52       */
  53      public function connect($dsn, $flags = false);    
  54      
  55      /**
  56       * Get the PHP native resource for the database connection/link.
  57       * @return resource
  58       */
  59      public function getResource();
  60          
  61      /**
  62       * Get any flags that were passed to connection.
  63       * @return int
  64       */
  65      public function getFlags();        
  66      
  67      /**
  68       * Get the DSN array used by connect() method to connect to database.
  69       * @see connect()
  70       * @return array
  71       */
  72      public function getDSN();      
  73      
  74      /**
  75       * Gets a DatabaseInfo class for the current database.
  76       *
  77       * This is not modeled on the JDBC MetaData class, but provides a possibly more 
  78       * useful metadata system.  All the same, there may eventually be a getMetaData()
  79       * which returns a class that behaves like JDBC's DatabaseMetaData.
  80       *
  81       * @return DatabaseInfo
  82       */
  83      public function getDatabaseInfo();
  84      
  85      /**
  86       * Loads and returns an IdGenerator object for current RDBMS.
  87       * @return IdGenerator
  88       */
  89      public function getIdGenerator();
  90      
  91      /**
  92       * Prepares a query for multiple execution with execute().
  93       *
  94       * With some database backends, this is emulated.
  95       * prepare() requires a generic query as string like
  96       * "INSERT INTO numbers VALUES(?,?,?)". The ? are placeholders.
  97          * 
  98       * IMPORTANT:  All occurrences of the placeholder (?) will be assumed
  99       * to be a parameter.  Therefore be sure not to have ? anywhere else in
 100       * the query.
 101       * 
 102       * So, ... DO NOT MIX WILDCARDS WITH ALREADY-PREPARED QUERIES
 103       *
 104       * INCORRECT:
 105       *     SELECT * FROM mytable WHERE id = ? AND title = 'Where are you?' and body LIKE ?
 106       * 
 107       * CORRECT:
 108       *    SELECT * FROM mytable WHERE id = ? AND title = ? and body LIKE ?
 109       * 
 110       * @param string $sql The query to prepare.
 111       * @return PreparedStatement
 112       * @throws SQLException
 113       * @see PreparedStatement::execute()
 114       */
 115      public function prepareStatement($sql);
 116      
 117      /**
 118       * Creates a new empty Statement.
 119       * @return Statement
 120       */
 121      public function createStatement();
 122      
 123      /**
 124       * If RDBMS supports native LIMIT/OFFSET then query SQL is modified
 125       * so that no emulation is performed in ResultSet.
 126       * 
 127       * @param string &$sql The query that will be modified.
 128       * @param int $offset
 129       * @param int $limit
 130       * @return void
 131       * @throws SQLException - if unable to modify query for any reason.
 132       */
 133      public function applyLimit(&$sql, $offset, $limit);
 134      
 135      /**
 136       * Executes the SQL query in this PreparedStatement object and returns the resultset.
 137       * 
 138       * @param string $sql The SQL statement.
 139       * @param int $fetchmode
 140       * @return object ResultSet
 141       * @throws SQLException if a database access error occurs.
 142       */
 143      public function executeQuery($sql, $fetchmode = null);
 144  
 145      /**
 146       * Executes the SQL INSERT, UPDATE, or DELETE statement.
 147       * 
 148       * @param string $sql This method may optionally be called with the SQL statement.
 149       * @return int Number of affected rows (or 0 for drivers that return nothing).
 150       * @throws SQLException if a database access error occurs.
 151       */
 152      public function executeUpdate($sql);
 153      
 154      /**
 155       * Creates a CallableStatement object for calling database stored procedures.
 156       * 
 157       * @param string $sql
 158       * @return CallableStatement
 159       */
 160      public function prepareCall($sql);
 161      
 162      /**
 163       * Free the db resources.
 164       * @return void
 165       */
 166      public function close();
 167      
 168      /**
 169       * Returns false if connection is closed.
 170       * @return boolean
 171       */
 172      public function isConnected();
 173      
 174      /**
 175       * Get auto-commit status.
 176       *
 177       * @return boolean
 178       */
 179      public function getAutoCommit();
 180      
 181      /**
 182       * Enable/disable automatic commits.
 183       * 
 184       * Pushes SQLWarning onto $warnings stack if the autocommit value is being changed mid-transaction. This function
 185       * is overridden by driver classes so that they can perform the necessary begin/end transaction SQL.
 186       * 
 187       * If auto-commit is being set to TRUE, then the current transaction will be committed immediately.
 188       * 
 189       * @param boolean $bit New value for auto commit.
 190       * @return void
 191       */
 192      public function setAutoCommit($bit);
 193      
 194      /**
 195       * Begins a transaction (if supported).
 196       *
 197       */
 198      public function begin();
 199      
 200      /**
 201       * Commits statements in a transaction.
 202       *
 203       */
 204      public function commit();
 205      
 206      /**
 207       * Rollback changes in a transaction.
 208       *
 209       */
 210      public function rollback();
 211      
 212      /**
 213       * Gets the number of rows affected by the data manipulation
 214       * query.
 215       *
 216       * @return int Number of rows affected by the last query.
 217       */
 218      public function getUpdateCount();
 219  
 220  }