add operator interfaces / API

Signed-off-by: Arthur Schiwon <blizzz@arthur-schiwon.de>

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 [];
+		}
+	}
 }

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);
+	}
+}

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;
 	}
 }
 

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;
 	}
 }

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',

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',

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 { }

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;
 }

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;
+
+
+}

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;
+}