From ec36c0ae80ea50d460f2c15c16e7d9de15cafd40 Mon Sep 17 00:00:00 2001
From: Arthur Schiwon <blizzz@arthur-schiwon.de>
Date: Fri, 23 Aug 2019 16:56:24 +0200
Subject: [PATCH] add operator interfaces / API
Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>
---
apps/workflowengine/lib/Manager.php | 33 +++-
.../workflowengine/lib/Settings/ASettings.php | 158 ++++++++++++++++++
apps/workflowengine/lib/Settings/Admin.php | 6 +-
apps/workflowengine/lib/Settings/Personal.php | 6 +-
lib/composer/composer/autoload_classmap.php | 3 +
lib/composer/composer/autoload_static.php | 3 +
.../WorkflowEngine/IComplexOperator.php | 43 +++++
lib/public/WorkflowEngine/IManager.php | 8 +
lib/public/WorkflowEngine/IOperator.php | 91 ++++++++++
.../WorkflowEngine/ISpecificOperator.php | 50 ++++++
10 files changed, 396 insertions(+), 5 deletions(-)
create mode 100644 apps/workflowengine/lib/Settings/ASettings.php
create mode 100644 lib/public/WorkflowEngine/IComplexOperator.php
create mode 100644 lib/public/WorkflowEngine/IOperator.php
create mode 100644 lib/public/WorkflowEngine/ISpecificOperator.php
diff --git a/apps/workflowengine/lib/Manager.php b/apps/workflowengine/lib/Manager.php
index ecf3f24bda1..d19aa31547a 100644
--- a/apps/workflowengine/lib/Manager.php
+++ b/apps/workflowengine/lib/Manager.php
@@ -40,6 +40,7 @@ use OCP\WorkflowEngine\IEntity;
use OCP\WorkflowEngine\IEntityAware;
use OCP\WorkflowEngine\IManager;
use OCP\WorkflowEngine\IOperation;
+use OCP\WorkflowEngine\IOperator;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\EventDispatcher\GenericEvent;
@@ -75,6 +76,9 @@ class Manager implements IManager, IEntityAware {
/** @var IEntity[] */
protected $registeredEntities = [];
+ /** @var IOperator[] */
+ protected $registeredOperators = [];
+
/** @var ILogger */
protected $logger;
@@ -545,12 +549,21 @@ class Manager implements IManager, IEntityAware {
/**
* @return IEntity[]
*/
- public function getEntitiesList() {
+ public function getEntitiesList(): array {
$this->eventDispatcher->dispatch('OCP\WorkflowEngine::registerEntities', new GenericEvent($this));
return array_merge($this->getBuildInEntities(), $this->registeredEntities);
}
+ /**
+ * @return IOperator[]
+ */
+ public function getOperatorList(): array {
+ $this->eventDispatcher->dispatch('OCP\WorkflowEngine::registerOperators', new GenericEvent($this));
+
+ return array_merge($this->getBuildInOperators(), $this->registeredOperators);
+ }
+
/**
* Listen to 'OCP/WorkflowEngine::registerEntities' at the EventDispatcher
* for registering your entities
@@ -561,6 +574,10 @@ class Manager implements IManager, IEntityAware {
$this->registeredEntities[$entity->getId()] = $entity;
}
+ public function registerOperator(IOperator $operator): void {
+ $this->registeredOperators[$operator->getId()] = $operator;
+ }
+
/**
* @return IEntity[]
*/
@@ -574,4 +591,18 @@ class Manager implements IManager, IEntityAware {
return [];
}
}
+
+ /**
+ * @return IOperator[]
+ */
+ protected function getBuildInOperators(): array {
+ try {
+ return [
+ // None yet
+ ];
+ } catch (QueryException $e) {
+ $this->logger->logException($e);
+ return [];
+ }
+ }
}
diff --git a/apps/workflowengine/lib/Settings/ASettings.php b/apps/workflowengine/lib/Settings/ASettings.php
new file mode 100644
index 00000000000..78a23d924c7
--- /dev/null
+++ b/apps/workflowengine/lib/Settings/ASettings.php
@@ -0,0 +1,158 @@
+<?php
+declare(strict_types=1);
+/**
+ * @copyright Copyright (c) 2019 Arthur Schiwon <blizzz@arthur-schiwon.de>
+ *
+ * @author Arthur Schiwon <blizzz@arthur-schiwon.de>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * 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
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCA\WorkflowEngine\Settings;
+
+use OCA\WorkflowEngine\AppInfo\Application;
+use OCA\WorkflowEngine\Manager;
+use OCP\AppFramework\Http\TemplateResponse;
+use OCP\IInitialStateService;
+use OCP\IL10N;
+use OCP\Settings\ISettings;
+use OCP\WorkflowEngine\IComplexOperator;
+use OCP\WorkflowEngine\IEntity;
+use OCP\WorkflowEngine\IEntityEvent;
+use OCP\WorkflowEngine\IOperator;
+use OCP\WorkflowEngine\ISpecificOperator;
+use Symfony\Component\EventDispatcher\EventDispatcherInterface;
+
+abstract class ASettings implements ISettings {
+ /** @var IL10N */
+ private $l10n;
+
+ /** @var string */
+ private $appName;
+
+ /** @var EventDispatcherInterface */
+ private $eventDispatcher;
+
+ /** @var Manager */
+ private $manager;
+
+ /** @var IInitialStateService */
+ private $initialStateService;
+
+ /**
+ * @param string $appName
+ * @param IL10N $l
+ * @param EventDispatcherInterface $eventDispatcher
+ */
+ public function __construct(
+ $appName,
+ IL10N $l,
+ EventDispatcherInterface $eventDispatcher,
+ Manager $manager,
+ IInitialStateService $initialStateService
+ ) {
+ $this->appName = $appName;
+ $this->l10n = $l;
+ $this->eventDispatcher = $eventDispatcher;
+ $this->manager = $manager;
+ $this->initialStateService = $initialStateService;
+ }
+
+ abstract function getScope(): int;
+
+ /**
+ * @return TemplateResponse
+ */
+ public function getForm() {
+ $this->eventDispatcher->dispatch('OCP\WorkflowEngine::loadAdditionalSettingScripts');
+
+ $entities = $this->manager->getEntitiesList();
+ $this->initialStateService->provideInitialState(
+ Application::APP_ID,
+ 'entities',
+ $this->entitiesToArray($entities)
+ );
+
+ $operators = $this->manager->getOperatorList();
+ $this->initialStateService->provideInitialState(
+ Application::APP_ID,
+ 'operators',
+ $this->operatorsToArray($operators)
+ );
+
+ $this->initialStateService->provideInitialState(
+ Application::APP_ID,
+ 'scope',
+ $this->getScope()
+ );
+
+ return new TemplateResponse(Application::APP_ID, 'settings', [], 'blank');
+ }
+
+ /**
+ * @return string the section ID, e.g. 'sharing'
+ */
+ public function getSection() {
+ return 'workflow';
+ }
+
+ /**
+ * @return int whether the form should be rather on the top or bottom of
+ * the admin section. The forms are arranged in ascending order of the
+ * priority values. It is required to return a value between 0 and 100.
+ *
+ * E.g.: 70
+ */
+ public function getPriority() {
+ return 0;
+ }
+
+ private function entitiesToArray(array $entities) {
+ return array_map(function (IEntity $entity) {
+ $events = array_map(function(IEntityEvent $entityEvent) {
+ return [
+ 'eventName' => $entityEvent->getEventName(),
+ 'displayName' => $entityEvent->getDisplayName()
+ ];
+ }, $entity->getEvents());
+
+ return [
+ 'id' => $entity->getId(),
+ 'icon' => $entity->getIcon(),
+ 'name' => $entity->getName(),
+ 'events' => $events,
+ ];
+ }, $entities);
+ }
+
+ private function operatorsToArray(array $operators) {
+ $operators = array_filter($operators, function(IOperator $operator) {
+ return $operator->isAvailableForScope($this->getScope());
+ });
+
+ return array_map(function (IOperator $operator) {
+ return [
+ 'id' => $operator->getId(),
+ 'icon' => $operator->getIcon(),
+ 'name' => $operator->getDisplayName(),
+ 'description' => $operator->getDescription(),
+ 'fixedEntity' => $operator instanceof ISpecificOperator ? $operator->getEntityId() : '',
+ 'isComplex' => $operator instanceof IComplexOperator,
+ ];
+ }, $operators);
+ }
+}
diff --git a/apps/workflowengine/lib/Settings/Admin.php b/apps/workflowengine/lib/Settings/Admin.php
index 39932d5f1f2..20ea8ad43c4 100644
--- a/apps/workflowengine/lib/Settings/Admin.php
+++ b/apps/workflowengine/lib/Settings/Admin.php
@@ -24,10 +24,12 @@ declare(strict_types=1);
namespace OCA\WorkflowEngine\Settings;
+use OCP\WorkflowEngine\IManager;
+
class Admin extends ASettings {
- function isAdmin(): bool {
- return true;
+ function getScope(): int {
+ return IManager::SCOPE_ADMIN;
}
}
diff --git a/apps/workflowengine/lib/Settings/Personal.php b/apps/workflowengine/lib/Settings/Personal.php
index d6ed220577f..9c23a250355 100644
--- a/apps/workflowengine/lib/Settings/Personal.php
+++ b/apps/workflowengine/lib/Settings/Personal.php
@@ -24,9 +24,11 @@ declare(strict_types=1);
namespace OCA\WorkflowEngine\Settings;
+use OCP\WorkflowEngine\IManager;
+
class Personal extends ASettings {
- function isAdmin(): bool {
- return false;
+ function getScope(): int {
+ return IManager::SCOPE_USER;
}
}
diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
index 2c76674ee52..76322993b48 100644
--- a/lib/composer/composer/autoload_classmap.php
+++ b/lib/composer/composer/autoload_classmap.php
@@ -439,11 +439,14 @@ return array(
'OCP\\User\\Backend\\ISetPasswordBackend' => $baseDir . '/lib/public/User/Backend/ISetPasswordBackend.php',
'OCP\\Util' => $baseDir . '/lib/public/Util.php',
'OCP\\WorkflowEngine\\ICheck' => $baseDir . '/lib/public/WorkflowEngine/ICheck.php',
+ 'OCP\\WorkflowEngine\\IComplexOperator' => $baseDir . '/lib/public/WorkflowEngine/IComplexOperator.php',
'OCP\\WorkflowEngine\\IEntity' => $baseDir . '/lib/public/WorkflowEngine/IEntity.php',
'OCP\\WorkflowEngine\\IEntityAware' => $baseDir . '/lib/public/WorkflowEngine/IEntityAware.php',
'OCP\\WorkflowEngine\\IEntityEvent' => $baseDir . '/lib/public/WorkflowEngine/IEntityEvent.php',
'OCP\\WorkflowEngine\\IManager' => $baseDir . '/lib/public/WorkflowEngine/IManager.php',
'OCP\\WorkflowEngine\\IOperation' => $baseDir . '/lib/public/WorkflowEngine/IOperation.php',
+ 'OCP\\WorkflowEngine\\IOperator' => $baseDir . '/lib/public/WorkflowEngine/IOperator.php',
+ 'OCP\\WorkflowEngine\\ISpecificOperator' => $baseDir . '/lib/public/WorkflowEngine/ISpecificOperator.php',
'OC\\Accounts\\Account' => $baseDir . '/lib/private/Accounts/Account.php',
'OC\\Accounts\\AccountManager' => $baseDir . '/lib/private/Accounts/AccountManager.php',
'OC\\Accounts\\AccountProperty' => $baseDir . '/lib/private/Accounts/AccountProperty.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
index 651364d06c1..f164d0b15bd 100644
--- a/lib/composer/composer/autoload_static.php
+++ b/lib/composer/composer/autoload_static.php
@@ -473,11 +473,14 @@ class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
'OCP\\User\\Backend\\ISetPasswordBackend' => __DIR__ . '/../../..' . '/lib/public/User/Backend/ISetPasswordBackend.php',
'OCP\\Util' => __DIR__ . '/../../..' . '/lib/public/Util.php',
'OCP\\WorkflowEngine\\ICheck' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/ICheck.php',
+ 'OCP\\WorkflowEngine\\IComplexOperator' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/IComplexOperator.php',
'OCP\\WorkflowEngine\\IEntity' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/IEntity.php',
'OCP\\WorkflowEngine\\IEntityAware' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/IEntityAware.php',
'OCP\\WorkflowEngine\\IEntityEvent' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/IEntityEvent.php',
'OCP\\WorkflowEngine\\IManager' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/IManager.php',
'OCP\\WorkflowEngine\\IOperation' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/IOperation.php',
+ 'OCP\\WorkflowEngine\\IOperator' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/IOperator.php',
+ 'OCP\\WorkflowEngine\\ISpecificOperator' => __DIR__ . '/../../..' . '/lib/public/WorkflowEngine/ISpecificOperator.php',
'OC\\Accounts\\Account' => __DIR__ . '/../../..' . '/lib/private/Accounts/Account.php',
'OC\\Accounts\\AccountManager' => __DIR__ . '/../../..' . '/lib/private/Accounts/AccountManager.php',
'OC\\Accounts\\AccountProperty' => __DIR__ . '/../../..' . '/lib/private/Accounts/AccountProperty.php',
diff --git a/lib/public/WorkflowEngine/IComplexOperator.php b/lib/public/WorkflowEngine/IComplexOperator.php
new file mode 100644
index 00000000000..ee2d3d0a183
--- /dev/null
+++ b/lib/public/WorkflowEngine/IComplexOperator.php
@@ -0,0 +1,43 @@
+<?php
+declare(strict_types=1);
+/**
+ * @copyright Copyright (c) 2019 Arthur Schiwon <blizzz@arthur-schiwon.de>
+ *
+ * @author Arthur Schiwon <blizzz@arthur-schiwon.de>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * 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
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\WorkflowEngine;
+
+/**
+ * Interface IComplexOperator
+ *
+ * This interface represents an operator that is less generic and indicates
+ * that some of the tasks it does itself instead of relying on the engine.
+ * This includes:
+ *
+ * * registering listeners – the implementing app needs to ensure that the
+ * business logic registers listeners to the events it listens to. For example
+ * when direct storage access is required, adding a wrapper or listening to
+ * a specific one is required over usual file events.
+ *
+ * @package OCP\WorkflowEngine
+ *
+ * @sincee 18.0.0
+ */
+interface IComplexOperator extends IOperator { }
diff --git a/lib/public/WorkflowEngine/IManager.php b/lib/public/WorkflowEngine/IManager.php
index c05459e1fb4..6d4bacc8e17 100644
--- a/lib/public/WorkflowEngine/IManager.php
+++ b/lib/public/WorkflowEngine/IManager.php
@@ -59,4 +59,12 @@ interface IManager {
* @since 18.0.0
*/
public function registerEntity(IEntity $entity): void;
+
+ /**
+ * Listen to 'OCP/WorkflowEngine::registerOperators' at the EventDispatcher
+ * for registering your operators
+ *
+ * @since 18.0.0
+ */
+ public function registerOperator(IOperator $operator): void;
}
diff --git a/lib/public/WorkflowEngine/IOperator.php b/lib/public/WorkflowEngine/IOperator.php
new file mode 100644
index 00000000000..70c80d98c45
--- /dev/null
+++ b/lib/public/WorkflowEngine/IOperator.php
@@ -0,0 +1,91 @@
+<?php
+declare(strict_types=1);
+/**
+ * @copyright Copyright (c) 2019 Arthur Schiwon <blizzz@arthur-schiwon.de>
+ *
+ * @author Arthur Schiwon <blizzz@arthur-schiwon.de>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * 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
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\WorkflowEngine;
+
+/**
+ * @since 18.0.0
+ */
+interface IOperator {
+ /**
+ * returns the unique identity of the operator
+ *
+ * It is recommended to use the namespaced class name of the IOperator
+ * implementation. Especially workflow applications released before
+ * Nextcloud 18 should chose this as id for compatibility.
+ *
+ * Example: OCA\FilesAutomatedTagging\Operation
+ *
+ * @since 18.0.0
+ */
+ public function getId(): string;
+
+ /**
+ * returns a translated name to be presented in the web interface
+ *
+ * Example: "Automated tagging" (en), "AÅtomata etikedado" (eo)
+ *
+ * @since 18.0.0
+ */
+ public function getDisplayName(): string;
+
+ /**
+ * returns a translated, descriptive text to be presented in the web interface.
+ *
+ * It should be short and precise.
+ *
+ * Example: "Tag based automatic deletion of files after a given time." (en)
+ *
+ * @since 18.0.0
+ */
+ public function getDescription(): string;
+
+ /**
+ * returns the URL to the icon of the operator for display in the web interface.
+ *
+ * Usually, the implementation would utilize the `imagePath()` method of the
+ * `\OCP\IURLGenerator` instance and simply return its result.
+ *
+ * Example implementation: return $this->urlGenerator->imagePath('myApp', 'cat.svg');
+ *
+ * @since 18.0.0
+ */
+ public function getIcon(): string;
+
+ /**
+ * returns whether the operation can be used in the requested scope.
+ *
+ * Scope IDs are defined as constants in OCP\WorkflowEngine\IManager. At
+ * time of writing these are SCOPE_ADMIN and SCOPE_USER.
+ *
+ * For possibly unknown future scopes the recommended behaviour is: if
+ * user scope is permitted, the default behaviour should return `true`,
+ * otherwise `false`.
+ *
+ * @since 18.0.0
+ */
+ public function isAvailableForScope(int $scope): bool;
+
+
+}
diff --git a/lib/public/WorkflowEngine/ISpecificOperator.php b/lib/public/WorkflowEngine/ISpecificOperator.php
new file mode 100644
index 00000000000..a5ae9fc1841
--- /dev/null
+++ b/lib/public/WorkflowEngine/ISpecificOperator.php
@@ -0,0 +1,50 @@
+<?php
+declare(strict_types=1);
+/**
+ * @copyright Copyright (c) 2019 Arthur Schiwon <blizzz@arthur-schiwon.de>
+ *
+ * @author Arthur Schiwon <blizzz@arthur-schiwon.de>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * 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
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\WorkflowEngine;
+
+/**
+ * Interface ISpecificOperator
+ *
+ * This interface represents an operator that is designed to work with exactly
+ * one entity type.
+ *
+ * In almost all of the cases it is not necessary to have this limitation,
+ * because the action is not connected to the event. This mechanism suits
+ * special cases.
+ *
+ * @package OCP\WorkflowEngine
+ * @since 18.0.0
+ */
+interface ISpecificOperator extends IOperator {
+
+ /**
+ * returns the id of the entity the operator is designed for
+ *
+ * Example: 'WorkflowEngine_Entity_File'
+ *
+ * @since 18.0.0
+ */
+ public function getEntityId():string;
+}
--
GitLab