diff options
author | Roeland Douma <rullzer@users.noreply.github.com> | 2016-05-12 10:48:11 +0300 |
---|---|---|
committer | Thomas Müller <DeepDiver1975@users.noreply.github.com> | 2016-05-12 10:48:11 +0300 |
commit | 56f4c4bed98eef9e422e7283e9c77cce15c312fd (patch) | |
tree | 7be94c56f805f052982379d81bfe84a6365430ce /lib/public/Comments | |
parent | 9b05f37fad88fdf78fdfee9473c27ba5be12abb2 (diff) |
Move \OCP\Comments to PSR-4 (#24565)
Diffstat (limited to 'lib/public/Comments')
-rw-r--r-- | lib/public/Comments/CommentsEvent.php | 70 | ||||
-rw-r--r-- | lib/public/Comments/IComment.php | 240 | ||||
-rw-r--r-- | lib/public/Comments/ICommentsManager.php | 239 | ||||
-rw-r--r-- | lib/public/Comments/ICommentsManagerFactory.php | 53 | ||||
-rw-r--r-- | lib/public/Comments/IllegalIDChangeException.php | 28 | ||||
-rw-r--r-- | lib/public/Comments/MessageTooLongException.php | 27 | ||||
-rw-r--r-- | lib/public/Comments/NotFoundException.php | 28 |
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 {} |