add operator interfaces / API

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

4 files changed, 192 insertions, 0 deletions

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