File size: 17,110 Bytes
07c3cdd
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
<?php
/*
 *  $Id: ResultSet.php,v 1.28 2006/01/17 19:44:38 hlellelid Exp $
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * This software consists of voluntary contributions made by many individuals
 * and is licensed under the LGPL. For more information please see
 * <http://creole.phpdb.org>.
 */

/**
 * This is the interface for classes the wrap db results.
 * 
 * The get*() methods in this interface will format values before returning them. Note
 * that if they will return null if the database returned NULL.  If the requested column does
 * not exist than an exception (SQLException) will be thrown.
 * 
 * <code>
 * $rs = $conn->executeQuery("SELECT MAX(stamp) FROM event", ResultSet::FETCHMODE_NUM);
 * $rs->next();
 * 
 * $max_stamp = $rs->getTimestamp(1, "d/m/Y H:i:s");
 * // $max_stamp will be date string or null if no MAX(stamp) was found
 * 
 * $max_stamp = $rs->getTimestamp("max(stamp)", "d/m/Y H:i:s");
 * // will THROW EXCEPTION, because the resultset was fetched using numeric indexing
 * // SQLException: Invalid resultset column: max(stamp)
 * </code>
 * 
 * This class implements SPL IteratorAggregate, so you may iterate over the database results
 * using foreach():
 * <code>
 * foreach($rs as $row) {
 *   print_r($row); // row is assoc array returned by getRow()
 * }
 * </code>
 * 
 * @author    Hans Lellelid <hans@xmpl.org>
 * @version   $Revision: 1.28 $
 * @package   creole
 */
interface ResultSet extends IteratorAggregate {
        
    /**
     * Index result set by field name.
     */
    const FETCHMODE_ASSOC = 1;

    /**
     * Index result set numerically.
     */
    const FETCHMODE_NUM = 2;
    
    /**
     * Get the PHP native resource for the result.
     * Arguably this should not be part of the interface: i.e. every driver should implement
     * it if they have a result resource, but conceivably drivers could be created that do
     * not.  For now every single driver does have a "dblink" resource property, and other
     * classes (e.g. ResultSet) need this info in order to get correct native errors.  We'll
     * leave it in for now, as it helps with driver development, with the caveat that it 
     * could be removed from the interface at a later point.
     * @return resource Query result or NULL if not not applicable.
     */
    public function getResource();
        
    /**
     * Sets the fetchmode used to retrieve results.
     * Changing fetchmodes mid-result retrieval is supported (haven't encountered any drivers 
     * that don't support that yet).
     * @param int $mode ResultSet::FETCHMODE_NUM or  ResultSet::FETCHMODE_ASSOC (default).
     * @return void
     */
    public function setFetchmode($mode);
    
    /**
     * Gets the fetchmode used to retrieve results.
     * @return int ResultSet::FETCHMODE_NUM or ResultSet::FETCHMODE_ASSOC (default).
     */
    public function getFetchmode();       
    
    /**
     * Whether assoc result keys get converted to lowercase for compatibility.
     * 
     * This defaults to FALSE unless Creole::COMPAT_ASSOC_LOWER flag has been passed to connection.
     * This property is read-only since it must be set when connection is created.  The
     * reason for this behavior is some drivers (e.g. SQLite) do the case conversions internally
     * based on a PHP ini value; it would not be possible to change the behavior from the ResultSet
     * (since query has already been executed).
	 * 
     * @return boolean
     */
    public function isLowerAssocCase();
        
    /**
     * Moves the internal cursor to the next position and fetches the row at that position.
     * 
     * @return boolean <tt>true</tt> if success, <tt>false</tt> if no next record.
     * @throws SQLException on any driver-level errors.
     */
    public function next();

    /**
     * Moves the internal cursor to the previous position and fetches the
     * row at that position.
     * 
     * @return boolean <tt>true</tt> if success, <tt>false</tt> if no previous record.
     * @throws SQLException - if unable to move to previous position
     *                      - if ResultSet doesn't support reverse scrolling
     */
    public function previous();

    /**
     * Moves the cursor a relative number of rows, either positive or negative and fetches
     * the row at that position.
     * 
     * Attempting to move beyond the first/last row in the result set positions the cursor before/after 
     * the first/last row and issues a Warning. Calling relative(0) is valid, but does not change the cursor 
     * position. 
     * 
     * @param integer $offset
     * @return boolean <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
     * @throws SQLException - if unable to move to relative position
     *                      - if rel pos is negative & ResultSet doesn't support reverse scrolling
     */
    public function relative($offset);


    /**
     * Moves the cursor to an absolute cursor position and fetches the row at that position.
     * 
     * Attempting to move beyond the first/last row in the result set positions the cursor before/after 
     * the first/last row and issues a Warning.
     * 
     * @param integer $pos cursor position, first position is 1.
     * @return boolean <tt>true</tt> if cursor is on a row, <tt>false</tt> otherwise.
     * @throws SQLException - if unable to move to absolute position
     *                      - if position is before current pos & ResultSet doesn't support reverse scrolling
     */
    public function absolute($pos);

    /**
     * Moves cursor position WITHOUT FETCHING ROW AT THAT POSITION.
     * 
     * Generally this method is for internal driver stuff (e.g. other methods like
     * absolute() or relative() might call this and then call next() to get the row).
     * This method is public to facilitate more advanced ResultSet scrolling tools
     * -- e.g. cleaner implimentation of ResultSetIterator.
     * 
     * Some drivers will emulate seek() and not allow reverse seek (Oracle).
     * 
     * Seek is 0-based, but seek() is only for moving to the space _before_ the record
     * that you want to read.  I.e. if you seek(0) and then call next() you will have the 
     * first row (i.e. same as calling first() or absolute(1)).
     * 
     * <strong>IMPORTANT:  You cannot rely on the return value of this method to know whether a given
     * record exists for reading.  In some cases seek() will correctly return <code>false</code> if
     * the position doesn't exist, but in other drivers the seek is not performed until the
     * record is fetched. You can check the return value of absolute() if you need to know
     * whether a specific rec position is valid.</strong>
     * 
     * @param int $rownum The cursor pos to seek to.
     * @return boolean true on success, false if unable to seek to specified record.
     * @throws SQLException if trying to seek backwards with a driver that doesn't
     *                      support reverse-scrolling
     */
    public function seek($rownum);    
    
    /**
     * Move cursor to beginning of recordset.
     * @return boolean <tt>true</tt> on success or <tt>false</tt> if not found.
     * @throws SQLException - if unable to move to first position
     *                      - if not at first pos & ResultSet doesn't support reverse scrolling
     */
    public function first();

    /**
     * Move cursor to end of recordset.
     * @return boolean <tt>true</tt> on success or <tt>false</tt> if not found.
     * @throws SQLException - if unable to move to last position
     *                      - if unable to get num rows
     */
    public function last();
    
    /**
     * Sets cursort to before first record. This does not actually seek(), but
     * simply sets cursor pos to 0.
     * This is useful for inserting a record before the first in the set, etc.
     * @return void
     */
    public function beforeFirst();


    /**
     * Sets cursort to after the last record. This does not actually seek(), but
     * simply sets the cursor pos  to last + 1.
     * This [will be] useful for inserting a record after the last in the set,
     * when/if Creole supports updateable ResultSets.
     * @return void
     */
    public function afterLast();


    /**
     * Checks whether cursor is after the last record.
     * @return boolean
     * @throws SQLException on any driver-level error.
     */
    public function isAfterLast();

    /**
     * Checks whether cursor is before the first record.
     * @return boolean
     * @throws SQLException on any driver-level error.
     */
    public function isBeforeFirst();

    /**
     * Returns the current cursor position.
     * Cursor positions start at 0, but as soon as first row is fetched
     * cursor position is 1. (so first row is 1)
     * @return int
     */
    public function getCursorPos();

    /**
     * Gets current fields (assoc array).
     * @return array
     */
    public function getRow();

    /**
     * Get the number of rows in a result set.
     * @return int the number of rows
     * @throws SQLException - if unable to get a rowcount.
     */
    public function getRecordCount();
            
    /**
     * Frees the resources allocated for this result set.
     * Also empties any internal field array so that any calls to
     * get() method on closed ResultSet will result in "Invalid column" SQLException.
     * @return void
     */
    public function close();
    
    /**
     * A generic get method returns unformatted (=string) value.
     * This returns the raw results from the database.  Usually this will be a string, but some drivers
     * also can return objects (lob descriptors, etc) in certain cases.
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used) (if ResultSet::FETCHMODE_NUM was used).
     * @return mixed Usually expect a string.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function get($column);
    
    /**
     * Reads a column as an array.
     * The value of the column is unserialized & returned as an array.  The generic case of this function is 
     * very PHP-specific.  Other drivers (e.g. Postgres) will format values into their native array format.
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return array value or null if database returned null.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getArray($column);

    /**
     * Returns value translated to boolean.
     * Default is to map 0 => false, 1 => true, but some database drivers may override this behavior.
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return boolean value or null if database returned null.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getBoolean($column);
            
    /**
     * Returns Blob with contents of column value.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return Blob New Blob with data from column or null if database returned null.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getBlob($column);

    /**
     * Returns Clob with contents of column value.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return Clob New Clob object with data from column or null if database returned null.
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getClob($column);

    /**
     * Return a formatted date.
     * 
     * The default format for dates returned is preferred (in your locale, as specified using setlocale()) 
     * format w/o time (i.e. strftime("%x", $val)).  Override this by specifying a format second parameter.  You
     * can also specify a date()-style formatter; if you do, make sure there are no "%" symbols in your format string.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
     *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
     * @return mixed  Formatted date, or integer unix timestamp (using 00:00:00 for time) if $format was null. 
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getDate($column, $format = '%x');   

    /**
     * Returns value cast as a float (in PHP this is same as double).
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return float value or null if database returned null
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getFloat($column);

    /**
     * Returns value cast as integer.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return int value or null if database returned null
     * @see getInteger()
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getInt($column);      

    /**
     * Returns value cast as string.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @return string value or null if database returned null
     * @see get()
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getString($column);
    
    /**
     * Return a formatted time.
     * 
     * The default format for times returned is preferred (in your locale, as specified using setlocale()) 
     * format w/o date (i.e. strftime("%X", $val)).  Override this by specifying a format second parameter.  You
     * can also specify a date()-style formatter; if you do, make sure there are no "%" symbols in your format string.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
     *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
     * @return mixed  Formatted time, or integer unix timestamp (using today's date) if $format was null. 
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getTime($column, $format = '%X');

    /**
     * Return a formatted timestamp.
     * 
     * The default format for timestamp is ISO standard YYYY-MM-DD HH:MM:SS (i.e. date('Y-m-d H:i:s', $val).
     * Override this by specifying a format second parameter.  You can also specify a strftime()-style formatter.
     * 
     * Hint: if you want to get the unix timestamp use the "U" formatter string.
     * 
     * @param mixed $column Column name (string) or index (int) starting with 1 (if ResultSet::FETCHMODE_NUM was used).
     * @param string $format Date formatter for use w/ strftime() or date() (it will choose based on examination of format string)
     *                          If format is NULL, then the integer unix timestamp will be returned (no formatting performed).
     * @return mixed Formatted timestamp, or integer unix timestamp (if $format was null)
     * @throws SQLException - If the column specified is not a valid key in current field array.
     */
    public function getTimestamp($column, $format = 'Y-m-d H:i:s');
    
}