add icommentsmanger and icomment implementation

register CommentsManager service, allow override, document in config.sample.php

don't insert autoincrement ids in tests, because of dislikes from oracle and pgsql

specify timezone in null date

only accepts strings for ID parameter that can be converted to int

replace forgotten hardcoded IDs in tests

react on deleted users

react on file deletion

Postgresql compatibility

lastInsertId needs *PREFIX* with the table name

do not listen for file deletion, because it is not reliable (trashbin, external storages)

add runtime cache for comments

3 files changed, 57 insertions, 6 deletions

diff --git a/lib/public/comments/icomment.php b/lib/public/comments/icomment.php
index c8f407624a0..8cfc504fc3f 100644
--- a/lib/public/comments/icomment.php
+++ b/lib/public/comments/icomment.php
@@ -49,7 +49,6 @@ interface IComment {
 
 	/**
 	 * sets the parent ID and returns itself
-	 *
 	 * @param string $parentId
 	 * @return IComment
 	 * @since 9.0.0
@@ -57,6 +56,24 @@ interface IComment {
 	public function setParentId($parentId);
 
 	/**
+	 * returns the topmost parent ID of the comment
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getTopmostParentId();
+
+
+	/**
+	 * sets the topmost parent ID and returns itself
+	 *
+	 * @param string $id
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setTopmostParentId($id);
+
+	/**
 	 * returns the number of children
 	 *
 	 * @return int
diff --git a/lib/public/comments/icommentsmanager.php b/lib/public/comments/icommentsmanager.php
index ebf7a34bf27..f6883224d60 100644
--- a/lib/public/comments/icommentsmanager.php
+++ b/lib/public/comments/icommentsmanager.php
@@ -13,6 +13,17 @@ namespace OCP\Comments;
 interface ICommentsManager {
 
 	/**
+	 * @const DELETED_USER type and id for a user that has been deleted
+	 * @see deleteReferencesOfActor
+	 * @since 9.0.0
+	 *
+	 * To be used as replacement for user type actors in deleteReferencesOfActor().
+	 *
+	 * User interfaces shall show "Deleted user" as display name, if needed.
+	 */
+	const DELETED_USER = 'deleted_user';
+
+	/**
 	 * returns a comment instance
 	 *
 	 * @param string $id the ID of the comment
@@ -28,7 +39,7 @@ interface ICommentsManager {
 	 * @param string $id
 	 * @param int $limit max number of entries to return, 0 returns all
 	 * @param int $offset the start entry
-	 * @return []
+	 * @return array
 	 * @since 9.0.0
 	 *
 	 * The return array looks like this
@@ -73,7 +84,6 @@ interface ICommentsManager {
 	 * @param \DateTime $notOlderThan optional, timestamp of the oldest comments
 	 * that may be returned
 	 * @return IComment[]
-	 * @throws NotFoundException in case the requested type or id is not present
 	 * @since 9.0.0
 	 */
 	public function getForObject(
@@ -88,7 +98,6 @@ interface ICommentsManager {
 	 * @param $objectType string the object type, e.g. 'files'
 	 * @param $objectId string the id of the object
 	 * @return Int
-	 * @throws NotFoundException in case the requested type or id is not present
 	 * @since 9.0.0
 	 */
 	public function getNumberOfCommentsForObject($objectType, $objectId);
@@ -130,17 +139,20 @@ interface ICommentsManager {
 	 * Throws NotFoundException when a comment that is to be updated does not
 	 * exist anymore at this point of time.
 	 *
-	 * @param IComment
+	 * @param IComment &$comment
 	 * @return bool
 	 * @throws NotFoundException
 	 * @since 9.0.0
 	 */
-	public function save(&$comment);
+	public function save(IComment &$comment);
 
 	/**
 	 * removes references to specific actor (e.g. on user delete) of a comment.
 	 * The comment itself must not get lost/deleted.
 	 *
+	 * A 'user' type actor (type and id) should get replaced by the
+	 * value of the DELETED_USER constant of this interface.
+	 *
 	 * @param string $actorType the actor type (e.g. 'user')
 	 * @param string $actorId a user id
 	 * @return boolean
diff --git a/lib/public/comments/icommentsmanagerfactory.php b/lib/public/comments/icommentsmanagerfactory.php
new file mode 100644
index 00000000000..7bfb79aae00
--- /dev/null
+++ b/lib/public/comments/icommentsmanagerfactory.php
@@ -0,0 +1,22 @@
+<?php
+
+namespace OCP\Comments;
+
+/**
+ * Interface IComment
+ *
+ * This class represents a comment and offers methods for modification.
+ *
+ * @package OCP\Comments
+ * @since 9.0.0
+ */
+interface ICommentsManagerFactory {
+
+	/**
+	 * creates and returns an instance of the ICommentsManager
+	 *
+	 * @return ICommentsManager
+	 * @since 9.0.0
+	 */
+	public function getManager();
+}