public interfaces for Comments

4 files changed, 360 insertions, 0 deletions

diff --git a/lib/public/comments/icomment.php b/lib/public/comments/icomment.php
new file mode 100644
index 00000000000..34adf5983fa
--- /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 00000000000..ebf7a34bf27
--- /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 00000000000..8bce3cf2f89
--- /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 00000000000..a82e703b79e
--- /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 {}