From d43abd0b8fcdad74a7a95936d919fb206534f0dc Mon Sep 17 00:00:00 2001
From: Arthur Schiwon <blizzz@owncloud.com>
Date: Tue, 10 Nov 2015 17:44:26 +0100
Subject: [PATCH 1/4] public interfaces for Comments

---
 lib/public/comments/icomment.php              | 181 ++++++++++++++++++
 lib/public/comments/icommentsmanager.php      | 161 ++++++++++++++++
 .../comments/illegalidchangeexception.php     |   9 +
 lib/public/comments/notfoundexception.php     |   9 +
 4 files changed, 360 insertions(+)
 create mode 100644 lib/public/comments/icomment.php
 create mode 100644 lib/public/comments/icommentsmanager.php
 create mode 100644 lib/public/comments/illegalidchangeexception.php
 create mode 100644 lib/public/comments/notfoundexception.php

diff --git a/lib/public/comments/icomment.php b/lib/public/comments/icomment.php
new file mode 100644
index 0000000000..34adf5983f
--- /dev/null
+++ b/lib/public/comments/icomment.php
@@ -0,0 +1,181 @@
+<?php
+
+namespace OCP\Comments;
+
+/**
+ * Interface IComment
+ *
+ * This class represents a comment and offers methods for modification.
+ *
+ * @package OCP\Comments
+ * @since 9.0.0
+ */
+interface IComment {
+
+	/**
+	 * returns the ID of the comment
+	 *
+	 * It may return an empty string, if the comment was not stored.
+	 * It is expected that the concrete Comment implementation gives an ID
+	 * by itself (e.g. after saving).
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getId();
+
+	/**
+	 * sets the ID of the comment and returns itself
+	 *
+	 * It is only allowed to set the ID only, if the current id is an empty
+	 * string (which means it is not stored in a database, storage or whatever
+	 * the concrete implementation does), or vice versa. Changing a given ID is
+	 * not permitted and must result in an IllegalIDChangeException.
+	 *
+	 * @param string $id
+	 * @return IComment
+	 * @throws IllegalIDChangeException
+	 * @since 9.0.0
+	 */
+	public function setId($id);
+
+	/**
+	 * returns the parent ID of the comment
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getParentId();
+
+	/**
+	 * sets the parent ID and returns itself
+	 *
+	 * @param string $parentId
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setParentId($parentId);
+
+	/**
+	 * returns the number of children
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getChildrenCount();
+
+	/**
+	 * returns the message of the comment
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getMessage();
+
+	/**
+	 * sets the message of the comment and returns itself
+	 *
+	 * @param string $message
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setMessage($message);
+
+	/**
+	 * returns the verb of the comment
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getVerb();
+
+	/**
+	 * sets the verb of the comment, e.g. 'comment' or 'like'
+	 *
+	 * @param string $verb
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setVerb($verb);
+
+	/**
+	 * returns the actor type
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getActorType();
+
+	/**
+	 * returns the actor ID
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getActorId();
+
+	/**
+	 * sets (overwrites) the actor type and id
+	 *
+	 * @param string $actorType e.g. 'user'
+	 * @param string $actorId e.g. 'zombie234'
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setActor($actorType, $actorId);
+
+	/**
+	 * returns the unix timestamp of the comment.
+	 *
+	 * If not explicitely set, it shall default to the time of initialization.
+	 *
+	 * @return \DateTime
+	 * @since 9.0.0
+	 */
+	public function getTimestamp();
+
+	/**
+	 * sets the timestamp of the comment and returns itself
+	 *
+	 * @param \DateTime $timestamp
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setTimestamp(\DateTime $timestamp);
+
+	/**
+	 * returns the timestamp of the most recent child
+	 *
+	 * @return int
+	 * @since 9.0.0
+	 */
+	public function getLatestChildTimestamp();
+
+	/**
+	 * returns the object type the comment is attached to
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getObjectType();
+
+	/**
+	 * returns the object id the comment is attached to
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getObjectId();
+
+	/**
+	 * sets (overwrites) the object of the comment
+	 *
+	 * @param string $objectType e.g. 'file'
+	 * @param string $objectId e.g. '16435'
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setObject($objectType, $objectId);
+
+}
+
diff --git a/lib/public/comments/icommentsmanager.php b/lib/public/comments/icommentsmanager.php
new file mode 100644
index 0000000000..ebf7a34bf2
--- /dev/null
+++ b/lib/public/comments/icommentsmanager.php
@@ -0,0 +1,161 @@
+<?php
+
+namespace OCP\Comments;
+
+/**
+ * Interface ICommentsManager
+ *
+ * This class manages the access to comments
+ *
+ * @package OCP\Comments
+ * @since 9.0.0
+ */
+interface ICommentsManager {
+
+	/**
+	 * returns a comment instance
+	 *
+	 * @param string $id the ID of the comment
+	 * @return IComment
+	 * @throws NotFoundException
+	 * @since 9.0.0
+	 */
+	public function get($id);
+
+	/**
+	 * returns the comment specified by the id and all it's child comments
+	 *
+	 * @param string $id
+	 * @param int $limit max number of entries to return, 0 returns all
+	 * @param int $offset the start entry
+	 * @return []
+	 * @since 9.0.0
+	 *
+	 * The return array looks like this
+	 * [
+	 * 	 'comment' => IComment, // root comment
+	 *   'replies' =>
+	 *   [
+	 *     0 =>
+	 *     [
+	 *       'comment' => IComment,
+	 *       'replies' =>
+	 *       [
+	 *         0 =>
+	 *         [
+	 *           'comment' => IComment,
+	 *           'replies' => [ … ]
+	 *         ],
+	 *         …
+	 *       ]
+	 *     ]
+	 *     1 =>
+	 *     [
+	 *       'comment' => IComment,
+	 *       'replies'=> [ … ]
+	 *     ],
+	 *     …
+	 *   ]
+	 * ]
+	 */
+	public function getTree($id, $limit = 0, $offset = 0);
+
+	/**
+	 * returns comments for a specific object (e.g. a file).
+	 *
+	 * The sort order is always newest to oldest.
+	 *
+	 * @param string $objectType the object type, e.g. 'files'
+	 * @param string $objectId the id of the object
+	 * @param int $limit optional, number of maximum comments to be returned. if
+	 * not specified, all comments are returned.
+	 * @param int $offset optional, starting point
+	 * @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(
+			$objectType,
+			$objectId,
+			$limit = 0,
+			$offset = 0,
+			\DateTime $notOlderThan = null
+	);
+
+	/**
+	 * @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);
+
+	/**
+	 * creates a new comment and returns it. At this point of time, it is not
+	 * saved in the used data storage. Use save() after setting other fields
+	 * of the comment (e.g. message or verb).
+	 *
+	 * @param string $actorType the actor type (e.g. 'user')
+	 * @param string $actorId a user id
+	 * @param string $objectType the object type the comment is attached to
+	 * @param string $objectId the object id the comment is attached to
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function create($actorType, $actorId, $objectType, $objectId);
+
+	/**
+	 * permanently deletes the comment specified by the ID
+	 *
+	 * When the comment has child comments, their parent ID will be changed to
+	 * the parent ID of the item that is to be deleted.
+	 *
+	 * @param string $id
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function delete($id);
+
+	/**
+	 * saves the comment permanently and returns it
+	 *
+	 * if the supplied comment has an empty ID, a new entry comment will be
+	 * saved and the instance updated with the new ID.
+	 *
+	 * Otherwise, an existing comment will be updated.
+	 *
+	 * Throws NotFoundException when a comment that is to be updated does not
+	 * exist anymore at this point of time.
+	 *
+	 * @param IComment
+	 * @return bool
+	 * @throws NotFoundException
+	 * @since 9.0.0
+	 */
+	public function save(&$comment);
+
+	/**
+	 * removes references to specific actor (e.g. on user delete) of a comment.
+	 * The comment itself must not get lost/deleted.
+	 *
+	 * @param string $actorType the actor type (e.g. 'user')
+	 * @param string $actorId a user id
+	 * @return boolean
+	 * @since 9.0.0
+	 */
+	public function deleteReferencesOfActor($actorType, $actorId);
+
+	/**
+	 * deletes all comments made of a specific object (e.g. on file delete)
+	 *
+	 * @param string $objectType the object type (e.g. 'file')
+	 * @param string $objectId e.g. the file id
+	 * @return boolean
+	 * @since 9.0.0
+	 */
+	public function deleteCommentsAtObject($objectType, $objectId);
+
+}
diff --git a/lib/public/comments/illegalidchangeexception.php b/lib/public/comments/illegalidchangeexception.php
new file mode 100644
index 0000000000..8bce3cf2f8
--- /dev/null
+++ b/lib/public/comments/illegalidchangeexception.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace OCP\Comments;
+
+/**
+ * Exception for not found entity
+ * @since 9.0.0
+ */
+class IllegalIDChangeException extends \Exception {}
diff --git a/lib/public/comments/notfoundexception.php b/lib/public/comments/notfoundexception.php
new file mode 100644
index 0000000000..a82e703b79
--- /dev/null
+++ b/lib/public/comments/notfoundexception.php
@@ -0,0 +1,9 @@
+<?php
+
+namespace OCP\Comments;
+
+/**
+ * Exception for not found entity
+ * @since 9.0.0
+ */
+class NotFoundException extends \Exception {}

From 4005c0337b41c222cbc94ba4f7a34e8da61a38d0 Mon Sep 17 00:00:00 2001
From: Arthur Schiwon <blizzz@owncloud.com>
Date: Mon, 23 Nov 2015 17:29:44 +0100
Subject: [PATCH 2/4] give creation datetime setter and getter a more
 meaningful and less misleading name

---
 lib/public/comments/icomment.php | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/lib/public/comments/icomment.php b/lib/public/comments/icomment.php
index 34adf5983f..3bc15c800f 100644
--- a/lib/public/comments/icomment.php
+++ b/lib/public/comments/icomment.php
@@ -125,23 +125,23 @@ interface IComment {
 	public function setActor($actorType, $actorId);
 
 	/**
-	 * returns the unix timestamp of the comment.
+	 * returns the creation date of the comment.
 	 *
-	 * If not explicitely set, it shall default to the time of initialization.
+	 * If not explicitly set, it shall default to the time of initialization.
 	 *
 	 * @return \DateTime
 	 * @since 9.0.0
 	 */
-	public function getTimestamp();
+	public function getCreationDateTime();
 
 	/**
-	 * sets the timestamp of the comment and returns itself
+	 * sets the creation date of the comment and returns itself
 	 *
 	 * @param \DateTime $timestamp
 	 * @return IComment
 	 * @since 9.0.0
 	 */
-	public function setTimestamp(\DateTime $timestamp);
+	public function setCreationDateTime(\DateTime $timestamp);
 
 	/**
 	 * returns the timestamp of the most recent child

From ab8937ba6ab28048d667dc6aa34a7ba1b1bd6bd9 Mon Sep 17 00:00:00 2001
From: Arthur Schiwon <blizzz@owncloud.com>
Date: Mon, 23 Nov 2015 23:58:22 +0100
Subject: [PATCH 3/4] =?UTF-8?q?missing=20setters=20for=20setChildrenCount?=
 =?UTF-8?q?=20and=20setLatestChildDateTime=20(formerly=20=E2=80=A6Timestam?=
 =?UTF-8?q?p)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 lib/public/comments/icomment.php | 28 +++++++++++++++++++++++-----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/lib/public/comments/icomment.php b/lib/public/comments/icomment.php
index 3bc15c800f..c8f407624a 100644
--- a/lib/public/comments/icomment.php
+++ b/lib/public/comments/icomment.php
@@ -64,6 +64,15 @@ interface IComment {
 	 */
 	public function getChildrenCount();
 
+	/**
+	 * sets the number of children
+	 *
+	 * @param int $count
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setChildrenCount($count);
+
 	/**
 	 * returns the message of the comment
 	 *
@@ -137,19 +146,28 @@ interface IComment {
 	/**
 	 * sets the creation date of the comment and returns itself
 	 *
-	 * @param \DateTime $timestamp
+	 * @param \DateTime $dateTime
 	 * @return IComment
 	 * @since 9.0.0
 	 */
-	public function setCreationDateTime(\DateTime $timestamp);
+	public function setCreationDateTime(\DateTime $dateTime);
 
 	/**
-	 * returns the timestamp of the most recent child
+	 * returns the date of the most recent child
 	 *
-	 * @return int
+	 * @return \DateTime
 	 * @since 9.0.0
 	 */
-	public function getLatestChildTimestamp();
+	public function getLatestChildDateTime();
+
+	/**
+	 * sets the date of the most recent child
+	 *
+	 * @param \DateTime $dateTime
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setLatestChildDateTime(\DateTime $dateTime);
 
 	/**
 	 * returns the object type the comment is attached to

From d660c6162fdca619e98a5096f660a3998853171f Mon Sep 17 00:00:00 2001
From: Arthur Schiwon <blizzz@owncloud.com>
Date: Thu, 26 Nov 2015 12:15:00 +0100
Subject: [PATCH 4/4] proper description for IllegalIDChangeException

---
 lib/public/comments/illegalidchangeexception.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/public/comments/illegalidchangeexception.php b/lib/public/comments/illegalidchangeexception.php
index 8bce3cf2f8..4e13ef6e44 100644
--- a/lib/public/comments/illegalidchangeexception.php
+++ b/lib/public/comments/illegalidchangeexception.php
@@ -3,7 +3,7 @@
 namespace OCP\Comments;
 
 /**
- * Exception for not found entity
+ * Exception for illegal attempts to modify a comment ID
  * @since 9.0.0
  */
 class IllegalIDChangeException extends \Exception {}