3 namespace Org\Mxchange\CoreFramework\Connection\Database;
5 // Import framework stuff
6 use Org\Mxchange\CoreFramework\Connector\Database\DatabaseConnector;
7 use Org\Mxchange\CoreFramework\Criteria\Criteria;
8 use Org\Mxchange\CoreFramework\Criteria\Storing\StoreableCriteria;
9 use Org\Mxchange\CoreFramework\Database\Backend\DatabaseBackend;
10 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
11 use Org\Mxchange\CoreFramework\Registry\Registerable;
12 use Org\Mxchange\CoreFramework\Middleware\BaseMiddleware;
13 use Org\Mxchange\CoreFramework\Middleware\Debug\DebugMiddleware;
16 use \InvalidArgumentException;
19 * Database selector class
21 * @author Roland Haeder <webmaster@shipsimu.org>
23 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
24 * @license GNU GPL 3.0 or any newer version
25 * @link http://www.shipsimu.org
27 * This program is free software: you can redistribute it and/or modify
28 * it under the terms of the GNU General Public License as published by
29 * the Free Software Foundation, either version 3 of the License, or
30 * (at your option) any later version.
32 * This program is distributed in the hope that it will be useful,
33 * but WITHOUT ANY WARRANTY; without even the implied warranty of
34 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
35 * GNU General Public License for more details.
37 * You should have received a copy of the GNU General Public License
38 * along with this program. If not, see <http://www.gnu.org/licenses/>.
40 class DatabaseConnection extends BaseMiddleware implements DatabaseConnector, Registerable {
42 * Array for connection data
44 private $connectData = array(
52 * The real database layer
54 private $backendInstance = NULL;
57 * An instance of this class
59 private static $selfInstance = NULL;
62 * Protected constructor
64 private function __construct () {
65 // Call parent constructor
66 parent::__construct(__CLASS__);
70 * Creates a new database connection layer
72 * @param $debugInstance An instance of a DebugMiddleware class
73 * @param $backendInstance An instance of a DatabaseBackend class
74 * @todo $debugInstance is currently not used
76 public static final function createDatabaseConnection (DebugMiddleware $debugInstance, DatabaseBackend $backendInstance) {
78 $databaseInstance = new DatabaseConnection();
81 $databaseInstance->setDatabaseLayer($backendInstance);
84 self::$selfInstance = $databaseInstance;
87 return $databaseInstance;
91 * Getter for this class
93 * @return $selfInstance An instance of this class
95 public static final function getSelfInstance () {
96 return self::$selfInstance;
100 * Setter for all database connection data. All these parameters may be
101 * supported by the underlaying backend.
103 * @param $login Login name to database
104 * @param $pass Passwort for above login
105 * @param $dbase Name of used database
106 * @param $host Host to connect to (default: 127.0.0.1)
109 public final function setConnectionData (string $login, string $pass, string $dbase, string $host = '127.0.0.1') {
110 // Transfer connection data
111 $this->connectData['login'] = $login;
112 $this->connectData['pass'] = $pass;
113 $this->connectData['dbase'] = $dbase;
114 $this->connectData['host'] = $host;
118 * Getter for connection data
120 * @return $connectData Connection data stored with this clas
122 public final function getConnectionData () {
123 return $this->connectData;
127 * Setter for the real database layer
128 * @param $backendInstance An instance of a DatabaseBackend class
131 public final function setDatabaseLayer (DatabaseBackend $backendInstance) {
132 $this->backendInstance = $backendInstance;
136 * Getter for index key
138 * @return $indexKey Index key
140 public final function getIndexKey () {
141 return $this->backendInstance->getIndexKey();
145 * Runs a 'select' statement on the database layer with given table name
146 * and criteria. If this doesn't fail the result will be returned
148 * @param $tableName Name of the 'table' we shall query
149 * @param $criteriaInstance An instance of a Criteria class
150 * @return $result The result as an array
151 * @throws InvalidArgumentException If a parameter is empty
153 public function doSelectByTableCriteria (string $tableName, Criteria $criteriaInstance) {
154 // Validate parameter
155 if (empty($tableName)) {
157 throw new InvalidArgumentException('Parameter "tableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
160 // Connect to the database
161 $this->backendInstance->connectToDatabase();
163 // Get result from query
164 $result = $this->backendInstance->querySelect($tableName, $criteriaInstance);
171 * Getter for last exception
173 * @return $exceptionInstance Last thrown exception
175 public final function getLastException () {
176 $exceptionInstance = $this->backendInstance->getLastException();
177 return $exceptionInstance;
181 * 'Inserts' a data set instance into a local file database folder
183 * @param $dataSetInstance A storeable data set
186 public function queryInsertDataSet (StoreableCriteria $dataSetInstance) {
187 // Connect to the database
188 $this->backendInstance->connectToDatabase();
190 // Ask the database layer
191 $this->backendInstance->queryInsertDataSet($dataSetInstance);
195 * 'Updates' a data set instance with a database layer
197 * @param $dataSetInstance A storeable data set
200 public function queryUpdateDataSet (StoreableCriteria $dataSetInstance) {
201 // Connect to the database
202 $this->backendInstance->connectToDatabase();
204 // Ask the database layer
205 $this->backendInstance->queryUpdateDataSet($dataSetInstance);
209 * Getter for primary key column of specified table name
211 * @param $tableName Name of table we need the primary key column from
212 * @return $primaryKey Primary key column of requested table
213 * @throws InvalidArgumentException If a parameter is empty
215 public function getPrimaryKeyOfTable (string $tableName) {
216 // Validate parameter
217 if (empty($tableName)) {
219 throw new InvalidArgumentException('Parameter "tableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
222 // Connect to the database
223 $this->backendInstance->connectToDatabase();
225 // Ask the database layer
226 $primaryKey = $this->backendInstance->getPrimaryKeyOfTable($tableName);
233 * Removes non-public data from given array.
235 * @param $data An array with possible non-public data that needs to be removed.
236 * @return $data A cleaned up array with only public data.
238 public function removeNonPublicDataFromArray (array $data) {
239 // Connect to the database
240 $this->backendInstance->connectToDatabase();
242 // Call database backend
243 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DB-CONNECTION[' . $this->__toString() . ']: Invoking this->backendInstance->removeNonPublicDataFromArray(data) ...');
244 $data = $this->backendInstance->removeNonPublicDataFromArray($data);
246 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugOutput('DB-CONNECTION[' . $this->__toString() . ']: data[]=' . gettype($data));
251 * Count total table rows
253 * @param $tableName Table name
254 * @return $count Total row count
255 * @throws InvalidArgumentException If a parameter is empty
257 public function countTotalRows (string $tableName) {
258 // Validate parameter
259 if (empty($tableName)) {
261 throw new InvalidArgumentException('Parameter "tableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
264 // Connect to the database
265 $this->backendInstance->connectToDatabase();
267 // Ask the database layer
268 $count = $this->backendInstance->countTotalRows($tableName);