framework/main/classes/criteria/dataset/class_DataSetCriteria.php

   1 <?php
   2 // Own namespace
   3 namespace Org\Mxchange\CoreFramework\Criteria\DataSet;
   4
   5 // Import framework stuff
   6 use Org\Mxchange\CoreFramework\Criteria\BaseCriteria;
   7 use Org\Mxchange\CoreFramework\Criteria\Local\LocalSearchCriteria;
   8 use Org\Mxchange\CoreFramework\Criteria\Storing\StoreableCriteria;
   9 use Org\Mxchange\CoreFramework\Generic\FrameworkInterface;
  10
  11 // Import SPL stuff
  12 use \BadMethodCallException;
  13 use \InvalidArgumentException;
  14
  15 /**
  16  * A set of data storeable in databases
  17  *
  18  * @author              Roland Haeder <webmaster@shipsimu.org>
  19  * @version             0.0.0
  20  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2023 Core Developer Team
  21  * @license             GNU GPL 3.0 or any newer version
  22  * @link                http://www.shipsimu.org
  23  *
  24  * This program is free software: you can redistribute it and/or modify
  25  * it under the terms of the GNU General Public License as published by
  26  * the Free Software Foundation, either version 3 of the License, or
  27  * (at your option) any later version.
  28  *
  29  * This program is distributed in the hope that it will be useful,
  30  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  31  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  32  * GNU General Public License for more details.
  33  *
  34  * You should have received a copy of the GNU General Public License
  35  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  36  */
  37 class DataSetCriteria extends BaseCriteria implements StoreableCriteria {
  38         /**
  39          * Table name
  40          */
  41         private $tableName = '';
  42
  43         /**
  44          * Unique key
  45          */
  46         private $uniqueKey = '';
  47
  48         /**
  49          * Primary key
  50          */
  51         private $primaryKey = '';
  52
  53         /**
  54          * Primary keys
  55          */
  56         private $primaryKeys = [];
  57
  58         /**
  59          * Search criteria instance
  60          */
  61         private $searchInstance = NULL;
  62
  63         /**
  64          * Protected constructor
  65          *
  66          * @return      void
  67          */
  68         private function __construct () {
  69                 // Call parent constructor
  70                 parent::__construct(__CLASS__);
  71         }
  72
  73         /**
  74          * Creates an instance of this criteria
  75          *
  76          * @param       $tableName                      Name of the table
  77          * @return      $criteriaInstance       An instance of this criteria
  78          * @throws      InvalidArgumentException        If a parameter is not valid
  79          */
  80         public static final function createDataSetCriteria (string $tableName) {
  81                 // Validate parameter
  82                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('DATA-SET-CRITERIA: tableName=%s - CALLED!', $tableName));
  83                 if (empty($tableName)) {
  84                         // Throw IAE
  85                         throw new InvalidArgumentException('Parameter "tableName" is empty', FrameworkInterface::EXCEPTION_INVALID_ARGUMENT);
  86                 }
  87
  88                 // Get a new instance
  89                 $criteriaInstance = new DataSetCriteria();
  90
  91                 // Set table name
  92                 $criteriaInstance->setTableName($tableName);
  93
  94                 // Return the instance
  95                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('DATA-SET-CRITERIA: criteriaInstance=%s - EXIT!', $criteriaInstance->__toString()));
  96                 return $criteriaInstance;
  97         }
  98
  99         /**
 100          * Setter for table name
 101          *
 102          * @param       $tableName      Name of the table to set
 103          * @return      void
 104          */
 105         public final function setTableName (string $tableName) {
 106                 $this->tableName = $tableName;
 107         }
 108
 109         /**
 110          * Getter for table name
 111          *
 112          * @return      $tableName      Name of the table to set
 113          */
 114         public final function getTableName () {
 115                 return $this->tableName;
 116         }
 117
 118         /**
 119          * Setter for unique key
 120          *
 121          * @param       $uniqueKey      Column to use as unique key
 122          * @return      void
 123          */
 124         public final function setUniqueKey (string $uniqueKey) {
 125                 $this->uniqueKey = $uniqueKey;
 126         }
 127
 128         /**
 129          * Getter for unique key
 130          *
 131          * @return      $uniqueKey      Column to use as unique key
 132          */
 133         public final function getUniqueKey () {
 134                 return $this->uniqueKey;
 135         }
 136
 137         /**
 138          * Setter for primary key
 139          *
 140          * @param       $primaryKey             Primary key to set
 141          * @return      void
 142          */
 143         public final function setPrimaryKey (string $primaryKey) {
 144                 $this->primaryKey = $primaryKey;
 145         }
 146
 147         /**
 148          * Setter for primary key array
 149          *
 150          * @param       $primaryKeys    Primary key array to set
 151          * @return      void
 152          */
 153         public function setPrimaryKeyCombined (array $primaryKeys) {
 154                 $this->primaryKeys = $primaryKeys;
 155         }
 156
 157         /**
 158          * Getter for primary keys
 159          *
 160          * @return      $primaryKeys    Primary key array
 161          */
 162         public final function getPrimaryKeys () {
 163                 // Return it
 164                 return $this->primaryKeys;
 165         }
 166
 167         /**
 168          * Setter for search instance
 169          *
 170          * @param       $searchInstance         Searchable criteria instance
 171          * @return      void
 172          */
 173         public final function setSearchInstance (LocalSearchCriteria $searchInstance) {
 174                 $this->searchInstance = $searchInstance;
 175         }
 176
 177         /**
 178          * Getter for search instance
 179          *
 180          * @return      $searchInstance         Searchable criteria instance
 181          */
 182         public final function getSearchInstance () {
 183                 return $this->searchInstance;
 184         }
 185
 186         /**
 187          * Getter for unique key value
 188          *
 189          * @return      $uniqueValue    Value of the unique key
 190          * @throws      BadMethodCallException  If no primary and no unique key was found
 191          */
 192         public final function getUniqueValue () {
 193                 // Get primary key(s) first
 194                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('DATA-SET-CRITERIA: CALLED!');
 195                 $primaryKey  = trim($this->getCriteriaElemnent($this->getPrimaryKey()));
 196                 $primaryKeys = $this->getPrimaryKeys();
 197
 198                 /*
 199                  * If this is not set, this could mean a badly written frontend as
 200                  * tables should always have a primary key.
 201                  */
 202                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('DATA-SET-CRITERIA: this->tableName=%s,primaryKey=%s,primaryKeys()=%d', $this->getTableName(), $primaryKey, count($primaryKeys)));
 203                 if (count($primaryKeys) > 0) {
 204                         /*
 205                          * Init return value, this can be put all together without any
 206                          * separator as it only aids as a "unique value" for generating the
 207                          * "row file name".
 208                          */
 209                         $return = '';
 210
 211                         // Combination set, so get all
 212                         foreach ($primaryKeys as $primaryKeyPart) {
 213                                 // Add it
 214                                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('DATA-SET-CRITERIA: primaryKeyPart=%s', $primaryKeyPart));
 215                                 $return .= trim($this->getCriteriaElemnent($primaryKeyPart));
 216                         }
 217
 218                         // Debug message
 219
 220                         // Return it
 221                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('DATA-SET-CRITERIA: return=%s - EXIT!', $return));
 222                         return $return;
 223                 } elseif (!empty($primaryKey)) {
 224                         // Return primary key
 225                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('DATA-SET-CRITERIA: primaryKey=%s - EXIT!', $primaryKey));
 226                         return $primaryKey;
 227                 } else {
 228                         // Issue a warning
 229                         self::createDebugInstance(__CLASS__, __LINE__)->warningMessage('DATA-SET-CRITERIA: Primary key not set for table ' . $this->getTableName() . ', please fix your table. Falling back to unique key ...');
 230
 231                         // Get unique key
 232                         $uniqueKey = trim($this->getCriteriaElemnent($this->getUniqueKey()));
 233
 234                         // Is it empty, too?
 235                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('DATA-SET-CRITERIA: uniqueKey=%s', $uniqueKey));
 236                         if (empty($uniqueKey)) {
 237                                 // Bad news, nothing is "unique" by design for this table
 238                                 throw new BadMethodCallException(sprintf('Table %s has both no primary and unique key, but %s was called. Please fix your table.', $this->getTableName(), __METHOD__), FrameworkInterface::EXCEPTION_BAD_METHOD_CALL);
 239                         }
 240
 241                         // Return unique key
 242                         //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('DATA-SET-CRITERIA: uniqueKey=%s - EXIT!', $uniqueKey));
 243                         return $uniqueKey;
 244                 }
 245         }
 246
 247         /**
 248          * Getter for primary key or unique key if not set
 249          *
 250          * @return      $primaryKey             Primary key or unique key if not set
 251          */
 252         public final function getPrimaryKey () {
 253                 // Get primary key by default
 254                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage('DATA-SET-CRITERIA: CALLED!');
 255                 $primaryKey = $this->primaryKey;
 256
 257                 // Is it still empty?
 258                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->debugMessage(sprintf('DATA-SET-CRITERIA: primaryKey=%s', $primaryKey));
 259                 if (empty($primaryKey)) {
 260                         // Get uniqueKey
 261                         $primaryKey = $this->getUniqueKey();
 262                 }
 263
 264                 // Return it
 265                 //* NOISY-DEBUG: */ self::createDebugInstance(__CLASS__, __LINE__)->traceMessage(sprintf('DATA-SET-CRITERIA: primaryKey=%s - EXIT!', $primaryKey));
 266                 return $primaryKey;
 267         }
 268
 269 }