Alpha Framework alpha--model
[ class tree: alpha--model ] [ index: alpha--model ] [ all elements ]
alpha--model
Packages:
alpha--controller
alpha--controller--front
alpha--exceptions
alpha--model
alpha--model--types
alpha--service
alpha--tasks
alpha--tests
alpha--util
alpha--util--cache
alpha--util--convertors
alpha--util--feeds
alpha--util--filters
alpha--util--graphs
alpha--util--helpers
alpha--util--metrics
alpha--view
alpha--view--widgets

Source for file AlphaDAOProviderInterface.inc

Documentation is available at AlphaDAOProviderInterface.inc

  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 1453 2011-12-04 15:12:54Z johnc $
  11.  * @license http://www.opensource.org/licenses/bsd-license.php The BSD License
  12.  * @copyright Copyright (c) 2011, 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.      * @return array An array containing objects of this type of business object.
  136.      * @since 1.1
  137.      * @throws BONotFoundException
  138.      * @throws IllegalArguementException
  139.      */
  140.     public function loadAllByAttributes($attributes=array(), $values=array(), $start=0, $limit=0, $orderBy='OID', $order='ASC', $ignoreClassType=false);
  141.     
  142.     /**
  143.      * Loads all of the objects of this class that where updated (updated_ts value) on the date indicated.
  144.      * 
  145.      * @param string $date The date for which to load the objects updated on, in the format 'YYYY-MM-DD'.
  146.      * @param integer $start The start of the SQL LIMIT clause, useful for pagination.
  147.      * @param integer $limit The amount (limit) of objects to load, useful for pagination.
  148.      * @param string $orderBy The name of the field to sort the objects by.
  149.      * @param string $order The order to sort the objects by.
  150.      * @param boolean $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type
  151.      * @return array An array containing objects of this type of business object.
  152.      * @since 1.1
  153.      * @throws BONotFoundException
  154.      */
  155.     public function loadAllByDayUpdated($date, $start=0, $limit=0, $orderBy="OID", $order="ASC", $ignoreClassType=false);
  156.     
  157.     /**
  158.      * Loads all of the specified attribute values of this class by the specified attribute into an
  159.      * array which is returned.
  160.      * 
  161.      * @param string $attribute The attribute name to load the field values by.
  162.      * @param string $value The value of the attribute to load the field values by.
  163.      * @param string $returnAttribute The name of the attribute to return.
  164.      * @param string $order The order to sort the BOs by.
  165.      * @param boolean $ignoreClassType Default is false, set to true if you want to load from overloaded tables and ignore the class type.
  166.      * @return array An array of field values.
  167.      * @since 1.1
  168.      * @throws BONotFoundException
  169.      */
  170.     public function loadAllFieldValuesByAttribute($attribute, $value, $returnAttribute, $order='ASC', $ignoreClassType=false);
  171.  
  172.     /**
  173.      * Saves the object.  If $this->OID is empty or null it will INSERT, otherwise UPDATE.
  174.      * 
  175.      * @since 1.1
  176.      * @throws FailedSaveException
  177.      * @throws LockingException
  178.      * @throws ValidationException
  179.      */
  180.     public function save();
  181.     
  182.     /**
  183.      * Saves the field specified with the value supplied.  Only works for persistent BOs.  Note that no Alpha type
  184.      * validation is performed with this method!
  185.      * 
  186.      * @param string $attribute The name of the attribute to save.
  187.      * @param mixed $value The value of the attribute to save.
  188.      * @since 1.1
  189.      * @throws IllegalArguementException
  190.      * @throws FailedSaveException
  191.      */
  192.     public function saveAttribute($attribute, $value);
  193.     
  194.     /**
  195.      * Deletes the current object from the database.
  196.      * 
  197.      * @since 1.1
  198.      * @throws FailedDeleteException
  199.      */
  200.     public function delete();
  201.     
  202.     /**
  203.      * Gets the version_num of the object from the database (returns 0 if the BO is not saved yet).
  204.      * 
  205.      * @return integer 
  206.      * @since 1.1
  207.      * @throws BONotFoundException
  208.      */
  209.     public function getVersion();
  210.  
  211.     /**
  212.      * Builds a new database table for the BO class.
  213.      * 
  214.      * @since 1.1
  215.      * @throws AlphaException
  216.      */    
  217.     public function makeTable();
  218.  
  219.     /**
  220.      * Re-builds the table if the model requirements have changed.  All data is lost!
  221.      * 
  222.      * @since 1.1
  223.      * @throws AlphaException
  224.      */
  225.     public function rebuildTable();
  226.     
  227.     /**
  228.      * Drops the table if the model requirements have changed.  All data is lost!
  229.      * 
  230.      * @since 1.1
  231.      * @param string $tableName Optional table name, leave blank for the defined table for this class to be dropped
  232.      * @throws AlphaException
  233.      */
  234.     public function dropTable($tableName=null);
  235.  
  236.     /**
  237.      * Adds in a new class property without loosing existing data (does an ALTER TABLE query on the
  238.      * database).
  239.      * 
  240.      * @param string $propName The name of the new field to add to the database table.
  241.      * @since 1.1
  242.      * @throws AlphaException
  243.      */
  244.     public function addProperty($propName);
  245.  
  246.     /**
  247.      * Gets the maximum OID value from the database for this class type.
  248.      * 
  249.      * @return integer The maximum OID value in the class table.
  250.      * @since 1.1
  251.      * @throws AlphaException
  252.      */
  253.     public function getMAX();
  254.     
  255.     /**
  256.      * Gets the count from the database for the amount of objects of this class.
  257.      * 
  258.      * @param array $atributes The attributes to count the objects by (optional).
  259.      * @param array $values The values of the attributes to count the objects by (optional).
  260.      * @return integer 
  261.      * @since 1.1
  262.      * @throws AlphaException
  263.      */
  264.     public function getCount($attributes=array(), $values=array());
  265.     
  266.     /**
  267.      * Populate all of the enum options for this object from the database.
  268.      * 
  269.      * @since 1.1
  270.      * @throws AlphaException
  271.      */
  272.     public function setEnumOptions();
  273.     
  274.     /**
  275.      * Checks to see if the table exists in the database for the current business class.
  276.      * 
  277.      * @return boolean 
  278.      * @since 1.1
  279.      * @throws AlphaException
  280.      */
  281.     public function checkTableExists();
  282.     
  283.     /**
  284.      * Static method to check the database and see if the table for the indicated BO class name
  285.      * exists (assumes table name will be $BOClassName less "Object").
  286.      * 
  287.      * @param string $BOClassName The name of the business object class we are checking.
  288.      * @return boolean 
  289.      * @since 1.1
  290.      * @throws AlphaException
  291.      */
  292.     public static function checkBOTableExists($BOClassName);
  293.     
  294.     /**
  295.      * Checks to see if the table in the database matches (for fields) the business class definition, i.e. if the
  296.      * database table is in sync with the class definition.
  297.      * 
  298.      * @return boolean 
  299.      * @since 1.1
  300.      * @throws AlphaException
  301.      */
  302.     public function checkTableNeedsUpdate();
  303.     
  304.     /**
  305.      * Returns an array containing any properties on the class which have not been created on the database
  306.      * table yet.
  307.      * 
  308.      * @return array An array of missing fields in the database table.
  309.      * @since 1.1
  310.      * @throws AlphaException
  311.      */
  312.     public function findMissingFields();
  313.     
  314.     /**
  315.      * Gets an array of all of the names of the active database indexes for this class.
  316.      *
  317.      * @return array An array of database indexes on this table.
  318.      * @since 1.1
  319.      * @throws AlphaException
  320.      */
  321.     public function getIndexes();
  322.     
  323.     /**
  324.      * Creates a foreign key constraint (index) in the database on the given attribute.
  325.      * 
  326.      * @param string $attributeName The name of the attribute to apply the index on.
  327.      * @param string $relatedClass The name of the related class in the format "NameObject".
  328.      * @param string $relatedClassAttribute The name of the field to relate to on the related class.
  329.      * @param bool $allowNullValues For foreign key indexes that don't allow null values, set this to false (default is true).
  330.      * @since 1.1
  331.      * @throws FailedIndexCreateException
  332.      */
  333.     public function createForeignIndex($attributeName, $relatedClass, $relatedClassAttribute);
  334.     
  335.     /**
  336.      * Creates a unique index in the database on the given attribute(s).
  337.      * 
  338.      * @param string $attribute1Name The first attribute to mark unique in the database.
  339.      * @param string $attribute2Name The second attribute to mark unique in the databse (optional, use only for composite keys).
  340.      * @param string $attribute3Name The third attribute to mark unique in the databse (optional, use only for composite keys).
  341.      * @since 1.1
  342.      * @throws FailedIndexCreateException
  343.      */
  344.     public function createUniqueIndex($attribute1Name, $attribute2Name = '', $attribute3Name = '');
  345.     
  346.     /**
  347.      * Reloads the object from the database, overwritting any attribute values in memory.
  348.      * 
  349.      * @since 1.1
  350.      * @throws AlphaException
  351.      */
  352.     public function reload();
  353.     
  354.     /**
  355.      * Checks that a record exists for the BO in the database.
  356.      * 
  357.      * @param int $OID The Object ID of the object we want to see whether it exists or not.
  358.      * @return boolean 
  359.      * @since 1.1
  360.      * @throws AlphaException
  361.      */
  362.     public function checkRecordExists($OID);
  363.     
  364.     /**
  365.      * Checks to see if the table name matches the classname, and if not if the table
  366.      * name matches the classname name of another BO, i.e. the table is used to store
  367.      * multiple types of BOs.
  368.      * 
  369.      * @return bool 
  370.      * @since 1.1
  371.      * @throws BadBOTableNameException
  372.      */
  373.     public function isTableOverloaded();
  374.     
  375.     /**
  376.      * Starts a new database transaction.
  377.      * 
  378.      * @since 1.1
  379.      * @throws AlphaException
  380.      */
  381.     public static function begin();
  382.     
  383.     /**
  384.      * Commits the current database transaction.
  385.      * 
  386.      * @since 1.1
  387.      * @throws FailedSaveException
  388.      */
  389.     public static function commit();
  390.       
  391.     /**
  392.      * Aborts the current database transaction.
  393.      * 
  394.      * @since 1.1
  395.      * @throws AlphaException
  396.      */
  397.     public static function rollback();
  398.     
  399.        /**
  400.         * Provide the BO that we are going to map the data to from this provider.
  401.         * 
  402.         * @param AlphaDAO $BO 
  403.         * @since 1.1
  404.         */
  405.        public function setBO($BO);
  406.        
  407.        /**
  408.         * Returns a 2d array, where each element in the array is another array
  409.      * representing a database row.
  410.         * 
  411.         * @param string $sqlQuery 
  412.         * @throws CustomQueryException
  413.         * @return array 
  414.         * @since 1.1
  415.         */
  416.        public function query($sqlQuery);
  417. }
  418.  
  419. ?>
Documentation generated on Tue, 13 Dec 2011 20:25:49 +0000 by phpDocumentor 1.4.3