From 9185517bf0b4e9c2728453615447cf6271dbccb5 Mon Sep 17 00:00:00 2001 From: Roeland Jago Douma Date: Thu, 5 May 2016 20:25:08 +0200 Subject: Move \OCP\Activity to PSR-4 --- lib/public/Activity/IConsumer.php | 48 ++++++++ lib/public/Activity/IEvent.php | 200 ++++++++++++++++++++++++++++++++ lib/public/Activity/IExtension.php | 164 +++++++++++++++++++++++++++ lib/public/Activity/IManager.php | 227 +++++++++++++++++++++++++++++++++++++ 4 files changed, 639 insertions(+) create mode 100644 lib/public/Activity/IConsumer.php create mode 100644 lib/public/Activity/IEvent.php create mode 100644 lib/public/Activity/IExtension.php create mode 100644 lib/public/Activity/IManager.php (limited to 'lib/public/Activity') diff --git a/lib/public/Activity/IConsumer.php b/lib/public/Activity/IConsumer.php new file mode 100644 index 00000000000..fc536fd0a56 --- /dev/null +++ b/lib/public/Activity/IConsumer.php @@ -0,0 +1,48 @@ + + * @author Morris Jobke + * @author Thomas Müller + * + * @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 + * + */ + +/** + * Public interface of ownCloud for apps to use. + * Activity/IConsumer interface + */ + +// use OCP namespace for all classes that are considered public. +// This means that they should be used by apps instead of the internal ownCloud classes +namespace OCP\Activity; + +/** + * Interface IConsumer + * + * @package OCP\Activity + * @since 6.0.0 + */ +interface IConsumer { + /** + * @param IEvent $event + * @return null + * @since 6.0.0 + * @since 8.2.0 Replaced the parameters with an IEvent object + */ + public function receive(IEvent $event); +} + diff --git a/lib/public/Activity/IEvent.php b/lib/public/Activity/IEvent.php new file mode 100644 index 00000000000..9b6df9126b2 --- /dev/null +++ b/lib/public/Activity/IEvent.php @@ -0,0 +1,200 @@ + + * + * @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 + * + */ + +/** + * Public interface of ownCloud for apps to use. + * Activity/IEvent interface + */ + +// use OCP namespace for all classes that are considered public. +// This means that they should be used by apps instead of the internal ownCloud classes +namespace OCP\Activity; + +/** + * Interface IEvent + * + * @package OCP\Activity + * @since 8.2.0 + */ +interface IEvent { + /** + * Set the app of the activity + * + * @param string $app + * @return IEvent + * @since 8.2.0 + */ + public function setApp($app); + + /** + * Set the type of the activity + * + * @param string $type + * @return IEvent + * @since 8.2.0 + */ + public function setType($type); + + /** + * Set the affected user of the activity + * + * @param string $user + * @return IEvent + * @since 8.2.0 + */ + public function setAffectedUser($user); + + /** + * Set the author of the activity + * + * @param string $author + * @return IEvent + * @since 8.2.0 + */ + public function setAuthor($author); + + /** + * Set the author of the activity + * + * @param int $timestamp + * @return IEvent + * @since 8.2.0 + */ + public function setTimestamp($timestamp); + + /** + * Set the subject of the activity + * + * @param string $subject + * @param array $parameters + * @return IEvent + * @since 8.2.0 + */ + public function setSubject($subject, array $parameters = []); + + /** + * Set the message of the activity + * + * @param string $message + * @param array $parameters + * @return IEvent + * @since 8.2.0 + */ + public function setMessage($message, array $parameters = []); + + /** + * Set the object of the activity + * + * @param string $objectType + * @param int $objectId + * @param string $objectName + * @return IEvent + * @since 8.2.0 + */ + public function setObject($objectType, $objectId, $objectName = ''); + + /** + * Set the link of the activity + * + * @param string $link + * @return IEvent + * @since 8.2.0 + */ + public function setLink($link); + + /** + * @return string + * @since 8.2.0 + */ + public function getApp(); + + /** + * @return string + * @since 8.2.0 + */ + public function getType(); + + /** + * @return string + * @since 8.2.0 + */ + public function getAffectedUser(); + + /** + * @return string + * @since 8.2.0 + */ + public function getAuthor(); + + /** + * @return int + * @since 8.2.0 + */ + public function getTimestamp(); + + /** + * @return string + * @since 8.2.0 + */ + public function getSubject(); + + /** + * @return array + * @since 8.2.0 + */ + public function getSubjectParameters(); + + /** + * @return string + * @since 8.2.0 + */ + public function getMessage(); + + /** + * @return array + * @since 8.2.0 + */ + public function getMessageParameters(); + + /** + * @return string + * @since 8.2.0 + */ + public function getObjectType(); + + /** + * @return string + * @since 8.2.0 + */ + public function getObjectId(); + + /** + * @return string + * @since 8.2.0 + */ + public function getObjectName(); + + /** + * @return string + * @since 8.2.0 + */ + public function getLink(); +} diff --git a/lib/public/Activity/IExtension.php b/lib/public/Activity/IExtension.php new file mode 100644 index 00000000000..b00dbdda20a --- /dev/null +++ b/lib/public/Activity/IExtension.php @@ -0,0 +1,164 @@ + + * @author Joas Schilling + * @author Morris Jobke + * @author Thomas Müller + * + * @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 + * + */ + +/** + * Public interface of ownCloud for apps to use. + * Activity/IExtension interface + */ + +// use OCP namespace for all classes that are considered public. +// This means that they should be used by apps instead of the internal ownCloud classes +namespace OCP\Activity; + +/** + * Interface IExtension + * + * @package OCP\Activity + * @since 8.0.0 + */ +interface IExtension { + const METHOD_STREAM = 'stream'; + const METHOD_MAIL = 'email'; + + const PRIORITY_VERYLOW = 10; + const PRIORITY_LOW = 20; + const PRIORITY_MEDIUM = 30; + const PRIORITY_HIGH = 40; + const PRIORITY_VERYHIGH = 50; + + /** + * The extension can return an array of additional notification types. + * If no additional types are to be added false is to be returned + * + * @param string $languageCode + * @return array|false Array "stringID of the type" => "translated string description for the setting" + * or Array "stringID of the type" => [ + * 'desc' => "translated string description for the setting" + * 'methods' => [self::METHOD_*], + * ] + * @since 8.0.0 - 8.2.0: Added support to allow limiting notifications to certain methods + */ + public function getNotificationTypes($languageCode); + + /** + * For a given method additional types to be displayed in the settings can be returned. + * In case no additional types are to be added false is to be returned. + * + * @param string $method + * @return array|false + * @since 8.0.0 + */ + public function getDefaultTypes($method); + + /** + * A string naming the css class for the icon to be used can be returned. + * If no icon is known for the given type false is to be returned. + * + * @param string $type + * @return string|false + * @since 8.0.0 + */ + public function getTypeIcon($type); + + /** + * The extension can translate a given message to the requested languages. + * If no translation is available false is to be returned. + * + * @param string $app + * @param string $text + * @param array $params + * @param boolean $stripPath + * @param boolean $highlightParams + * @param string $languageCode + * @return string|false + * @since 8.0.0 + */ + public function translate($app, $text, $params, $stripPath, $highlightParams, $languageCode); + + /** + * The extension can define the type of parameters for translation + * + * Currently known types are: + * * file => will strip away the path of the file and add a tooltip with it + * * username => will add the avatar of the user + * + * @param string $app + * @param string $text + * @return array|false + * @since 8.0.0 + */ + public function getSpecialParameterList($app, $text); + + /** + * The extension can define the parameter grouping by returning the index as integer. + * In case no grouping is required false is to be returned. + * + * @param array $activity + * @return integer|false + * @since 8.0.0 + */ + public function getGroupParameter($activity); + + /** + * The extension can define additional navigation entries. The array returned has to contain two keys 'top' + * and 'apps' which hold arrays with the relevant entries. + * If no further entries are to be added false is no be returned. + * + * @return array|false + * @since 8.0.0 + */ + public function getNavigation(); + + /** + * The extension can check if a customer filter (given by a query string like filter=abc) is valid or not. + * + * @param string $filterValue + * @return boolean + * @since 8.0.0 + */ + public function isFilterValid($filterValue); + + /** + * The extension can filter the types based on the filter if required. + * In case no filter is to be applied false is to be returned unchanged. + * + * @param array $types + * @param string $filter + * @return array|false + * @since 8.0.0 + */ + public function filterNotificationTypes($types, $filter); + + /** + * For a given filter the extension can specify the sql query conditions including parameters for that query. + * In case the extension does not know the filter false is to be returned. + * The query condition and the parameters are to be returned as array with two elements. + * E.g. return array('`app` = ? and `message` like ?', array('mail', 'ownCloud%')); + * + * @param string $filter + * @return array|false + * @since 8.0.0 + */ + public function getQueryForFilter($filter); +} diff --git a/lib/public/Activity/IManager.php b/lib/public/Activity/IManager.php new file mode 100644 index 00000000000..cbd08722410 --- /dev/null +++ b/lib/public/Activity/IManager.php @@ -0,0 +1,227 @@ + + * @author Jörn Friedrich Dreyer + * @author Morris Jobke + * @author Thomas Müller + * + * @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 + * + */ + +/** + * Public interface of ownCloud for apps to use. + * Activity/IManager interface + */ + +// use OCP namespace for all classes that are considered public. +// This means that they should be used by apps instead of the internal ownCloud classes +namespace OCP\Activity; + +/** + * Interface IManager + * + * @package OCP\Activity + * @since 6.0.0 + */ +interface IManager { + /** + * Generates a new IEvent object + * + * Make sure to call at least the following methods before sending it to the + * app with via the publish() method: + * - setApp() + * - setType() + * - setAffectedUser() + * - setSubject() + * + * @return IEvent + * @since 8.2.0 + */ + public function generateEvent(); + + /** + * Publish an event to the activity consumers + * + * Make sure to call at least the following methods before sending an Event: + * - setApp() + * - setType() + * - setAffectedUser() + * - setSubject() + * + * @param IEvent $event + * @return null + * @since 8.2.0 + */ + public function publish(IEvent $event); + + /** + * @param string $app The app where this event is associated with + * @param string $subject A short description of the event + * @param array $subjectParams Array with parameters that are filled in the subject + * @param string $message A longer description of the event + * @param array $messageParams Array with parameters that are filled in the message + * @param string $file The file including path where this event is associated with + * @param string $link A link where this event is associated with + * @param string $affectedUser Recipient of the activity + * @param string $type Type of the notification + * @param int $priority Priority of the notification + * @return null + * @since 6.0.0 + * @deprecated 8.2.0 Grab an IEvent from generateEvent() instead and use the publish() method + */ + public function publishActivity($app, $subject, $subjectParams, $message, $messageParams, $file, $link, $affectedUser, $type, $priority); + + /** + * In order to improve lazy loading a closure can be registered which will be called in case + * activity consumers are actually requested + * + * $callable has to return an instance of \OCP\Activity\IConsumer + * + * @param \Closure $callable + * @return void + * @since 6.0.0 + */ + public function registerConsumer(\Closure $callable); + + /** + * In order to improve lazy loading a closure can be registered which will be called in case + * activity consumers are actually requested + * + * $callable has to return an instance of \OCP\Activity\IExtension + * + * @param \Closure $callable + * @return void + * @since 8.0.0 + */ + public function registerExtension(\Closure $callable); + + /** + * Will return additional notification types as specified by other apps + * + * @param string $languageCode + * @return array Array "stringID of the type" => "translated string description for the setting" + * or Array "stringID of the type" => [ + * 'desc' => "translated string description for the setting" + * 'methods' => [\OCP\Activity\IExtension::METHOD_*], + * ] + * @since 8.0.0 - 8.2.0: Added support to allow limiting notifications to certain methods + */ + public function getNotificationTypes($languageCode); + + /** + * @param string $method + * @return array + * @since 8.0.0 + */ + public function getDefaultTypes($method); + + /** + * @param string $type + * @return string + * @since 8.0.0 + */ + public function getTypeIcon($type); + + /** + * @param string $type + * @param int $id + * @since 8.2.0 + */ + public function setFormattingObject($type, $id); + + /** + * @return bool + * @since 8.2.0 + */ + public function isFormattingFilteredObject(); + + /** + * @param string $app + * @param string $text + * @param array $params + * @param boolean $stripPath + * @param boolean $highlightParams + * @param string $languageCode + * @return string|false + * @since 8.0.0 + */ + public function translate($app, $text, $params, $stripPath, $highlightParams, $languageCode); + + /** + * @param string $app + * @param string $text + * @return array|false + * @since 8.0.0 + */ + public function getSpecialParameterList($app, $text); + + /** + * @param array $activity + * @return integer|false + * @since 8.0.0 + */ + public function getGroupParameter($activity); + + /** + * @return array + * @since 8.0.0 + */ + public function getNavigation(); + + /** + * @param string $filterValue + * @return boolean + * @since 8.0.0 + */ + public function isFilterValid($filterValue); + + /** + * @param array $types + * @param string $filter + * @return array + * @since 8.0.0 + */ + public function filterNotificationTypes($types, $filter); + + /** + * @param string $filter + * @return array + * @since 8.0.0 + */ + public function getQueryForFilter($filter); + + + /** + * Set the user we need to use + * + * @param string|null $currentUserId + * @throws \UnexpectedValueException If the user is invalid + * @since 9.0.1 + */ + public function setCurrentUserId($currentUserId); + + /** + * Get the user we need to use + * + * Either the user is logged in, or we try to get it from the token + * + * @return string + * @throws \UnexpectedValueException If the token is invalid, does not exist or is not unique + * @since 8.1.0 + */ + public function getCurrentUserId(); +} -- cgit v1.2.3