/**
* Datasource driver Factory
*
* A clever method which loads and instantiate data source drivers.
*
* Can be called in various ways:
*
* Detect the source type and load the appropriate driver with default
* options:
* <code>
* $driver =& Structures_DataGrid::dataSourceFactory($source);
* </code>
*
* Detect the source type and load the appropriate driver with custom
* options:
* <code>
* $driver =& Structures_DataGrid::dataSourceFactory($source, $options);
* </code>
*
* Load a driver for an explicit type (faster, bypasses detection routine):
* <code>
* $driver =& Structures_DataGrid::dataSourceFactory($source, $options, $type);
* </code>
*
* @access public
* @param mixed $source The data source respective to the driver
* @param array $options An associative array of the form:
* array(optionName => optionValue, ...)
* @param string $type The data source type constant (of the form
* DATAGRID_SOURCE_*)
* @uses Structures_DataGrid::_detectSourceType()
* @return Structures_DataGrid_DataSource|PEAR_Error
* driver object or PEAR_Error on failure
* @static
*/
function &dataSourceFactory($source, $options = array(), $type = null)
{
if (is_null($type) && !($type = Structures_DataGrid::_detectSourceType($source, $options))) {
$error = PEAR::raiseError('Unable to determine the data source type. ' . 'You may want to explicitly specify it.');
return $error;
}
$type = Structures_DataGrid::_correctDriverName($type, 'DataSource');
if (PEAR::isError($type)) {
return $type;
}
$className = "Structures_DataGrid_DataSource_{$type}";
if (PEAR::isError($driver =& Structures_DataGrid::loadDriver($className))) {
return $driver;
}
$result = $driver->bind($source, $options);
if (PEAR::isError($result)) {
return $result;
} else {
return $driver;
}
}
