From ea6341df296b86cfa6960d7c2d404e4c77d19506 Mon Sep 17 00:00:00 2001 From: Vincent Petry Date: Tue, 17 Nov 2015 17:01:53 +0100 Subject: [PATCH] Core interfaces for system tags and its manager --- lib/public/systemtag/isystemtag.php | 68 +++++++++++ .../systemtag/isystemtagobjectmapper.php | 115 ++++++++++++++++++ lib/public/systemtag/isystemtagsmanager.php | 111 +++++++++++++++++ .../systemtag/tagalreadyexistsexception.php | 29 +++++ lib/public/systemtag/tagnotfoundexception.php | 29 +++++ 5 files changed, 352 insertions(+) create mode 100644 lib/public/systemtag/isystemtag.php create mode 100644 lib/public/systemtag/isystemtagobjectmapper.php create mode 100644 lib/public/systemtag/isystemtagsmanager.php create mode 100644 lib/public/systemtag/tagalreadyexistsexception.php create mode 100644 lib/public/systemtag/tagnotfoundexception.php diff --git a/lib/public/systemtag/isystemtag.php b/lib/public/systemtag/isystemtag.php new file mode 100644 index 0000000000..76a812f38d --- /dev/null +++ b/lib/public/systemtag/isystemtag.php @@ -0,0 +1,68 @@ + + * + * @copyright Copyright (c) 2015, 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 + * + */ + +namespace OCP\SystemTag; + +/** + * Public interface for a system-wide tag. + * + * @since 9.0.0 + */ +interface ISystemTag { + + /** + * Returns the tag id + * + * @return string id + * + * @since 9.0.0 + */ + public function getId(); + + /** + * Returns the tag display name + * + * @return string tag display name + * + * @since 9.0.0 + */ + public function getName(); + + /** + * Returns whether the tag is visible for regular users + * + * @return bool true if visible, false otherwise + * + * @since 9.0.0 + */ + public function isUserVisible(); + + /** + * Returns whether the tag can be assigned to objects by regular users + * + * @return bool true if assignable, false otherwise + * + * @since 9.0.0 + */ + public function isUserAsssignable(); + +} + diff --git a/lib/public/systemtag/isystemtagobjectmapper.php b/lib/public/systemtag/isystemtagobjectmapper.php new file mode 100644 index 0000000000..87f3fd0473 --- /dev/null +++ b/lib/public/systemtag/isystemtagobjectmapper.php @@ -0,0 +1,115 @@ + + * + * @copyright Copyright (c) 2015, 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 + * + */ + +namespace OCP\SystemTag; + +/** + * Public interface to access and manage system-wide tags. + * + * @since 9.0.0 + */ +interface ISystemTagObjectMapper { + + /** + * Get a list of tag ids for the given object ids. + * + * This returns an array that maps object id to tag ids + * [ + * 1 => array('id1', 'id2'), + * 2 => array('id3', 'id2'), + * 3 => array('id5'), + * 4 => array() + * ] + * + * Untagged objects will have an empty array associated. + * + * @param string|array $objIds object ids + * @param string $objectType object type + * + * @return array with object id as key and an array + * of tag ids as value + * + * @since 9.0.0 + */ + public function getTagIdsForObjects($objIds, $objectType); + + /** + * Get a list of objects tagged with $tagIds. + * + * @param string|array $tagIds Tag id or array of tag ids. + * @param string $objectType object type + * + * @return string[] array of object ids or empty array if none found + * + * @throws \OCP\SystemTag\TagNotFoundException if at least one of the + * given tags does not exist + * + * @since 9.0.0 + */ + public function getObjectIdsForTags($tagIds, $objectType); + + /** + * Assign the given tags to the given object. + * + * @param string $objId object id + * @param string $objectType object type + * @param string|array $tagIds tag id or array of tag ids to assign + * + * @throws \OCP\SystemTag\TagNotFoundException if at least one of the + * given tags does not exist + * + * @since 9.0.0 + */ + public function assignTags($objId, $objectType, $tagIds); + + /** + * Unassign the given tags from the given object. + * + * @param string $objId object id + * @param string $objectType object type + * @param string|array $tagIds tag id or array of tag ids to unassign + * + * @throws \OCP\SystemTag\TagNotFoundException if at least one of the + * given tags does not exist + * + * @since 9.0.0 + */ + public function unassignTags($objId, $objectType, $tagIds); + + /** + * Checks whether the given objects have the given tag. + * + * @param string|array $objIds object ids + * @param string $objectType object type + * @param string $tagId tag id to check + * @param bool $all true to check that ALL objects have the tag assigned, + * false to check that at least ONE object has the tag. + * + * @return bool true if the condition set by $all is matched, false + * otherwise + * + * @throws \OCP\SystemTag\TagNotFoundException if the tag does not exist + * + * @since 9.0.0 + */ + public function hasTags($objIds, $objectType, $tagId, $all = true); + +} diff --git a/lib/public/systemtag/isystemtagsmanager.php b/lib/public/systemtag/isystemtagsmanager.php new file mode 100644 index 0000000000..df59cc48d5 --- /dev/null +++ b/lib/public/systemtag/isystemtagsmanager.php @@ -0,0 +1,111 @@ + + * + * @copyright Copyright (c) 2015, 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 + * + */ + +namespace OCP\SystemTag; + +/** + * Public interface to access and manage system-wide tags. + * + * @since 9.0.0 + */ +interface ISystemTagManager { + + /** + * Returns the tag objects matching the given tag ids. + * + * @param array|string $tagIds The ID or array of IDs of the tags to retrieve + * + * @return \OCP\SystemTag\ISystemTag[] array of system tags or empty array if none found + * + * @since 9.0.0 + */ + public function getTagsById($tagIds); + + /** + * Returns the tag object matching the given attributes. + * + * @param string $tagName tag name + * @param bool $userVisible whether the tag is visible by users + * @param bool $userAssignable whether the tag is assignable by users + * + * @return \OCP\SystemTag\ISystemTag system tag + * + * @throws \OCP\SystemTag\TagNotFoundException if tag does not exist + * + * @since 9.0.0 + */ + public function getTag($tagName, $userVisible, $userAssignable); + + /** + * Creates the tag object using the given attributes. + * + * @param string $tagName tag name + * @param bool $userVisible whether the tag is visible by users + * @param bool $userAssignable whether the tag is assignable by users + * + * @return \OCP\SystemTag\ISystemTag system tag + * + * @throws \OCP\SystemTag\TagAlreadyExistsException if tag already exists + * + * @since 9.0.0 + */ + public function createTag($tagName, $userVisible, $userAssignable); + + /** + * Returns all known tags, optionally filtered by visibility. + * + * @param bool $visibleOnly whether to only return user visible tags + * @param string $nameSearchPattern optional search pattern for the tag name + * + * @return \OCP\SystemTag\ISystemTag[] array of system tags or empty array if none found + * + * @since 9.0.0 + */ + public function getAllTags($visibleOnly = false, $nameSearchPattern = null); + + /** + * Updates the given tag + * + * @param string $tagId tag id + * @param string $newName the new tag name + * @param bool $userVisible whether the tag is visible by users + * @param bool $userAssignable whether the tag is assignable by users + * + * @throws \OCP\SystemTag\TagNotFoundException if tag with the given id does not exist + * @throws \OCP\SystemTag\TagAlreadyExistsException if there is already another tag + * with the same attributes + * + * @since 9.0.0 + */ + public function updateTag($tagId, $newName, $userVisible, $userAssignable); + + /** + * Delete the given tags from the database and all their relationships. + * + * @param string|array $tagIds array of tag ids + * + * @throws \OCP\SystemTag\TagNotFoundException if tag did not exist + * + * @since 9.0.0 + */ + public function deleteTags($tagIds); + +} diff --git a/lib/public/systemtag/tagalreadyexistsexception.php b/lib/public/systemtag/tagalreadyexistsexception.php new file mode 100644 index 0000000000..d192b38e7b --- /dev/null +++ b/lib/public/systemtag/tagalreadyexistsexception.php @@ -0,0 +1,29 @@ + + * + * @copyright Copyright (c) 2015, 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 + * + */ + +namespace OCP\SystemTag; + +/** + * Exception when a tag already exists. + * + * @since 9.0.0 + */ +class TagAlreadyExistsException extends \RuntimeException {} diff --git a/lib/public/systemtag/tagnotfoundexception.php b/lib/public/systemtag/tagnotfoundexception.php new file mode 100644 index 0000000000..94bb07c8c1 --- /dev/null +++ b/lib/public/systemtag/tagnotfoundexception.php @@ -0,0 +1,29 @@ + + * + * @copyright Copyright (c) 2015, 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 + * + */ + +namespace OCP\SystemTag; + +/** + * Exception when a tag was not found. + * + * @since 9.0.0 + */ +class TagNotFoundException extends \RuntimeException {}