Source for file DBHandler.class.php

Documentation is available at DBHandler.class.php

  1. <?php
  2. /**
  3. * @package harmoni.dbc
  4. *
  5. * @copyright Copyright &copy; 2005, Middlebury College
  6. * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License (GPL)
  7. *
  8. * @version $Id: DBHandler.class.php,v 1.27 2007/09/14 13:57:06 adamfranco Exp $
  9. */
  10. /**
  11. * A constant for the MySQL database type.
  12. * @const MYSQL A constant for the MySQL database type.
  13. * @access public
  14. * @package harmoni.dbc
  15. */
  16. define("MYSQL", 1);
  17.  
  18.  
  19. /**
  20. * A constant for the POSTGRE_SQL database type.
  21. * @const POSTGRE_SQL A constant for the POSTGRE_SQL database type.
  22. * @access public
  23. * @package harmoni.dbc
  24. */
  25. define("POSTGRESQL", 2);
  26.  
  27.  
  28. /**
  29. * A constant for the ORACLE database type.
  30. * @const ORACLE A constant for the ORACLE database type.
  31. * @access public
  32. * @package harmoni.dbc
  33. */
  34. define("ORACLE", 3);
  35.  
  36.  
  37. /**
  38. * A constant for the SQLSERVER database type.
  39. * @const SQLSERVER A constant for the SQLSERVER database type.
  40. * @access public
  41. * @package harmoni.dbc
  42. */
  43. define("SQLSERVER", 4);
  44.  
  45. require_once(HARMONI."DBHandler/SelectQuery.class.php");
  46. require_once(HARMONI."DBHandler/UpdateQuery.class.php");
  47. require_once(HARMONI."DBHandler/DeleteQuery.class.php");
  48. require_once(HARMONI."DBHandler/InsertQuery.class.php");
  49. require_once(HARMONI."DBHandler/GenericSQLQuery.class.php");
  50. require_once(HARMONI.'DBHandler/MySQL/MySQLDatabase.class.php');
  51. require_once(HARMONI.'DBHandler/PostgreSQL/PostgreSQLDatabase.class.php');
  52. require_once(HARMONI.'DBHandler/Oracle/OracleDatabase.class.php');
  53. require_once(HARMONI.'DBHandler/SQLUtils.static.php');
  54. require_once(HARMONI.'utilities/Queue.class.php');
  55.  
  56. require_once(HARMONI."Primitives/Chronology/include.php");
  57.  
  58.  
  59. /**
  60. * A Database Handler. The DBHandler is to be loaded at the beginning
  61. * program executution with configuration settings for the database type, name,
  62. * server, user, and password.
  63. *
  64. *
  65. * @package harmoni.dbc
  66. *
  67. * @copyright Copyright &copy; 2005, Middlebury College
  68. * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License (GPL)
  69. *
  70. * @version $Id: DBHandler.class.php,v 1.27 2007/09/14 13:57:06 adamfranco Exp $
  71. */
  72.  
  73. class DBHandler {
  74. /**
  75. * An array of all databases.
  76. * An array of all databases.
  77. * @var array $_databases An array of all databases.
  78. * @access private
  79. */
  80. var $_databases;
  81.  
  82.  
  83.  
  84. /**
  85. * Constructor.
  86. * @access public
  87. */
  88. function DBHandler() {
  89. $this->_databases = array();
  90. }
  91. /**
  92. * Assign the configuration of this Manager. Valid configuration options are as
  93. * follows:
  94. * database_index integer
  95. * database_name string
  96. *
  97. * @param object Properties $configuration (original type: java.util.Properties)
  98. *
  99. * @throws object OsidException An exception with one of the following
  100. * messages defined in org.osid.OsidException: {@link }
  101. * org.osid.OsidException#OPERATION_FAILED OPERATION_FAILED},
  102. * {@link org.osid.OsidException#PERMISSION_DENIED}
  103. * PERMISSION_DENIED}, {@link }
  104. * org.osid.OsidException#CONFIGURATION_ERROR
  105. * CONFIGURATION_ERROR}, {@link }
  106. * org.osid.OsidException#UNIMPLEMENTED UNIMPLEMENTED}, {@link }
  107. * org.osid.OsidException#NULL_ARGUMENT NULL_ARGUMENT}
  108. *
  109. * @access public
  110. */
  111. function assignConfiguration ( $configuration ) {
  112. $this->_configuration =$configuration;
  113. }
  114.  
  115. /**
  116. * Return context of this OsidManager.
  117. *
  118. * @return object OsidContext
  119. *
  120. * @throws object OsidException
  121. *
  122. * @access public
  123. */
  124. function getOsidContext () {
  125. return $this->_osidContext;
  126. }
  127.  
  128. /**
  129. * Assign the context of this OsidManager.
  130. *
  131. * @param object OsidContext $context
  132. *
  133. * @throws object OsidException An exception with one of the following
  134. * messages defined in org.osid.OsidException: {@link }
  135. * org.osid.OsidException#NULL_ARGUMENT NULL_ARGUMENT}
  136. *
  137. * @access public
  138. */
  139. function assignOsidContext ( $context ) {
  140. $this->_osidContext =$context;
  141. }
  142. /**
  143. * Adds the specified Database object to the list of databases.
  144. * @access public
  145. * @param ref object database
  146. * @return mixed $dbIndex The index of the new database, if it was created successfully; False, otherwise.
  147. */
  148. function addDatabase(Database $database) {
  149.  
  150. $this->_databases[] =$database;
  151. // return the index of the database we just created
  152. return (count($this->_databases) - 1);
  153. }
  154.  
  155. /**
  156. * *Deprecated* Creates a new database connection.
  157. * @param string $dbType The type of database: MYSQL, POSTGRES, ORACLE, OKI, etc.
  158. * @param string $dbHost The hostname for the database, i.e. myserver.mydomain.edu.
  159. * @param string $dbName The name of the database.
  160. * @param string $dbUser The username with which to connect to the database.
  161. * @param string $dbPass The password for $_dbUser with which to connect to the database.
  162. * @return mixed $dbIndex The index of the new database, if it was created successfully; False, otherwise.
  163. * @deprecated July 20, 2003 - Use addDatabase instead.
  164. * @access public
  165. */
  166. function createDatabase($dbType, $dbHost, $dbName, $dbUser, $dbPass) {
  167. // ** parameter validation
  168. $stringRule = StringValidatorRule::getRule();
  169. $integerRule = IntegerValidatorRule::getRule();
  170. ArgumentValidator::validate($dbType, $integerRule, true);
  171. ArgumentValidator::validate($dbHost, $stringRule, true);
  172. ArgumentValidator::validate($dbName, $stringRule, true);
  173. ArgumentValidator::validate($dbUser, $stringRule, true);
  174. ArgumentValidator::validate($dbPass, $stringRule, true);
  175. // ** end of parameter validation
  176.  
  177. // depending on $dbType, instantiate the corresponding Database object.
  178. switch ($dbType) {
  179. case MYSQL :
  180. $this->_databases[] = new MySQLDatabase($dbHost, $dbName, $dbUser, $dbPass);
  181. break;
  182. case ORACLE :
  183. ;
  184. break;
  185. case POSTGRESQL :
  186. $this->_databases[] = new PostgreSQLDatabase($dbHost, $dbName, $dbUser, $dbPass);
  187. break;
  188. case SQLSERVER :
  189. ;
  190. break;
  191. case OKI :
  192. ;
  193. break;
  194. default : {
  195. // unsupported database type
  196. throw new ConnectionDatabaseException("Unknown database type.");
  197. return false;
  198. }
  199. }
  200. // return the index of the database we just created
  201. return (count($this->_databases) - 1);
  202. }
  203.  
  204. /**
  205. * Returns a list of the tables that exist in the database referenced by $index.
  206. * @param optional integer $index
  207. * @return array
  208. * @access public
  209. */
  210. function getTableList($index=0) {
  211. $this->_validateDBIndex($index);
  212. return $this->_databases[$index]->getTableList();
  213. }
  214. /**
  215. * Answer the type of the database. Will be one of the constants defined above:
  216. * MYSQL, POSTGRESQL, ORACLE, or SQLSERVER
  217. *
  218. * @param optional integer $dbIndex Default is 0.
  219. * @return integer
  220. * @access public
  221. * @since 9/11/07
  222. */
  223. public function getDatabaseType ($dbIndex = 0) {
  224. if (!isset($this->_databases[$dbIndex]))
  225. throw new DatabaseException("Unknown database index '$dbIndex'.");
  226. if ($this->_databases[$dbIndex] instanceof MySQLDatabase)
  227. return MYSQL;
  228. if ($this->_databases[$dbIndex] instanceof PostgreSQLDatabase)
  229. return POSTGRESQL;
  230. if ($this->_databases[$dbIndex] instanceof OracleDatabase)
  231. return ORACLE;
  232. if ($this->_databases[$dbIndex] instanceof SqlServerDatabase)
  233. return SQLSERVER;
  234. throw new DatabaseException("Type unknow for database of class '".get_class($this->_databases[$dbIndex])."'.");
  235. }
  236.  
  237. /**
  238. * Run a database query based on the Query object and return a QueryResult object.
  239. * @param object Query A query object which holds the query to run.
  240. * @param integer $dbIndex The index of the database on which to run the query. Default is 0, the database created on handler instantiation.
  241. * @return object QueryResultInterface Returns a QueryResult object that impliments QueryResultInterface and corresponds to the DB configuration.
  242. * @access public
  243. */
  244. function query(Query $query, $dbIndex=0) {
  245. if (!isset($this->_databases[$dbIndex]))
  246. throw new DatabaseException("Unknown database index '$dbIndex'.");
  247. // run the query on the appropriate database.
  248. $result = $this->_databases[$dbIndex]->query($query);
  249. return $result;
  250. }
  251.  
  252. /**
  253. * Run a database query for each Query in the Queue and return a Queue of QueryResults.
  254. * @param object QueueInterface A queue object which holds the queries to run.
  255. * @param integer $dbIndex The index of the database on which to run the query. Default is 0, the database created on handler instantiation.
  256. * @return object QueInterface Returns a Queue of QueryResults.
  257. * @access public
  258. */
  259. function queryQueue(Queue $queue, $dbIndex=0) {
  260. // ** parameter validation
  261. $this->_validateDBIndex($dbIndex);
  262. // ** end of parameter validation
  263.  
  264. $resultQueue = new Queue();
  265. while ($queue->hasNext()) {
  266. $result =$this->_databases[$dbIndex]->query($queue->next());
  267. $resultQueue->add($result);
  268. }
  269. return $resultQueue;
  270. }
  271. /**
  272. * Returns the short string name of the database index passed.
  273. * @access public
  274. * @return string
  275. */
  276. function getStringName($dbIndex=0) {
  277. $this->_validateDBIndex($dbIndex);
  278. return $this->_databases[$dbIndex]->getStringName();
  279. }
  280. /**
  281. * Gets the total number of queries that have been run so far.
  282. * Gets the total number of queries that have been run so far.
  283. * @return integer The number of queries that have run so far.
  284. * @access public
  285. */
  286. function getTotalNumberOfQueries() {
  287. $numberOfQueries = 0;
  288. foreach (array_keys($this->_databases) as $key) {
  289. $numberOfQueries += $this->_databases[$key]->getNumberSuccessfulQueries();
  290. $numberOfQueries += $this->_databases[$key]->getNumberFailedQueries();
  291. }
  292. return $numberOfQueries;
  293. }
  294. /**
  295. * Gets the total number of queries that have been run successfully so far.
  296. * Gets the total number of queries that have been run successfully so far.
  297. * @return integer The number of queries that have run successfully so far.
  298. * @access public
  299. */
  300. function getTotalNumberOfSuccessfulQueries() {
  301. $numberOfQueries = 0;
  302. foreach (array_keys($this->_databases) as $key) {
  303. $numberOfQueries += $this->_databases[$key]->getNumberSuccessfulQueries();
  304. }
  305. return $numberOfQueries;
  306. }
  307.  
  308. /**
  309. * Gets the total number of queries that have failed so far.
  310. * Gets the total number of queries that have failed so far.
  311. * @return integer The number of queries that have failed so far.
  312. * @access public
  313. */
  314. function getTotalNumberOfFailedQueries() {
  315. $numberOfQueries = 0;
  316. foreach (array_keys($this->_databases) as $key) {
  317. $numberOfQueries += $this->_databases[$key]->getNumberFailedQueries();
  318. }
  319. return $numberOfQueries;
  320. }
  321. /**
  322. * Connect to the database.
  323. * @param integer $dbIndex The index of the database with which to connect. Default is 0, the database created on handler instantiation.
  324. * @return boolean True, if successful; False, otherwise.
  325. * @access public
  326. */
  327. function connect($dbIndex = 0) {
  328. // ** parameter validation
  329. $this->_validateDBIndex($dbIndex);
  330. // ** end of parameter validation
  331. // attempt to connect to the specified database
  332. $result = $this->_databases[$dbIndex]->connect();
  333. // see, if we were successful
  334. $isSuccessful = ($result !== false);
  335. return $isSuccessful;
  336. }
  337. /**
  338. * Persistantly connect to the database.
  339. * @param integer $dbIndex The index of the database with which to pconnect. Default is 0, the database created on handler instantiation.
  340. * @return boolean True, if successful; False, otherwise.
  341. * @access public
  342. */
  343. function pConnect($dbIndex = 0) {
  344. // ** parameter validation
  345. $this->_validateDBIndex($dbIndex);
  346. // ** end of parameter validation
  347. // attempt to connect to the specified database
  348. $result = $this->_databases[$dbIndex]->pConnect();
  349. // see, if we were successful
  350. $isSuccessful = ($result !== false);
  351. return $isSuccessful;
  352. }
  353.  
  354. /**
  355. * disconnect from the database.
  356. * @param integer $dbIndex The index of the database with which to disconnect. Default is 0, the database created on handler instantiation.
  357. * @return boolean True, if successful; False, otherwise.
  358. * @access public
  359. */
  360. function disconnect($dbIndex = 0) {
  361. // ** parameter validation
  362. $this->_validateDBIndex($dbIndex);
  363. // ** end of parameter validation
  364. // attempt to disconnect from the specified database
  365. $result = $this->_databases[$dbIndex]->disconnect();
  366. // see, if we were successful
  367. $isSuccessful = ($result !== false);
  368. return $isSuccessful;
  369. }
  370. /**
  371. * Indicates whether there is an open connection to the database.
  372. * Indicates whether there is an open connection to the database.
  373. * @access public
  374. * @return boolean True, if there is an open connection to the database; False, otherwise.
  375. */
  376. function isConnected($dbIndex = 0) {
  377. // ** parameter validation
  378. $this->_validateDBIndex($dbIndex);
  379. // ** end of parameter validation
  380. // see if the specified database is connected
  381. $isConnected = $this->_databases[$dbIndex]->isConnected();
  382.  
  383. return $isConnected;
  384. }
  385.  
  386.  
  387.  
  388. /**
  389. * Converts a DateAndTime object to a proper datetime/timestamp/time representation
  390. * for the specified database object. $dateAndTime must implement asDateAndTime().
  391. * @access public
  392. * @param ref object DateAndTime The DateAndTime object to convert.
  393. * @param integer dbIndex The index of the database to use (0 by default).
  394. * @return mixed A proper datetime/timestamp/time representation for this Database.
  395. */
  396. function toDBDate(DateAndTime $dateAndTime, $dbIndex = 0) {
  397. // ** parameter validation
  398. ArgumentValidator::validate($dateAndTime,
  399. HasMethodsValidatorRule::getRule("asDateAndTime"), true);
  400. $this->_validateDBIndex($dbIndex);
  401. // ** end of parameter validation
  402. return $this->_databases[$dbIndex]->toDBDate($dateAndTime);
  403. }
  404. /**
  405. * Converts a database datetime/timestamp/time value (that has been fetched
  406. * from the db) to a DateAndTime object.
  407. * @access public
  408. * @param mixed A database datetime/timestamp/time value (that has been fetched
  409. * from the db).
  410. * @param integer dbIndex The index of the database to use (0 by default).
  411. * @return ref object The DateAndTime object.
  412. */
  413. function fromDBDate($value, $dbIndex = 0) {
  414. // ** parameter validation
  415. $this->_validateDBIndex($dbIndex);
  416. // ** end of parameter validation
  417. return $this->_databases[$dbIndex]->fromDBDate($value);
  418. }
  419. /**
  420. * Return TRUE if this database supports transactions.
  421. *
  422. * @return boolean
  423. * @access public
  424. * @since 3/9/05
  425. */
  426. function supportsTransactions ( $dbIndex = 0 ) {
  427. // ** parameter validation
  428. $this->_validateDBIndex($dbIndex);
  429. // ** end of parameter validation
  430. return $this->_databases[$dbIndex]->supportsTransactions();
  431. }
  432. /**
  433. * Begin a transaction.
  434. *
  435. * @return void
  436. * @access public
  437. * @since 3/9/05
  438. */
  439. function beginTransaction ( $dbIndex = 0 ) {
  440. // ** parameter validation
  441. $this->_validateDBIndex($dbIndex);
  442. // ** end of parameter validation
  443. $this->_databases[$dbIndex]->beginTransaction();
  444. }
  445. /**
  446. * Commit a transaction. This will roll-back changes if errors occured in the
  447. * transaction block.
  448. *
  449. * @return void
  450. * @access public
  451. * @since 3/9/05
  452. */
  453. function commitTransaction ( $dbIndex = 0 ) {
  454. // ** parameter validation
  455. $this->_validateDBIndex($dbIndex);
  456. // ** end of parameter validation
  457. $this->_databases[$dbIndex]->commitTransaction();
  458. }
  459. /**
  460. * Roll-back a transaction manually instead of committing
  461. *
  462. * @return void
  463. * @access public
  464. * @since 3/9/05
  465. */
  466. function rollbackTransaction ( $dbIndex = 0 ) {
  467. // ** parameter validation
  468. $this->_validateDBIndex($dbIndex);
  469. // ** end of parameter validation
  470. $this->_databases[$dbIndex]->rollbackTransaction();
  471. }
  472. /**
  473. * Private method for validating the dbIndex passed.
  474. *
  475. * @param integer $dbIndex
  476. * @return void
  477. * @access private
  478. * @since 3/9/05
  479. */
  480. function _validateDBIndex ($dbIndex) {
  481. // ** parameter validation
  482. ArgumentValidator::validate($dbIndex, IntegerValidatorRule::getRule(), true);
  483. // ** end of parameter validation
  484. // check that the index is valid
  485. if (!is_object($this->_databases[$dbIndex])) {
  486. throw new DatabaseException("Invalid database index.");
  487. return false;
  488. }
  489. }
  490. /**
  491. * Generate the SQL string for the specified Query and Database
  492. *
  493. * @param object $query
  494. * @param int $dbIndex
  495. * @return string
  496. * @access public
  497. * @since 11/14/06
  498. */
  499. function generateSQL (Query $query, $dbIndex = 0) {
  500. return $this->_databases[$dbIndex]->generateSQL($query);
  501. }
  502. }
  503. ?>

Documentation generated on Wed, 19 Sep 2007 10:22:38 -0400 by phpDocumentor 1.3.0RC3