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