[TASK] Add a set of interfaces for collection
authorSteffen Ritter <info@rs-websystems.de>
Tue, 29 Nov 2011 06:08:56 +0000 (07:08 +0100)
committerSteffen Ritter <info@rs-websystems.de>
Tue, 29 Nov 2011 08:21:33 +0000 (09:21 +0100)
The core currently lacks a common way of handling "sets of data"
in a generic way. This set of interfaces define these common way of
accessing data-sets within TYPO3.

Change-Id: I1d698a89f0add4cd4d1aaebc99fe0ed37dac333d
Resolves: #32146
Releases: 4.7
Reviewed-on: http://review.typo3.org/6967
Reviewed-by: Georg Ringer
Tested-by: Georg Ringer
Reviewed-by: Fabien Udriot
Tested-by: Fabien Udriot
Reviewed-by: Steffen Ritter
Tested-by: Steffen Ritter
t3lib/collection/interfaces/interface.t3lib_collection_collection.php [new file with mode: 0644]
t3lib/collection/interfaces/interface.t3lib_collection_editable.php [new file with mode: 0644]
t3lib/collection/interfaces/interface.t3lib_collection_nameable.php [new file with mode: 0644]
t3lib/collection/interfaces/interface.t3lib_collection_persistable.php [new file with mode: 0644]
t3lib/collection/interfaces/interface.t3lib_collection_recordcollection.php [new file with mode: 0644]
t3lib/collection/interfaces/interface.t3lib_collection_sortable.php [new file with mode: 0644]

diff --git a/t3lib/collection/interfaces/interface.t3lib_collection_collection.php b/t3lib/collection/interfaces/interface.t3lib_collection_collection.php
new file mode 100644 (file)
index 0000000..2513a67
--- /dev/null
@@ -0,0 +1,45 @@
+<?php
+/***************************************************************
+ *  Copyright notice
+ *
+ *  (c) 2011 Steffen Ritter <typo3steffen-ritter.net>
+ *  All rights reserved
+ *
+ *  This script is part of the TYPO3 project. The TYPO3 project is
+ *  free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  The GNU General Public License can be found at
+ *  http://www.gnu.org/copyleft/gpl.html.
+ *  A copy is found in the textfile GPL.txt and important notices to the license
+ *  from the author is found in LICENSE.txt distributed with these scripts.
+ *
+ *
+ *  This script is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  This copyright notice MUST APPEAR in all copies of the script!
+ ***************************************************************/
+
+
+/**
+ * Marker interface for collection classes
+ *
+ * Collections are containers-classes handling the storage
+ * of data values (f.e. strings, records, relations) in a
+ * common and generic way, while the class manages the storage
+ * in an appropiate way itself
+ *
+ * @author Steffen Ritter <typo3steffen-ritter.net>
+ * @package TYPO3
+ * @subpackage t3lib
+ */
+interface t3lib_collection_Collection extends Iterator, Serializable, Countable {
+
+}
+
+?>
\ No newline at end of file
diff --git a/t3lib/collection/interfaces/interface.t3lib_collection_editable.php b/t3lib/collection/interfaces/interface.t3lib_collection_editable.php
new file mode 100644 (file)
index 0000000..717bcb6
--- /dev/null
@@ -0,0 +1,78 @@
+<?php
+/***************************************************************
+ *  Copyright notice
+ *
+ *  (c) 2011 Steffen Ritter <typo3steffen-ritter.net>
+ *  All rights reserved
+ *
+ *  This script is part of the TYPO3 project. The TYPO3 project is
+ *  free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  The GNU General Public License can be found at
+ *  http://www.gnu.org/copyleft/gpl.html.
+ *  A copy is found in the textfile GPL.txt and important notices to the license
+ *  from the author is found in LICENSE.txt distributed with these scripts.
+ *
+ *
+ *  This script is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  This copyright notice MUST APPEAR in all copies of the script!
+ ***************************************************************/
+
+
+/**
+ * Interface for collection classes which es enabled to be modified
+ *
+ * @author Steffen Ritter <typo3steffen-ritter.net>
+ * @package TYPO3
+ * @subpackage t3lib
+ */
+interface t3lib_collection_Editable {
+
+       /**
+        * Adds on entry to the collection
+        *
+        * @abstract
+        * @param mixed $data
+        * @return void
+        */
+       public function add($data);
+
+       /**
+        * Adds a set of entries to the collection
+        *
+        * @abstract
+        * @param t3lib_collection_Collection $other
+        * @return void
+        */
+       public function addAll(t3lib_collection_Collection $other);
+
+       /**
+        * Remove the given entry from collection
+        *
+        * Note: not the given "index"
+        *
+        * @abstract
+        * @param mixed $data
+        * @return void
+        */
+       public function remove($data);
+
+       /**
+        * Removes all entries from the collection
+        *
+        * collection will be empty afterwards
+        *
+        * @abstract
+        * @return void
+        */
+       public function removeAll();
+}
+
+?>
\ No newline at end of file
diff --git a/t3lib/collection/interfaces/interface.t3lib_collection_nameable.php b/t3lib/collection/interfaces/interface.t3lib_collection_nameable.php
new file mode 100644 (file)
index 0000000..6ff82a6
--- /dev/null
@@ -0,0 +1,79 @@
+<?php
+/***************************************************************
+ *  Copyright notice
+ *
+ *  (c) 2011 Steffen Ritter <typo3steffen-ritter.net>
+ *  All rights reserved
+ *
+ *  This script is part of the TYPO3 project. The TYPO3 project is
+ *  free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  The GNU General Public License can be found at
+ *  http://www.gnu.org/copyleft/gpl.html.
+ *  A copy is found in the textfile GPL.txt and important notices to the license
+ *  from the author is found in LICENSE.txt distributed with these scripts.
+ *
+ *
+ *  This script is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  This copyright notice MUST APPEAR in all copies of the script!
+ ***************************************************************/
+
+
+/**
+ * Marker interface for a collection class with title and description
+ *
+ * Collections might be used internally as well as being shown
+ * With the nameable interface a title and a description are added
+ * to an collection, allowing every collection implementing Nameable
+ * being display by the same logic.
+ *
+ * @author Steffen Ritter <typo3steffen-ritter.net>
+ * @package TYPO3
+ * @subpackage t3lib
+ */
+interface t3lib_collection_Nameable {
+
+       /**
+        * Setter for the title
+        *
+        * @abstract
+        * @param string $title
+        * @return void
+        */
+       public function setTitle($title);
+
+       /**
+        * Setter for the description
+        *
+        * @abstract
+        * @param string $description
+        * @return void
+        */
+       public function setDescription($description);
+
+       /**
+        * Getter for the title
+        *
+        * @abstract
+        * @return string
+        */
+       public function getTitle();
+
+       /**
+        * Getter for the description
+        *
+        * @abstract
+        * @return void
+        */
+       public function getDescription();
+
+}
+
+?>
\ No newline at end of file
diff --git a/t3lib/collection/interfaces/interface.t3lib_collection_persistable.php b/t3lib/collection/interfaces/interface.t3lib_collection_persistable.php
new file mode 100644 (file)
index 0000000..24d05a2
--- /dev/null
@@ -0,0 +1,103 @@
+<?php
+/***************************************************************
+ *  Copyright notice
+ *
+ *  (c) 2011 Steffen Ritter <typo3steffen-ritter.net>
+ *  All rights reserved
+ *
+ *  This script is part of the TYPO3 project. The TYPO3 project is
+ *  free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  The GNU General Public License can be found at
+ *  http://www.gnu.org/copyleft/gpl.html.
+ *  A copy is found in the textfile GPL.txt and important notices to the license
+ *  from the author is found in LICENSE.txt distributed with these scripts.
+ *
+ *
+ *  This script is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  This copyright notice MUST APPEAR in all copies of the script!
+ ***************************************************************/
+
+
+/**
+ * Interface for collection class being persistable
+ *
+ * Collections are containers-classes handling the storage
+ * of data values (f.e. strings, records, relations) in a
+ * common and generic way, while the class manages the storage
+ * in an appropiate way itself
+ *
+ * @author Steffen Ritter <typo3steffen-ritter.net>
+ * @package TYPO3
+ * @subpackage t3lib
+ */
+interface t3lib_collection_Persistable {
+
+       /**
+        * Get the identifier of the collection
+        *
+        * For database stored collections, this will be a integer,
+        * session stored, registry stored or other collections might
+        * use a string as well
+        *
+        * @abstract
+        * @return int|string
+        */
+       public function getIdentifier();
+
+       /**
+        * Sets the identifier of the collection
+        *
+        * @abstract
+        * @param int|string $id
+        * @return void
+        */
+       public function setIdentifier($id);
+
+       /**
+        * Loads the collections with the given id from persistence
+        *
+        * For memory reasons, per default only f.e. title, database-table,
+        * identifier (what ever static data is defined) is loaded.
+        * Entries can be load on first access.
+        *
+        * @static
+        * @abstract
+        * @param int|string $id
+        * @param boolean $fillItems Populates the entries directly on load, might be bad for memory on large collections
+        * @return t3lib_collection_Collection
+        */
+       public static function load($id, $fillItems = FALSE);
+
+       /**
+        * Persists current collection state to underlying storage
+        *
+        * @abstract
+        * @return void
+        */
+       public function persist();
+
+       /**
+        * Populates the content-entries of the storage
+        *
+        * Queries the underlying storage for entries of the collection
+        * and adds them to the collection data.
+        *
+        * If the content entries of the storage had not been loaded on creation
+        * ($fillItems = false) this function is to be used for loading the contents
+        * afterwards.
+        *
+        * @abstract
+        * @return void
+        */
+       public function loadContents();
+}
+
+?>
\ No newline at end of file
diff --git a/t3lib/collection/interfaces/interface.t3lib_collection_recordcollection.php b/t3lib/collection/interfaces/interface.t3lib_collection_recordcollection.php
new file mode 100644 (file)
index 0000000..efd1fc3
--- /dev/null
@@ -0,0 +1,57 @@
+<?php
+/***************************************************************
+ *  Copyright notice
+ *
+ *  (c) 2011 Steffen Ritter <typo3steffen-ritter.net>
+ *  All rights reserved
+ *
+ *  This script is part of the TYPO3 project. The TYPO3 project is
+ *  free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  The GNU General Public License can be found at
+ *  http://www.gnu.org/copyleft/gpl.html.
+ *  A copy is found in the textfile GPL.txt and important notices to the license
+ *  from the author is found in LICENSE.txt distributed with these scripts.
+ *
+ *
+ *  This script is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  This copyright notice MUST APPEAR in all copies of the script!
+ ***************************************************************/
+
+
+/**
+ * Collection for handling records from a single database-table.
+ *
+ * @author Steffen Ritter <typo3steffen-ritter.net>
+ * @package TYPO3
+ * @subpackage t3lib
+ */
+interface t3lib_collection_RecordCollection extends t3lib_collection_Collection, t3lib_collection_Nameable {
+
+       /**
+        * Setter for the name of the data-source table
+        *
+        * @abstract
+        * @param string $tableName
+        * @return void
+        */
+       public function setItemTableName($tableName);
+
+       /**
+        * Setter for the name of the data-source table
+        *
+        * @abstract
+        * @return string
+        */
+       public function getItemTableName();
+
+}
+
+?>
\ No newline at end of file
diff --git a/t3lib/collection/interfaces/interface.t3lib_collection_sortable.php b/t3lib/collection/interfaces/interface.t3lib_collection_sortable.php
new file mode 100644 (file)
index 0000000..e026762
--- /dev/null
@@ -0,0 +1,71 @@
+<?php
+/***************************************************************
+ *  Copyright notice
+ *
+ *  (c) 2011 Steffen Ritter <typo3steffen-ritter.net>
+ *  All rights reserved
+ *
+ *  This script is part of the TYPO3 project. The TYPO3 project is
+ *  free software; you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation; either version 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  The GNU General Public License can be found at
+ *  http://www.gnu.org/copyleft/gpl.html.
+ *  A copy is found in the textfile GPL.txt and important notices to the license
+ *  from the author is found in LICENSE.txt distributed with these scripts.
+ *
+ *
+ *  This script is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  This copyright notice MUST APPEAR in all copies of the script!
+ ***************************************************************/
+
+
+/**
+ * Interface for collection class being sortable
+ *
+ * This interface allows you to either define a callback implementing
+ * your own sorting method and explicitly move an item from one position
+ * to another.
+ *
+ * This assumes that entries are sortable and therefore a index can be assigned
+ *
+ * @author Steffen Ritter <typo3steffen-ritter.net>
+ * @package TYPO3
+ * @subpackage t3lib
+ */
+interface t3lib_collection_Sortable {
+
+       /**
+        * Sorts collection via given callBackFunction
+        *
+        * The comparison function given as must return an integer less than, equal to, or greater than
+        * zero if the first argument is considered to be respectively less than, equal to, or greater than the second.
+        *
+        * @abstract
+        * @param $callbackFunction
+        * @see http://www.php.net/manual/en/function.usort.php
+        * @return void
+        */
+       public function usort($callbackFunction);
+
+       /**
+        * Moves the item within the collection
+        *
+        * The item at $currentPosition will be moved to
+        * $newPosition. Ommiting $newPosition will move to top.
+        *
+        * @abstract
+        * @param int $currentPosition
+        * @param int $newPosition
+        * @return void
+        */
+       public function moveItemAt($currentPosition, $newPosition = 0);
+}
+
+?>
\ No newline at end of file