From f4c930d7034ad5349ccf55cd27e63c049f48d4b8 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Sebastian=20Skej=C3=B8?= Date: Sat, 11 Jul 2009 18:37:53 +0200 Subject: [PATCH] AOOSModel.php: Documentation + cache modes Added documentation for all data functions. Added cache modes, which defines how calls to populate are handled. At the moment two cache modes are implemented: static and dynamic. Cache modes are set using setCacheMode($cacheMode), which takes an integer parameter, which are define()'ed. AOOSMODEL_CACHE_STATIC set the static cache mode and AOOSMODEL_CACHE_DYNAMIC sets the dynamic cache mode. If cache mode is set to static, model is only populated when the model is empty. If cache mode is set to dynamic, model is emptied and then populated on each call to populate(). --- AOOSModel.php | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 120 insertions(+), 7 deletions(-) diff --git a/AOOSModel.php b/AOOSModel.php index e6b6f1b..f521e09 100644 --- a/AOOSModel.php +++ b/AOOSModel.php @@ -23,6 +23,9 @@ define('AOOSMODELROW_PRIVATE_INSERT', 1); define('AOOSMODELROW_PRIVATE_UPDATE', 2); define('AOOSMODELROW_PRIVATE_REMOVE', 3); +define('AOOSMODEL_CACHE_STATIC', 1); // Only populate if empty +define('AOOSMODEL_CACHE_DYNAMIC', 2); // Clear and populate always + class AOOSModel extends AOOSModule { private $_data = array(); private $_columnIndex = array(); @@ -33,10 +36,18 @@ class AOOSModel extends AOOSModule { private $_storage = null; private $_rows = 0; private $_lastMatch = 0; + private $_cache = AOOSMODEL_CACHE_STATIC; private $_table = null; /* ------ Data functions ------ */ + /** + * Appends a row to the end of the model. If given an array, the function creates the row with the values specified + * in the array. Otherwise the row is empty. + * @param $values An array with the values to fill the row with. Array keys are column indeces and array values are + * the values used to fill the array. + * @return true + */ public function appendRow($values = null) { if ($values instanceof AOOSModelRow) { $values = $values->toArray(); @@ -44,21 +55,31 @@ class AOOSModel extends AOOSModule { $row = new AOOSModelRow($this, $values, AOOSMODELROW_PRIVATE_INSERT); $this->_data[] = $row; $this->_rows++; - return null; + return true; } + /** + * Sets value of $column in row $row to be $value. Throws an AOOSException if $row isn't valid, if the specified + * column isn't a valid column index or setting the value for some reason failed. + * @param $row An integer representing the row + * @param $column A valid column index. + * @param $value The value + * @return boolean + */ public function setData($row, $column, $value) { try { $r = $this->getRow($row); + $ret = $r->$column = $value; } catch (AOOSException $e) { throw $e; } - if (!$this->inColumnIndex($column)) { - throw new AOOSException($this->core(), $this->tr("index_error")); - } - return $r->$column = $value; + return $ret; } + /** + * Returns all rows that haven't been removed + * @return array + */ public function data() { $rows = array(); foreach ($this->_data as $row) { @@ -69,6 +90,13 @@ class AOOSModel extends AOOSModule { return $rows; } + /** + * Returns the row at $index position. If a negative value is given it is counted from the end. Throws an AOOSException + * if $index isn't within bounds. + * @param $index An integer representing the row + * @sa getRows + * @return AOOSModelRow + */ public function getRow($index) { if ($index < 0) { $index = $this->rows()+$index; @@ -79,6 +107,13 @@ class AOOSModel extends AOOSModule { return $this->_data[$index]; } + /** + * Returns all rows from $start until $length rows is found. If $start is negative, it is counted from the end. Throws an AOOSException if $start or $start+$length aren't within bounds. + * @param $start The start row. An integer. + * @param $length Get $length number of rows. An integer. + * @sa getRows + * @return array + */ public function getRows($start, $length) { $rows = array(); if ($start < 0) { @@ -94,10 +129,22 @@ class AOOSModel extends AOOSModule { return $rows; } + /** + * Returns the number of rows. + * @return integer + */ public function rows() { return $this->_rows; } + /** + * Removes rows that match $where. $limit defines the number of rows to remove. Both $where and $limit are arrays. + * $limit consists of two entries, $limit[0] which defines the start of which rows to remove and $limit[1] which + * defines the number of rows to remove. Throws an AOOSException if $where or $limit aren't arrays. + * @param $where An array against which all rows are matched. + * @param $limit The limit array. + * @return true. + */ public function remove($where, $limit) { if (!is_array($where) || !is_array($limit)) { throw new AOOSException($this->core(), $this->tr("not_array")); @@ -110,6 +157,14 @@ class AOOSModel extends AOOSModule { return true; } + /** + * Returns the column $column. $start defines the start row and $length defines the number of rows. $start and + * $length are optional. Throws an AOOSException if $column isn't a valid column index. + * @param $column The column name. + * @param $start An integer representing the start row. Defaults to 0. + * @param $length The number or rows to use. Defaults to all rows. + * @return array + */ public function getColumn($column, $start = 0, $length = null) { $columnA = array(); if (!$this->inColumnIndex($column)) { @@ -125,6 +180,14 @@ class AOOSModel extends AOOSModule { return $columnA; } + /** + * Returns the first row that matches $match from $offset and forwards. The rows are matched using preg_match and + * delimiters should NOT be included in the array values. Throws an AOOSException if $offset isn't within bounds. + * @param $match An array in which keys are column names and values are the values to match against. + * @param $offset The row to start searching in. + * @sa findAll + * @return AOOSModelRow or false if no rows are found. + */ public function find($match, $offset = 0) { $m = false; for($i = $offset; $i < $this->rows(); ++$i) { @@ -142,11 +205,23 @@ class AOOSModel extends AOOSModule { return $m; } + /** + * Returns all rows that match $match from $offset and forwards. Throws an AOOSException if $offset isn't within + * bounds. + * @param $match An array in which keys are column names and values are the values to match against. + * @param $offset The row to start searching in. + * @sa find + * @return array + */ public function findAll($match, $offset = 0) { $m = array(); $i = 0; while (true) { - $row = $this->find($match, $i); + try { + $row = $this->find($match, $i); + } catch (AOOSException $e) { + throw $e; + } if ($row === false) { break; } @@ -156,6 +231,11 @@ class AOOSModel extends AOOSModule { return $m; } + /** + * Empties the model and removes all propeties, constraints and flags. Only column indeces are kept. + * @sa resetData + * @return true + */ public function reset() { $this->_data = array(); $this->_properties = array(); @@ -165,12 +245,30 @@ class AOOSModel extends AOOSModule { return true; } + /** + * Empties the model. + * @sa reset + * @return true; + */ public function resetData() { $this->_data = array(); $this->_rows = 0; return true; } + /* ----- Cache mode ------ */ + public function setCacheMode($cacheMode) { + if ($cacheMode != AOOSMODEL_CACHE_STATIC && $cacheMode != AOOSMODEL_CACHE_DYNAMIC) { + throw new AOOSExcpetion($this->core(), $this->tr("not_valid_cache_mode")); + } + $this->_cache = $cacheMode; + return true; + } + + public function cacheMode() { + return $this->_cache; + } + /* ----- Column index ------ */ public function setColumnIndex($columnindex) { @@ -328,6 +426,16 @@ class AOOSModel extends AOOSModule { } public function populate($where = null, $order = null, $limit = null) { + switch($this->_cache) { + case(AOOSMODEL_CACHE_STATIC): + if ($this->rows() != 0) { + return false; + } + break; + case(AOOSMODEL_CACHE_DYNAMIC): + $this->resetData(); + break; + } $fields = array(); if (is_array($where)) { $where = new AOOSModelRow($this, $where); @@ -412,7 +520,12 @@ class AOOSModelRow extends AOOSModule implements ArrayAccess{ } public function __set($name, $value) { - return $this->_setData($name, $value); + try { + $ret = $this->_setData($name, $value); + } catch (AOOSException $e) { + throw $e; + } + return $ret; } public function __get($name) { -- 2.11.4.GIT