Move \OCP\Comments to PSR-4 (#24565)

7 files changed, 685 insertions, 0 deletions

diff --git a/lib/public/Comments/CommentsEvent.php b/lib/public/Comments/CommentsEvent.php
new file mode 100644
index 00000000000..3101c4e6c50
--- /dev/null
+++ b/lib/public/Comments/CommentsEvent.php
@@ -0,0 +1,70 @@
+<?php
+/**
+ * @author Joas Schilling <nickvergessen@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+
+namespace OCP\Comments;
+
+use Symfony\Component\EventDispatcher\Event;
+
+/**
+ * Class CommentsEvent
+ *
+ * @package OCP\Comments
+ * @since 9.0.0
+ */
+class CommentsEvent extends Event {
+
+	const EVENT_ADD = 'OCP\Comments\ICommentsManager::addComment';
+	const EVENT_UPDATE = 'OCP\Comments\ICommentsManager::updateComment';
+	const EVENT_DELETE = 'OCP\Comments\ICommentsManager::deleteComment';
+
+	/** @var string */
+	protected $event;
+	/** @var IComment */
+	protected $comment;
+
+	/**
+	 * DispatcherEvent constructor.
+	 *
+	 * @param string $event
+	 * @param IComment $comment
+	 * @since 9.0.0
+	 */
+	public function __construct($event, IComment $comment) {
+		$this->event = $event;
+		$this->comment = $comment;
+	}
+
+	/**
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getEvent() {
+		return $this->event;
+	}
+
+	/**
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function getComment() {
+		return $this->comment;
+	}
+}
diff --git a/lib/public/Comments/IComment.php b/lib/public/Comments/IComment.php
new file mode 100644
index 00000000000..23580923058
--- /dev/null
+++ b/lib/public/Comments/IComment.php
@@ -0,0 +1,240 @@
+<?php
+/**
+ * @author Arthur Schiwon <blizzz@owncloud.com>
+ * @author Thomas Müller <thomas.mueller@tmit.eu>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+namespace OCP\Comments;
+
+/**
+ * Interface IComment
+ *
+ * This class represents a comment
+ *
+ * @package OCP\Comments
+ * @since 9.0.0
+ */
+interface IComment {
+	const MAX_MESSAGE_LENGTH = 1000;
+
+	/**
+	 * 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 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
+	 * @since 9.0.0
+	 */
+	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
+	 *
+	 * @return string
+	 * @since 9.0.0
+	 */
+	public function getMessage();
+
+	/**
+	 * sets the message of the comment and returns itself
+	 *
+	 * When the given message length exceeds MAX_MESSAGE_LENGTH an
+	 * MessageTooLongException shall be thrown.
+	 *
+	 * @param string $message
+	 * @return IComment
+	 * @throws MessageTooLongException
+	 * @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. 'users'
+	 * @param string $actorId e.g. 'zombie234'
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setActor($actorType, $actorId);
+
+	/**
+	 * returns the creation date of the comment.
+	 *
+	 * If not explicitly set, it shall default to the time of initialization.
+	 *
+	 * @return \DateTime
+	 * @since 9.0.0
+	 */
+	public function getCreationDateTime();
+
+	/**
+	 * sets the creation date of the comment and returns itself
+	 *
+	 * @param \DateTime $dateTime
+	 * @return IComment
+	 * @since 9.0.0
+	 */
+	public function setCreationDateTime(\DateTime $dateTime);
+
+	/**
+	 * returns the date of the most recent child
+	 *
+	 * @return \DateTime
+	 * @since 9.0.0
+	 */
+	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
+	 *
+	 * @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. 'files'
+	 * @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..cdc74282243
--- /dev/null
+++ b/lib/public/Comments/ICommentsManager.php
@@ -0,0 +1,239 @@
+<?php
+/**
+ * @author Arthur Schiwon <blizzz@owncloud.com>
+ * @author Joas Schilling <nickvergessen@owncloud.com>
+ * @author Thomas Müller <thomas.mueller@tmit.eu>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+namespace OCP\Comments;
+
+/**
+ * Interface ICommentsManager
+ *
+ * This class manages the access to comments
+ *
+ * @package OCP\Comments
+ * @since 9.0.0
+ */
+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_users';
+
+	/**
+	 * 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 array
+	 * @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[]
+	 * @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
+	 * @param \DateTime $notOlderThan optional, timestamp of the oldest comments
+	 * that may be returned
+	 * @return Int
+	 * @since 9.0.0
+	 */
+	public function getNumberOfCommentsForObject($objectType, $objectId, \DateTime $notOlderThan = null);
+
+	/**
+	 * 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. 'users')
+	 * @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
+	 *
+	 * 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 $comment
+	 * @return bool
+	 * @throws NotFoundException
+	 * @since 9.0.0
+	 */
+	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 'users' 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. 'users')
+	 * @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. 'files')
+	 * @param string $objectId e.g. the file id
+	 * @return boolean
+	 * @since 9.0.0
+	 */
+	public function deleteCommentsAtObject($objectType, $objectId);
+
+	/**
+	 * sets the read marker for a given file to the specified date for the
+	 * provided user
+	 *
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param \DateTime $dateTime
+	 * @param \OCP\IUser $user
+	 * @since 9.0.0
+	 */
+	public function setReadMark($objectType, $objectId, \DateTime $dateTime, \OCP\IUser $user);
+
+	/**
+	 * returns the read marker for a given file to the specified date for the
+	 * provided user. It returns null, when the marker is not present, i.e.
+	 * no comments were marked as read.
+	 *
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @param \OCP\IUser $user
+	 * @return \DateTime|null
+	 * @since 9.0.0
+	 */
+	public function getReadMark($objectType, $objectId, \OCP\IUser $user);
+
+	/**
+	 * deletes the read markers for the specified user
+	 *
+	 * @param \OCP\IUser $user
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function deleteReadMarksFromUser(\OCP\IUser $user);
+
+	/**
+	 * deletes the read markers on the specified object
+	 *
+	 * @param string $objectType
+	 * @param string $objectId
+	 * @return bool
+	 * @since 9.0.0
+	 */
+	public function deleteReadMarksOnObject($objectType, $objectId);
+
+}
diff --git a/lib/public/Comments/ICommentsManagerFactory.php b/lib/public/Comments/ICommentsManagerFactory.php
new file mode 100644
index 00000000000..6d814104ae1
--- /dev/null
+++ b/lib/public/Comments/ICommentsManagerFactory.php
@@ -0,0 +1,53 @@
+<?php
+/**
+ * @author Arthur Schiwon <blizzz@owncloud.com>
+ * @author Thomas Müller <thomas.mueller@tmit.eu>
+ * @author Vincent Petry <pvince81@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+namespace OCP\Comments;
+
+use OCP\IServerContainer;
+
+/**
+ * Interface ICommentsManagerFactory
+ *
+ * This class is responsible for instantiating and returning an ICommentsManager
+ * instance.
+ *
+ * @package OCP\Comments
+ * @since 9.0.0
+ */
+interface ICommentsManagerFactory {
+
+	/**
+	 * Constructor for the comments manager factory
+	 *
+	 * @param IServerContainer $serverContainer server container
+	 * @since 9.0.0
+	 */
+	public function __construct(IServerContainer $serverContainer);
+
+	/**
+	 * creates and returns an instance of the ICommentsManager
+	 *
+	 * @return ICommentsManager
+	 * @since 9.0.0
+	 */
+	public function getManager();
+}
diff --git a/lib/public/Comments/IllegalIDChangeException.php b/lib/public/Comments/IllegalIDChangeException.php
new file mode 100644
index 00000000000..056113bdb3f
--- /dev/null
+++ b/lib/public/Comments/IllegalIDChangeException.php
@@ -0,0 +1,28 @@
+<?php
+/**
+ * @author Arthur Schiwon <blizzz@owncloud.com>
+ * @author Thomas Müller <thomas.mueller@tmit.eu>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+namespace OCP\Comments;
+
+/**
+ * Exception for illegal attempts to modify a comment ID
+ * @since 9.0.0
+ */
+class IllegalIDChangeException extends \Exception {}
diff --git a/lib/public/Comments/MessageTooLongException.php b/lib/public/Comments/MessageTooLongException.php
new file mode 100644
index 00000000000..054cecf320f
--- /dev/null
+++ b/lib/public/Comments/MessageTooLongException.php
@@ -0,0 +1,27 @@
+<?php
+/**
+ * @author Arthur Schiwon <blizzz@owncloud.com>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+namespace OCP\Comments;
+
+/**
+ * Exception thrown when a comment message exceeds the allowed character limit
+ * @since 9.0.0
+ */
+class MessageTooLongException extends \OverflowException {}
diff --git a/lib/public/Comments/NotFoundException.php b/lib/public/Comments/NotFoundException.php
new file mode 100644
index 00000000000..579dcd26f60
--- /dev/null
+++ b/lib/public/Comments/NotFoundException.php
@@ -0,0 +1,28 @@
+<?php
+/**
+ * @author Arthur Schiwon <blizzz@owncloud.com>
+ * @author Thomas Müller <thomas.mueller@tmit.eu>
+ *
+ * @copyright Copyright (c) 2016, ownCloud, Inc.
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3,
+ * as published by the Free Software Foundation.
+ *
+ * This program 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License, version 3,
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>
+ *
+ */
+namespace OCP\Comments;
+
+/**
+ * Exception for not found entity
+ * @since 9.0.0
+ */
+class NotFoundException extends \Exception {}