Fixed #433, #384, #439, #477, #435, #422, #401, #359. Add more class docs for sqlmap.

6 files changed, 154 insertions, 54 deletions

diff --git a/framework/Data/SqlMap/DataMapper/TLazyLoadList.php b/framework/Data/SqlMap/DataMapper/TLazyLoadList.php
index 770c217a..c078efeb 100644
--- a/framework/Data/SqlMap/DataMapper/TLazyLoadList.php
+++ b/framework/Data/SqlMap/DataMapper/TLazyLoadList.php
@@ -7,7 +7,7 @@
  * @copyright Copyright © 2005-2007 PradoSoft

  * @license http://www.pradosoft.com/license/

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  */

 

 /**

@@ -15,7 +15,7 @@
  *

  * @author Wei Zhuo <weizho[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 class TLazyLoadList

@@ -108,7 +108,7 @@ class TLazyLoadList
  *

  * @author Wei Zhuo <weizho[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 class TObjectProxy

diff --git a/framework/Data/SqlMap/DataMapper/TPropertyAccess.php b/framework/Data/SqlMap/DataMapper/TPropertyAccess.php
index 901072ea..c89bcb75 100644
--- a/framework/Data/SqlMap/DataMapper/TPropertyAccess.php
+++ b/framework/Data/SqlMap/DataMapper/TPropertyAccess.php
@@ -7,7 +7,7 @@
  * @copyright Copyright &copy; 2005-2007 PradoSoft

  * @license http://www.pradosoft.com/license/

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  */

 

 /**

@@ -38,7 +38,7 @@
  *

  * @author Wei Zhuo <weizho[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 class TPropertyAccess

diff --git a/framework/Data/SqlMap/DataMapper/TSqlMapCache.php b/framework/Data/SqlMap/DataMapper/TSqlMapCache.php
index a47ed52a..4a621b6a 100644
--- a/framework/Data/SqlMap/DataMapper/TSqlMapCache.php
+++ b/framework/Data/SqlMap/DataMapper/TSqlMapCache.php
@@ -7,7 +7,7 @@
  * @copyright Copyright &copy; 2005-2007 PradoSoft

  * @license http://www.pradosoft.com/license/

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  */

 

 /**

@@ -17,7 +17,7 @@
  *

  * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 abstract class TSqlMapCache implements ICache

@@ -89,7 +89,7 @@ abstract class TSqlMapCache implements ICache
  *

  * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 class TSqlMapFifoCache extends TSqlMapCache

@@ -126,7 +126,7 @@ class TSqlMapFifoCache extends TSqlMapCache
  *

  * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 class TSqlMapLruCache extends TSqlMapCache

@@ -168,7 +168,7 @@ class TSqlMapLruCache extends TSqlMapCache
  *

  * @author Wei Zhuo <weizho[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 class TSqlMapApplicationCache implements ICache

diff --git a/framework/Data/SqlMap/DataMapper/TSqlMapException.php b/framework/Data/SqlMap/DataMapper/TSqlMapException.php
index 52fedb13..76bf7198 100644
--- a/framework/Data/SqlMap/DataMapper/TSqlMapException.php
+++ b/framework/Data/SqlMap/DataMapper/TSqlMapException.php
@@ -1,13 +1,19 @@
 <?php

 

+/**

+ * TSqlMapException is the base exception class for all SqlMap exceptions.

+ *

+ * @author Wei Zhuo <weizho[at]gmail[dot]com>

+ * @version $Id$

+ * @package System.Data.SqlMap

+ * @since 3.1

+ */

 class TSqlMapException extends TException

 {

 	/**

-	 * Constructor.

-	 * @param string error message. This can be a string that is listed

-	 * in the message file. If so, the message in the preferred language

-	 * will be used as the error message. Any rest parameters will be used

-	 * to replace placeholders ({0}, {1}, {2}, etc.) in the message.

+	 * Constructor, similar to the parent constructor. For parameters that

+	 * are of SimpleXmlElement, the tag name and its attribute names and values

+	 * are expanded into a string.

 	 */

 	public function __construct($errorMessage)

 	{

@@ -27,6 +33,10 @@ class TSqlMapException extends TException
 		parent::__construct(strtr($errorMessage,$tokens));

 	}

 

+	/**

+	 * @param SimpleXmlElement node

+	 * @return string tag name and attribute names and values.

+	 */

 	protected function implodeNode($node)

 	{

 		$attributes=array();

@@ -49,21 +59,52 @@ class TSqlMapException extends TException
 	}

 }

 

+/**

+ * TSqlMapConfigurationException, raised during configuration file parsing.

+ *

+ * @author Wei Zhuo <weizho[at]gmail[dot]com>

+ * @version $Id$

+ * @package System.Data.SqlMap

+ * @since 3.1

+ */

 class TSqlMapConfigurationException extends TSqlMapException

 {

 

 }

 

+/**

+ * TSqlMapUndefinedException, raised when mapped statemented are undefined.

+ *

+ * @author Wei Zhuo <weizho[at]gmail[dot]com>

+ * @version $Id$

+ * @package System.Data.SqlMap

+ * @since 3.1

+ */

 class TSqlMapUndefinedException extends TSqlMapException

 {

 

 }

 

+/**

+ * TSqlMapDuplicateException, raised when a duplicate mapped statement is found.

+ *

+ * @author Wei Zhuo <weizho[at]gmail[dot]com>

+ * @version $Id$

+ * @package System.Data.SqlMap

+ * @since 3.1

+ */

 class TSqlMapDuplicateException extends TSqlMapException

 {

 }

 

-

+/**

+ * TInvalidPropertyException, raised when setting or getting an invalid property.

+ *

+ * @author Wei Zhuo <weizho[at]gmail[dot]com>

+ * @version $Id$

+ * @package System.Data.SqlMap

+ * @since 3.1

+ */

 class TInvalidPropertyException extends TSqlMapException

 {

 }

diff --git a/framework/Data/SqlMap/DataMapper/TSqlMapPagedList.php b/framework/Data/SqlMap/DataMapper/TSqlMapPagedList.php
index b15a1d4c..0eb7cc7c 100644
--- a/framework/Data/SqlMap/DataMapper/TSqlMapPagedList.php
+++ b/framework/Data/SqlMap/DataMapper/TSqlMapPagedList.php
@@ -1,14 +1,31 @@
 <?php

+/**

+ * TSqlMapPagedList class file.

+ *

+ * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 2005-2007 PradoSoft

+ * @license http://www.pradosoft.com/license/

+ * @version $Id$

+ * @package System.Data.SqlMap

+ */

 

 Prado::using('System.Collections.TPagedList');

 

 /**

- * TSQLMapPagedList

+ * TSqlMapPagedList implements a list with paging functionality that retrieves

+ * data from a SqlMap statement.

+ *

+ * The maximum number of records fetched is 3 times the page size. It fetches

+ * the current, the previous and the next page at a time. This allows the paged

+ * list to determine if the page is a the begin, the middle or the end of the list.

+ *

+ * The paged list does not need to know about the total number of records.

  *

  * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

  * @version $Id$

- * @package System.Web.UI.WebControls

- * @since 3.0

+ * @package System.Data.SqlMap

+ * @since 3.1

  */

 class TSqlMapPagedList extends TPagedList

 {

@@ -18,8 +35,14 @@ class TSqlMapPagedList extends TPagedList
 	private $_nextPageList;

 	private $_delegate=null;

 

-	public function __construct(IMappedStatement $statement,

-									$parameter, $pageSize, $delegate=null)

+	/**

+	 * Create a new SqlMap paged list.

+	 * @param IMappedStatement SqlMap statement.

+	 * @param mixed query parameters

+	 * @param int page size

+	 * @param mixed delegate for each data row retrieved.

+	 */

+	public function __construct(IMappedStatement $statement,$parameter, $pageSize, $delegate=null)

 	{

 		parent::__construct();

 		parent::setCustomPaging(true);

@@ -27,6 +50,12 @@ class TSqlMapPagedList extends TPagedList
 		$this->_delegate=$delegate;

 	}

 

+	/**

+	 * Initialize the paged list.

+	 * @param IMappedStatement SqlMap statement.

+	 * @param mixed query parameters

+	 * @param int page size.

+	 */

 	protected function initialize($statement, $parameter, $pageSize)

 	{

 		$this->_statement = $statement;

@@ -36,11 +65,19 @@ class TSqlMapPagedList extends TPagedList
 		$this->gotoPage(0);

 	}

 

+	/**

+	 * @throws TSqlMapException custom paging must be enabled.

+	 */

 	public function setCustomPaging($value)

 	{

-		throw new TDataMapperException('sqlmap_must_enable_custom_paging');

+		throw new TSqlMapException('sqlmap_must_enable_custom_paging');

 	}

 

+	/**

+	 * Fetch data by executing the SqlMap statement.

+	 * @param TPageList current object.

+	 * @param TPagedListFetchDataEventParameter fetch parameters

+	 */

 	protected function fetchDataFromStatement($sender, $param)

 	{

 		$limit = $this->getOffsetAndLimit($param);

@@ -50,22 +87,29 @@ class TSqlMapPagedList extends TPagedList
 		$this->populateData($param, $data);

 	}

 

+	/**

+	 * Switches to the next page.

+	 * @return integer|boolean the new page index, false if next page is not availabe.

+	 */

 	public function nextPage()

 	{

-		if($this->getIsNextPageAvailable())

-			return parent::nextPage();

-		else

-			return false;

+		return $this->getIsNextPageAvailable() ? parent::nextPage() : false;

 	}

 

+	/**

+	 * Switches to the previous page.

+	 * @return integer|boolean the new page index, false if previous page is not availabe.

+	 */

 	public function previousPage()

 	{

-		if($this->getIsPreviousPageAvailable())

-			return parent::previousPage();

-		else

-			return false;

+		return $this->getIsPreviousPageAvailable() ? parent::previousPage() : false;

 	}

 

+	/**

+	 * Populate the list with the fetched data.

+	 * @param TPagedListFetchDataEventParameter fetch parameters

+	 * @param array fetched data.

+	 */

 	protected function populateData($param, $data)

 	{

 		$total = $data instanceof TList ? $data->getCount() : count($data);

@@ -88,67 +132,72 @@ class TSqlMapPagedList extends TPagedList
 			}

 			else

 			{

-				$param->setData($this->sublist($data, 0, $pageSize));

-				$this->_nextPageList = $this->sublist($data, $pageSize,$total);

+				$param->setData(array_slice($data, 0, $pageSize));

+				$this->_nextPageList = array_slice($data, $pageSize-1,$total);

 			}

 		}

 		else

 		{

 			if($total <= $pageSize)

 			{

-				$this->_prevPageList = $this->sublist($data, 0, $total);

+				$this->_prevPageList = array_slice($data, 0, $total);

 				$param->setData(array());

 				$this->_nextPageList = null;

 			}

 			else if($total <= $pageSize*2)

 			{

-				$this->_prevPageList = $this->sublist($data, 0, $pageSize);

-				$param->setData($this->sublist($data, $pageSize, $total));

+				$this->_prevPageList = array_slice($data, 0, $pageSize);

+				$param->setData(array_slice($data, $pageSize, $total));

 				$this->_nextPageList = null;

 			}

 			else

 			{

-				$this->_prevPageList = $this->sublist($data, 0, $pageSize);

-				$param->setData($this->sublist($data, $pageSize, $pageSize*2));

-				$this->_nextPageList = $this->sublist($data, $pageSize*2, $total);

+				$this->_prevPageList = array_slice($data, 0, $pageSize);

+				$param->setData(array_slice($data, $pageSize, $pageSize));

+				$this->_nextPageList = array_slice($data, $pageSize*2, $total-$pageSize*2);

 			}

 		}

 	}

 

-	protected function sublist($data, $from, $to)

-	{

-		$array = array();

-		for($i = $from; $i<$to; $i++)

-			$array[] = $data[$i];

-		return $array;

-	}

-

+	/**

+	 * Calculate the data fetch offsets and limits.

+	 * @param TPagedListFetchDataEventParameter fetch parameters

+	 * @return array 1st element is the offset, 2nd element is the limit.

+	 */

 	protected function getOffsetAndLimit($param)

 	{

 		$index = $param->getNewPageIndex();

 		$pageSize = $this->getPageSize();

-		if($index < 1)

-			return array($index, $pageSize*2);

-		else

-			return array(($index-1)*$pageSize, $pageSize*3);

+		return $index < 1 ? array($index, $pageSize*2) : array(($index-1)*$pageSize, $pageSize*3);

 	}

 

+	/**

+	 * @return boolean true if the next page is available, false otherwise.

+	 */

 	public function getIsNextPageAvailable()

 	{

 		return !is_null($this->_nextPageList);

 	}

 

+	/**

+	 * @return boolean true if the previous page is available, false otherwise.

+	 */

 	public function getIsPreviousPageAvailable()

 	{

 		return !is_null($this->_prevPageList);

 	}

 

+	/**

+	 * @return boolean true if is the very last page, false otherwise.

+	 */

 	public function getIsLastPage()

 	{

-		return is_null($this->_nextPageList)

-				|| $this->_nextPageList->getCount() < 1;

+		return is_null($this->_nextPageList) || $this->_nextPageList->getCount() < 1;

 	}

 

+	/**

+	 * @return boolean true if is not first nor last page, false otherwise.

+	 */

 	public function getIsMiddlePage()

 	{

 		return !($this->getIsFirstPage() || $this->getIsLastPage());

diff --git a/framework/Data/SqlMap/DataMapper/TSqlMapTypeHandlerRegistry.php b/framework/Data/SqlMap/DataMapper/TSqlMapTypeHandlerRegistry.php
index c26c0401..d58a7e3c 100644
--- a/framework/Data/SqlMap/DataMapper/TSqlMapTypeHandlerRegistry.php
+++ b/framework/Data/SqlMap/DataMapper/TSqlMapTypeHandlerRegistry.php
@@ -1,4 +1,14 @@
 <?php

+/**

+ * TSqlMapTypeHandlerRegistry, and abstract TSqlMapTypeHandler classes file.

+ *

+ * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 2005-2007 PradoSoft

+ * @license http://www.pradosoft.com/license/

+ * @version $Id$

+ * @package System.Data.SqlMap

+ */

 

 /**

  * TTypeHandlerFactory provides type handler classes to convert database field type

@@ -6,7 +16,7 @@
  *

  * @author Wei Zhuo <weizho[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 class TSqlMapTypeHandlerRegistry

@@ -112,7 +122,7 @@ class TSqlMapTypeHandlerRegistry
  *

  * @author Wei Zhuo <weizho[at]gmail[dot]com>

  * @version $Id$

- * @package System.Data.SqlMap.DataMapper

+ * @package System.Data.SqlMap

  * @since 3.1

  */

 abstract class TSqlMapTypeHandler extends TComponent