WorkflowStubInterface.php

<?php

/**
 * This file is part of Temporal package.
 *
 * For the full copyright and license information, please view the LICENSE
 * file that was distributed with this source code.
 */

declare(strict_types=1);

namespace Temporal\Client;

use Temporal\Client\Update\UpdateHandle;
use Temporal\Client\Update\UpdateOptions;
use Temporal\DataConverter\Type;
use Temporal\DataConverter\ValuesInterface;
use Temporal\Exception\Client\WorkflowUpdateException;
use Temporal\Exception\Client\WorkflowUpdateRPCTimeoutOrCanceledException;
use Temporal\Exception\IllegalStateException;
use Temporal\Workflow\CancellationScopeInterface;
use Temporal\Workflow\QueryMethod;
use Temporal\Workflow\UpdateMethod;
use Temporal\Workflow\WorkflowExecution;
use Temporal\Workflow\WorkflowRunInterface;

/**
 * WorkflowStub is a client side stub to a single workflow instance.
 *
 * It can be used to start, signal, query, wait for completion and cancel a workflow
 * execution. Created through {@see WorkflowClient::newUntypedWorkflowStub()}.
 * @template ReturnType
 * @extends WorkflowRunInterface<ReturnType>
 */
interface WorkflowStubInterface extends WorkflowRunInterface
{
    /**
     * @return non-empty-string|null
     */
    public function getWorkflowType(): ?string;

    /**
     * Returns associated workflow options. Empty for running workflows. Workflow options are immutable and can
     * not be changed after the workflow was created.
     */
    public function getOptions(): ?WorkflowOptions;

    /**
     * Get associated workflow execution (if any).
     *
     * @throws IllegalStateException
     */
    public function getExecution(): WorkflowExecution;

    /**
     * Check if workflow was started and has associated execution.
     */
    public function hasExecution(): bool;

    /**
     * Attaches running workflow context to the workflow stub.
     */
    public function setExecution(WorkflowExecution $execution): void;

    /**
     * Sends named signal to the workflow execution.
     *
     * @param mixed ...$args
     */
    public function signal(string $name, ...$args): void;

    /**
     * Synchronously queries workflow by invoking its query handler.
     *
     * Usually a query handler is a method annotated with {@see QueryMethod}.
     *
     * @param mixed ...$args
     */
    public function query(string $name, ...$args): ?ValuesInterface;

    /**
     * Synchronously update a workflow execution by invoking its update handler.
     *
     * Usually an update handler is a method annotated with the {@see UpdateMethod} attribute.
     *
     * @param non-empty-string $name Name of the update handler.
     * @param mixed ...$args Arguments to pass to the update handler.
     * @throws WorkflowUpdateException
     * @throws WorkflowUpdateRPCTimeoutOrCanceledException
     */
    public function update(string $name, ...$args): ?ValuesInterface;

    /**
     * Update a workflow execution by invoking its update handler and returning a
     * handle to the update request.
     *
     * By default, WaitPolicy is set to {@see \Temporal\Client\Update\LifecycleStage::StageAccepted},
     * which means that the handle will return immediately after successful validation of the Update call.
     * However, also note that the processing Workflow worker must be available. Otherwise, the request
     * may block indefinitely or fail due to a timeout.
     *
     * Usually an update handler is a method annotated with the {@see UpdateMethod} attribute.
     *
     * @param non-empty-string|UpdateOptions $nameOrOptions Name of the update handler or update options.
     * @param mixed ...$args Arguments to pass to the update handler.
     * @throws WorkflowUpdateRPCTimeoutOrCanceledException
     */
    public function startUpdate(string|UpdateOptions $nameOrOptions, ...$args): UpdateHandle;

    /**
     * Get a handle to an existing update request.
     *
     * @param non-empty-string $updateId
     * @param string|\ReflectionClass|\ReflectionType|Type|null $resultType
     */
    public function getUpdateHandle(string $updateId, mixed $resultType = null): UpdateHandle;

    /**
     * Request cancellation of a workflow execution.
     *
     * Cancellation cancels {@see CancellationScopeInterface} that wraps the
     * main workflow method. Note that workflow can take long time to get
     * canceled or even completely ignore the cancellation request.
     */
    public function cancel(): void;

    /**
     * Terminates a workflow execution.
     *
     * Termination is a hard stop of a workflow execution which doesn't give
     * workflow code any chance to perform cleanup.
     */
    public function terminate(string $reason, array $details = []): void;
}