1: <?php
2:
3: /**
4: * An interface that defines all of the Data Access Object (DAO) methods that should be
5: * included in a provider that implements this interface.
6: *
7: * @package alpha::model
8: * @since 1.1
9: * @author John Collins <dev@alphaframework.org>
10: * @version $Id: AlphaDAOProviderInterface.inc 1808 2014-07-27 14:11:52Z alphadevx $
11: * @license http://www.opensource.org/licenses/bsd-license.php The BSD License
12: * @copyright Copyright (c) 2014, John Collins (founder of Alpha Framework).
13: * All rights reserved.
14: *
15: * <pre>
16: * Redistribution and use in source and binary forms, with or
17: * without modification, are permitted provided that the
18: * following conditions are met:
19: *
20: * * Redistributions of source code must retain the above
21: * copyright notice, this list of conditions and the
22: * following disclaimer.
23: * * Redistributions in binary form must reproduce the above
24: * copyright notice, this list of conditions and the
25: * following disclaimer in the documentation and/or other
26: * materials provided with the distribution.
27: * * Neither the name of the Alpha Framework nor the names
28: * of its contributors may be used to endorse or promote
29: * products derived from this software without specific
30: * prior written permission.
31: *
32: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
33: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
34: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
35: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
36: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
37: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
38: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
39: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
40: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
41: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
42: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
43: * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
44: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
45: * </pre>
46: *
47: */
48: interface AlphaDAOProviderInterface {
49: /**
50: * Gets the current connection singleton, or creates a new one if none exists
51: *
52: * @return mysqli
53: * @since 1.1
54: */
55: public static function getConnection();
56:
57: /**
58: * Disconnects the current database connection if one exists (self::$connection is set)
59: *
60: * @since 1.1
61: */
62: public static function disconnect();
63:
64: /**
65: * Returns the last database error string for the current connection.
66: *
67: * @since 1.1
68: * @return string
69: */
70: public static function getLastDatabaseError();
71:
72: /**
73: * Populates the child object with the properties retrived from the database for the object $OID.
74: *
75: * @param integer $OID The object ID of the business object to load.
76: * @since 1.1
77: * @throws BONotFoundException
78: */
79: public function load($OID);
80:
81: /**
82: * Populates the child object from the database table by the given attribute value.
83: *
84: * @param string $atribute The name of the attribute to load the object by.
85: * @param string $value The value of the attribute to load the object by.
86: * @param boolean $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
87: * @param array $loadAttributes The attributes to load from the database to this object (leave blank to load all attributes)
88: * @since 1.1
89: * @throws BONotFoundException
90: */
91: public function loadByAttribute($attribute, $value, $ignoreClassType=false, $loadAttributes=array());
92:
93: /**
94: * Loads all of the objects of this class into an array which is returned.
95: *
96: * @param integer $start The start of the SQL LIMIT clause, useful for pagination.
97: * @param integer $limit The amount (limit) of objects to load, useful for pagination.
98: * @param string $orderBy The name of the field to sort the objects by.
99: * @param string $order The order to sort the objects by.
100: * @param boolean $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
101: * @return array An array containing objects of this type of business object.
102: * @since 1.1
103: * @throws BONotFoundException
104: */
105: public function loadAll($start=0, $limit=0, $orderBy='OID', $order='ASC', $ignoreClassType=false);
106:
107: /**
108: * Loads all of the objects of this class by the specified attribute into an array which is returned.
109: *
110: * @param string $atribute The attribute to load the objects by.
111: * @param string $value The value of the attribute to load the objects by.
112: * @param integer $start The start of the SQL LIMIT clause, useful for pagination.
113: * @param integer $limit The amount (limit) of objects to load, useful for pagination.
114: * @param string $orderBy The name of the field to sort the objects by.
115: * @param string $order The order to sort the objects by.
116: * @param boolean $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type.
117: * @param array $constructorArgs An optional array of contructor arguements to pass to the BOs that will be generated and returned. Supports a maximum of 5 arguements.
118: * @return array An array containing objects of this type of business object.
119: * @since 1.1
120: * @throws BONotFoundException
121: * @throws IllegalArguementException
122: */
123: public function loadAllByAttribute($attribute, $value, $start=0, $limit=0, $orderBy="OID", $order="ASC", $ignoreClassType=false, $constructorArgs=array());
124:
125: /**
126: * Loads all of the objects of this class by the specified attributes into an array which is returned.
127: *
128: * @param array $atributes The attributes to load the objects by.
129: * @param array $values The values of the attributes to load the objects by.
130: * @param integer $start The start of the SQL LIMIT clause, useful for pagination.
131: * @param integer $limit The amount (limit) of objects to load, useful for pagination.
132: * @param string $orderBy The name of the field to sort the objects by.
133: * @param string $order The order to sort the objects by.
134: * @param boolean $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
135: * @param array $constructorArgs An optional array of contructor arguements to pass to the BOs that will be generated and returned. Supports a maximum of 5 arguements.
136: * @return array An array containing objects of this type of business object.
137: * @since 1.1
138: * @throws BONotFoundException
139: * @throws IllegalArguementException
140: */
141: public function loadAllByAttributes($attributes=array(), $values=array(), $start=0, $limit=0, $orderBy='OID', $order='ASC', $ignoreClassType=false, $constructorArgs=array());
142:
143: /**
144: * Loads all of the objects of this class that where updated (updated_ts value) on the date indicated.
145: *
146: * @param string $date The date for which to load the objects updated on, in the format 'YYYY-MM-DD'.
147: * @param integer $start The start of the SQL LIMIT clause, useful for pagination.
148: * @param integer $limit The amount (limit) of objects to load, useful for pagination.
149: * @param string $orderBy The name of the field to sort the objects by.
150: * @param string $order The order to sort the objects by.
151: * @param boolean $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
152: * @return array An array containing objects of this type of business object.
153: * @since 1.1
154: * @throws BONotFoundException
155: */
156: public function loadAllByDayUpdated($date, $start=0, $limit=0, $orderBy="OID", $order="ASC", $ignoreClassType=false);
157:
158: /**
159: * Loads all of the specified attribute values of this class by the specified attribute into an
160: * array which is returned.
161: *
162: * @param string $attribute The attribute name to load the field values by.
163: * @param string $value The value of the attribute to load the field values by.
164: * @param string $returnAttribute The name of the attribute to return.
165: * @param string $order The order to sort the BOs by.
166: * @param boolean $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type.
167: * @return array An array of field values.
168: * @since 1.1
169: * @throws BONotFoundException
170: */
171: public function loadAllFieldValuesByAttribute($attribute, $value, $returnAttribute, $order='ASC', $ignoreClassType=false);
172:
173: /**
174: * Saves the object. If $this->OID is empty or null it will INSERT, otherwise UPDATE.
175: *
176: * @since 1.1
177: * @throws FailedSaveException
178: * @throws LockingException
179: * @throws ValidationException
180: */
181: public function save();
182:
183: /**
184: * Saves the field specified with the value supplied. Only works for persistent BOs. Note that no Alpha type
185: * validation is performed with this method!
186: *
187: * @param string $attribute The name of the attribute to save.
188: * @param mixed $value The value of the attribute to save.
189: * @since 1.1
190: * @throws IllegalArguementException
191: * @throws FailedSaveException
192: */
193: public function saveAttribute($attribute, $value);
194:
195: /**
196: * Saves the object history to the [tablename]_history table. It always does an INSERT.
197: *
198: * @since 1.2
199: * @throws FailedSaveException
200: */
201: public function saveHistory();
202:
203: /**
204: * Deletes the current object from the database.
205: *
206: * @since 1.1
207: * @throws FailedDeleteException
208: */
209: public function delete();
210:
211: /**
212: * Gets the version_num of the object from the database (returns 0 if the BO is not saved yet).
213: *
214: * @return integer
215: * @since 1.1
216: * @throws BONotFoundException
217: */
218: public function getVersion();
219:
220: /**
221: * Builds a new database table for the BO class.
222: *
223: * @since 1.1
224: * @throws AlphaException
225: */
226: public function makeTable();
227:
228: /**
229: * Builds a new database table for the BO class to store it's history
230: *
231: * @since 1.2
232: * @throws AlphaException
233: */
234: public function makeHistoryTable();
235:
236: /**
237: * Re-builds the table if the model requirements have changed. All data is lost!
238: *
239: * @since 1.1
240: * @throws AlphaException
241: */
242: public function rebuildTable();
243:
244: /**
245: * Drops the table if the model requirements have changed. All data is lost!
246: *
247: * @since 1.1
248: * @param string $tableName Optional table name, leave blank for the defined table for this class to be dropped
249: * @throws AlphaException
250: */
251: public function dropTable($tableName=null);
252:
253: /**
254: * Adds in a new class property without loosing existing data (does an ALTER TABLE query on the
255: * database).
256: *
257: * @param string $propName The name of the new field to add to the database table.
258: * @since 1.1
259: * @throws AlphaException
260: */
261: public function addProperty($propName);
262:
263: /**
264: * Gets the maximum OID value from the database for this class type.
265: *
266: * @return integer The maximum OID value in the class table.
267: * @since 1.1
268: * @throws AlphaException
269: */
270: public function getMAX();
271:
272: /**
273: * Gets the count from the database for the amount of objects of this class.
274: *
275: * @param array $atributes The attributes to count the objects by (optional).
276: * @param array $values The values of the attributes to count the objects by (optional).
277: * @return integer
278: * @since 1.1
279: * @throws AlphaException
280: */
281: public function getCount($attributes=array(), $values=array());
282:
283: /**
284: * Gets the count from the database for the amount of entries in the [tableName]_history table for this business object. Only call
285: * this method on classes where maintainHistory = true, otherwise an exception will be thrown.
286: *
287: * @return integer
288: * @since 1.2
289: * @throws AlphaException
290: */
291: public function getHistoryCount();
292:
293: /**
294: * Populate all of the enum options for this object from the database.
295: *
296: * @since 1.1
297: * @throws AlphaException
298: */
299: public function setEnumOptions();
300:
301: /**
302: * Checks to see if the table exists in the database for the current business class.
303: *
304: * @param boolean $checkHistoryTable Set to true if you want to check for the existance of the _history table for this DAO.
305: * @return boolean
306: * @since 1.1
307: * @throws AlphaException
308: */
309: public function checkTableExists($checkHistoryTable = false);
310:
311: /**
312: * Static method to check the database and see if the table for the indicated BO class name
313: * exists (assumes table name will be $BOClassName less "Object").
314: *
315: * @param string $BOClassName The name of the business object class we are checking.
316: * @param boolean $checkHistoryTable Set to true if you want to check for the existance of the _history table for this DAO.
317: * @return boolean
318: * @since 1.1
319: * @throws AlphaException
320: */
321: public static function checkBOTableExists($BOClassName, $checkHistoryTable = false);
322:
323: /**
324: * Checks to see if the table in the database matches (for fields) the business class definition, i.e. if the
325: * database table is in sync with the class definition.
326: *
327: * @return boolean
328: * @since 1.1
329: * @throws AlphaException
330: */
331: public function checkTableNeedsUpdate();
332:
333: /**
334: * Returns an array containing any properties on the class which have not been created on the database
335: * table yet.
336: *
337: * @return array An array of missing fields in the database table.
338: * @since 1.1
339: * @throws AlphaException
340: */
341: public function findMissingFields();
342:
343: /**
344: * Gets an array of all of the names of the active database indexes for this class.
345: *
346: * @return array An array of database indexes on this table.
347: * @since 1.1
348: * @throws AlphaException
349: */
350: public function getIndexes();
351:
352: /**
353: * Creates a foreign key constraint (index) in the database on the given attribute.
354: *
355: * @param string $attributeName The name of the attribute to apply the index on.
356: * @param string $relatedClass The name of the related class in the format "NameObject".
357: * @param string $relatedClassAttribute The name of the field to relate to on the related class.
358: * @param bool $allowNullValues For foreign key indexes that don't allow null values, set this to false (default is true).
359: * @since 1.1
360: * @throws FailedIndexCreateException
361: */
362: public function createForeignIndex($attributeName, $relatedClass, $relatedClassAttribute);
363:
364: /**
365: * Creates a unique index in the database on the given attribute(s).
366: *
367: * @param string $attribute1Name The first attribute to mark unique in the database.
368: * @param string $attribute2Name The second attribute to mark unique in the databse (optional, use only for composite keys).
369: * @param string $attribute3Name The third attribute to mark unique in the databse (optional, use only for composite keys).
370: * @since 1.1
371: * @throws FailedIndexCreateException
372: */
373: public function createUniqueIndex($attribute1Name, $attribute2Name = '', $attribute3Name = '');
374:
375: /**
376: * Reloads the object from the database, overwritting any attribute values in memory.
377: *
378: * @since 1.1
379: * @throws AlphaException
380: */
381: public function reload();
382:
383: /**
384: * Checks that a record exists for the BO in the database.
385: *
386: * @param int $OID The Object ID of the object we want to see whether it exists or not.
387: * @return boolean
388: * @since 1.1
389: * @throws AlphaException
390: */
391: public function checkRecordExists($OID);
392:
393: /**
394: * Checks to see if the table name matches the classname, and if not if the table
395: * name matches the classname name of another BO, i.e. the table is used to store
396: * multiple types of BOs.
397: *
398: * @return bool
399: * @since 1.1
400: * @throws BadBOTableNameException
401: */
402: public function isTableOverloaded();
403:
404: /**
405: * Starts a new database transaction.
406: *
407: * @since 1.1
408: * @throws AlphaException
409: */
410: public static function begin();
411:
412: /**
413: * Commits the current database transaction.
414: *
415: * @since 1.1
416: * @throws FailedSaveException
417: */
418: public static function commit();
419:
420: /**
421: * Aborts the current database transaction.
422: *
423: * @since 1.1
424: * @throws AlphaException
425: */
426: public static function rollback();
427:
428: /**
429: * Provide the BO that we are going to map the data to from this provider.
430: *
431: * @param AlphaDAO $BO
432: * @since 1.1
433: */
434: public function setBO($BO);
435:
436: /**
437: * Returns a 2d array, where each element in the array is another array
438: * representing a database row.
439: *
440: * @param string $sqlQuery
441: * @throws CustomQueryException
442: * @return array
443: * @since 1.1
444: */
445: public function query($sqlQuery);
446: }
447:
448: ?>