[Sommaire] [Imprimer]

   1  <?php
   2  /*
   3   *  $Id: Statement.php,v 1.17 2004/03/20 04:16:49 hlellelid 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  /**
  23   * Class that represents a SQL statement.
  24   * 
  25   * This class is very generic and has no driver-specific implementations.  In fact,
  26   * it wouldn't be possible to have driver-specific classes, since PHP doesn't support
  27   * multiple inheritance.  I.e. you couldn't have MySQLPreparedStatement that extended
  28   * both the abstract PreparedStatement class and the MySQLStatement class.  In Java
  29   * this isn't a concern since PreparedStatement is an interface, not a class.
  30   *
  31   * 
  32   * @author   Hans Lellelid <hans@xmpl.org>
  33   * @version  $Revision: 1.17 $
  34   * @package  creole
  35   */
  36  interface Statement {    
  37      
  38      /**
  39       * Sets the maximum number of rows to return from db.
  40       * This will affect the SQL if the RDBMS supports native LIMIT; if not,
  41       * it will be emulated.  Limit only applies to queries (not update sql).
  42       * @param int $v Maximum number of rows or 0 for all rows.
  43       * @return void
  44       */
  45      public function setLimit($v);
  46      
  47      /**
  48       * Returns the maximum number of rows to return or 0 for all.
  49       * @return int
  50       */
  51      public function getLimit();
  52      
  53      /**
  54       * Sets the start row.
  55       * This will affect the SQL if the RDBMS supports native OFFSET; if not,
  56       * it will be emulated. Offset only applies to queries (not update) and 
  57       * only is evaluated when LIMIT is set!
  58       * @param int $v
  59       * @return void
  60       */ 
  61      public function setOffset($v);
  62      
  63      /**
  64       * Returns the start row.
  65       * Offset only applies when Limit is set!
  66       * @return int
  67       */
  68      public function getOffset();
  69      
  70      /**
  71       * Free resources associated with this statement.
  72       * Some drivers will need to implement this method to free
  73       * database result resources. 
  74       * 
  75       * @return void
  76       */
  77      public function close();
  78      
  79      /**
  80       * Generic execute() function has to check to see whether SQL is an update or select query.
  81       * 
  82       * If you already know whether it's a SELECT or an update (manipulating) SQL, then use
  83       * the appropriate method, as this one will incurr overhead to check the SQL.
  84       * 
  85       * @param int $fetchmode Fetchmode (only applies to queries).
  86       * @return boolean True if it is a result set, false if not or if no more results (this is identical to JDBC return val).
  87       * @throws SQLException
  88       */
  89      public function execute($sql, $fetchmode = null);
  90  
  91      /**
  92       * Get result set.
  93       * This assumes that the last thing done was an executeQuery() or an execute()
  94       * with SELECT-type query.
  95       *
  96       * @return RestultSet (or null if none)
  97       */
  98      public function getResultSet();
  99  
 100      /**
 101       * Get update count.
 102       *
 103       * @return int Number of records affected, or <code>null</code> if not applicable.
 104       */
 105      public function getUpdateCount();        
 106  
 107      /**
 108       * Executes the SQL query in this PreparedStatement object and returns the resultset generated by the query.
 109       * 
 110       * @param string $sql This method may optionally be called with the SQL statement.
 111       * @param int $fetchmode The mode to use when fetching the results (e.g. ResultSet::FETCHMODE_NUM, ResultSet::FETCHMODE_ASSOC).
 112       * @return object Creole::ResultSet
 113       * @throws SQLException if a database access error occurs.
 114       */
 115      public function executeQuery($sql, $fetchmode = null);
 116      
 117      /**
 118       * Executes the SQL INSERT, UPDATE, or DELETE statement in this PreparedStatement object.
 119       * 
 120       * @param string $sql This method may optionally be called with the SQL statement.
 121       * @return int Number of affected rows (or 0 for drivers that return nothing).
 122       * @throws SQLException if a database access error occurs.
 123       */
 124      public function executeUpdate($sql);
 125      
 126      /**
 127       * Gets next result set (if this behavior is supported by driver).
 128       * Some drivers (e.g. MSSQL) support returning multiple result sets -- e.g.
 129       * from stored procedures.
 130       *
 131       * This function also closes any current restult set.
 132       *
 133       * Default behavior is for this function to return false.  Driver-specific
 134       * implementations of this class can override this method if they actually
 135       * support multiple result sets.
 136       * 
 137       * @return boolean True if there is another result set, otherwise false.
 138       */
 139      public function getMoreResults();
 140       
 141      /**
 142       * Gets the db Connection that created this statement.
 143       * @return Connection
 144       */
 145      public function getConnection();
 146      
 147  }