You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kie.apache.org by dj...@apache.org on 2026/10/07 04:38:15 UTC

(incubator-kie) 01/01: JavaDoc for Workflow Extension Points

This is an automated email from the ASF dual-hosted git repository.

josedee pushed a commit to branch incubator-kie#7172
in repository https://gitbox.apache.org/repos/asf/incubator-kie.git

commit 805be0326c590df479cc808abff02358c15c8385
Author: Deepak Joseph <De...@ibm.com>
AuthorDate: Wed Oct 7 10:07:58 2026 +0530

    JavaDoc for Workflow Extension Points
---
 .../api/event/process/ProcessEventListener.java    | 102 ++++++++++++---------
 .../org/kie/kogito/calendar/BusinessCalendar.java  |  23 ++---
 .../java/org/kie/kogito/event/EventPublisher.java  |  23 ++---
 .../process/workitem/KogitoWorkItemHandler.java    |  69 ++++++++++++--
 .../usertask/UserTaskAssignmentStrategy.java       |  18 ++++
 .../kie/kogito/usertask/UserTaskEventListener.java |  62 +++++++++++++
 .../usertask/lifecycle/UserTaskLifeCycle.java      |  72 +++++++++++++++
 7 files changed, 292 insertions(+), 77 deletions(-)

diff --git a/kie-api/src/main/java/org/kie/api/event/process/ProcessEventListener.java b/kie-api/src/main/java/org/kie/api/event/process/ProcessEventListener.java
index 1ddb65db8c1..f3b7f01ec06 100644
--- a/kie-api/src/main/java/org/kie/api/event/process/ProcessEventListener.java
+++ b/kie-api/src/main/java/org/kie/api/event/process/ProcessEventListener.java
@@ -21,122 +21,138 @@ package org.kie.api.event.process;
 import java.util.EventListener;
 
 /**
- * A listener for events related to process instance execution.
+ * <b>Process Event Listener</b> extension point.
+ *
+ * <p>Listens for process execution lifecycle events, including process start and completion,
+ * node entry and exit, variable mutations, SLA violations, signals, and error boundaries.
  */
 public interface ProcessEventListener
     extends
     EventListener {
 
     /**
-     * This listener method is invoked right before a process instance is being started.
-     * @param event
+     * Invoked immediately before a process instance is started.
+     *
+     * @param event the non-null {@link ProcessStartedEvent}
      */
     void beforeProcessStarted(ProcessStartedEvent event);
 
     /**
-     * This listener method is invoked right after a process instance has been started.
-     * @param event
+     * Invoked immediately after a process instance is started.
+     *
+     * @param event the non-null {@link ProcessStartedEvent}
      */
     void afterProcessStarted(ProcessStartedEvent event);
 
     /**
-     * This listener method is invoked right before a process instance is being completed (or aborted).
-     * @param event
+     * Invoked immediately before a process instance is completed or aborted.
+     *
+     * @param event the non-null {@link ProcessCompletedEvent}
      */
     void beforeProcessCompleted(ProcessCompletedEvent event);
 
     /**
-     * This listener method is invoked right after a process instance has been completed (or aborted).
-     * @param event
+     * Invoked immediately after a process instance is completed or aborted.
+     *
+     * @param event the non-null {@link ProcessCompletedEvent}
      */
     void afterProcessCompleted(ProcessCompletedEvent event);
 
     /**
-     * This listener method is invoked right before a node in a process instance is being triggered
-     * (which is when the node is being entered, for example when an incoming connection triggers it).
-     * @param event
+     * Invoked immediately before a node instance is triggered (node entry).
+     *
+     * @param event the non-null {@link ProcessNodeTriggeredEvent}
      */
     void beforeNodeTriggered(ProcessNodeTriggeredEvent event);
 
     /**
-     * This listener method is invoked right after a node in a process instance has been triggered
-     * (which is when the node was entered, for example when an incoming connection triggered it).
-     * @param event
+     * Invoked immediately after a node instance is triggered (node entry).
+     *
+     * @param event the non-null {@link ProcessNodeTriggeredEvent}
      */
     void afterNodeTriggered(ProcessNodeTriggeredEvent event);
 
     /**
-     * This listener method is invoked right before a node in a process instance is being left
-     * (which is when the node is completed, for example when it has performed the task it was
-     * designed for).
-     * @param event
+     * Invoked immediately before a node instance is left (node exit).
+     *
+     * @param event the non-null {@link ProcessNodeLeftEvent}
      */
     void beforeNodeLeft(ProcessNodeLeftEvent event);
 
     /**
-     * This listener method is invoked right after a node in a process instance has been left
-     * (which is when the node was completed, for example when it performed the task it was
-     * designed for).
-     * @param event
+     * Invoked immediately after a node instance is left (node exit).
+     *
+     * @param event the non-null {@link ProcessNodeLeftEvent}
      */
     void afterNodeLeft(ProcessNodeLeftEvent event);
 
     /**
-     * This listener method is invoked right before the value of a process variable is being changed.
-     * @param event
+     * Invoked immediately before a process variable value is modified.
+     *
+     * @param event the non-null {@link ProcessVariableChangedEvent}
      */
     void beforeVariableChanged(ProcessVariableChangedEvent event);
 
     /**
-     * This listener method is invoked right after the value of a process variable has been changed.
-     * @param event
+     * Invoked immediately after a process variable value has been modified.
+     *
+     * @param event the non-null {@link ProcessVariableChangedEvent}
      */
     void afterVariableChanged(ProcessVariableChangedEvent event);
     
     /**
-     * This listener method is invoked right before a process/node instance's SLA has been violated.
-     * @param event
+     * Invoked immediately before an SLA deadline on a process or node instance is violated.
+     *
+     * @param event the non-null {@link SLAViolatedEvent}
      */
     default void beforeSLAViolated(SLAViolatedEvent event) {}
 
     /**
-     * This listener method is invoked right after a process/node instance's SLA has been violated.
-     * @param event
+     * Invoked immediately after an SLA deadline on a process or node instance is violated.
+     *
+     * @param event the non-null {@link SLAViolatedEvent}
      */
     default void afterSLAViolated(SLAViolatedEvent event) {}
 
     /**
-     * This listener method is invoked when a signal is sent
-     * @param event
+     * Invoked when a signal is dispatched.
+     *
+     * @param event the non-null {@link SignalEvent}
      */
     default void onSignal(SignalEvent event) {}
 
     /**
-     * This listeners is triggered when a migration occurs
-     * @param event
+     * Invoked when a process instance migration occurs across.
+     *
+     * @param event the non-null {@link ProcessMigrationEvent}
      */
     default void onMigration(ProcessMigrationEvent event) { }
+
     /**
-     * This listener method is invoked when a message is sent
-     * @param event
+     * Invoked when a message event is sent.
+     *
+     * @param event the non-null {@link MessageEvent}
      */
     default void onMessage(MessageEvent event) {}
     
     /**
-     * This listener method is invoked when an error is captured
-     * @param event
+     * Invoked when an error is captured during process execution.
+     *
+     * @param event the non-null {@link ErrorEvent}
      */
     default void onError (ErrorEvent event) {}
 
     /**
-     * This listener method is invoked right after a process instance is modified.
-     * @param event
+     * Invoked right after a process instance is modified.
+     *
+     * @param event the non-null {@link ProcessStateChangeEvent}
      */
     default void onProcessStateChanged(ProcessStateChangeEvent event) {}
 
     /**
-     * This listener method is invoked right after a node in a process instance is modified.
-     * @param event
+     * Invoked right after a node in a process instance is modified.
+     *
+     * @param event the non-null {@link ProcessNodeStateChangeEvent}
      */
     default void onNodeStateChanged(ProcessNodeStateChangeEvent event) {}
 }
diff --git a/kogito-api/kogito-api/src/main/java/org/kie/kogito/calendar/BusinessCalendar.java b/kogito-api/kogito-api/src/main/java/org/kie/kogito/calendar/BusinessCalendar.java
index 45ecce21bd4..594925ced14 100644
--- a/kogito-api/kogito-api/src/main/java/org/kie/kogito/calendar/BusinessCalendar.java
+++ b/kogito-api/kogito-api/src/main/java/org/kie/kogito/calendar/BusinessCalendar.java
@@ -21,27 +21,28 @@ package org.kie.kogito.calendar;
 import java.util.Date;
 
 /**
- * BusinessCalendar allows for defining custom definitions of working days, hours and holidays
- * to be taken under consideration when scheduling time based activities such as timers or deadlines.
+ * <b>Business Calendar</b> extension point.
+ *
+ * <p>
+ * Calculates business working hours, weekend exclusions, and corporate holiday schedules
+ * for workflow timer nodes, SLA tracking, and user task deadline escalations.
  */
 public interface BusinessCalendar {
 
     /**
-     * Returns the difference, in milliseconds, between the <b>business date</b> that matches the given
-     * <code>timeExpression</code>, and the current time.
-     * See {@link #calculateBusinessTimeAsDate} for <b>business date</b> calculation
+     * Calculates the duration in milliseconds from the current time to the business time matching the expression.
      *
      * @param timeExpression time expression that is supported by business calendar implementation.
-     * @return duration expressed in milliseconds
+     * @return duration expressed in milliseconds; always &gt;= 0
+     * @see #calculateBusinessTimeAsDate(String)
      */
     long calculateBusinessTimeAsDuration(String timeExpression);
 
     /**
-     * Returns the first <code>Date</code> that matches the given <code>timeExpression</code> and falls
-     * into the business calendar working hours.
-     * 
-     * @param timeExpression time expression that is supported by business calendar implementation.
-     * @return date when given time expression will match in the future
+     * Calculates the future date matching the expression within valid business calendar hours.
+     *
+     * @param timeExpression the non-null ISO-8601 or custom cron/interval time expression
+     * @return the future {@link Date} when the time expression matches; never {@code null}
      */
     Date calculateBusinessTimeAsDate(String timeExpression);
 }
diff --git a/kogito-api/kogito-api/src/main/java/org/kie/kogito/event/EventPublisher.java b/kogito-api/kogito-api/src/main/java/org/kie/kogito/event/EventPublisher.java
index 8a28f56d81b..750c802866a 100644
--- a/kogito-api/kogito-api/src/main/java/org/kie/kogito/event/EventPublisher.java
+++ b/kogito-api/kogito-api/src/main/java/org/kie/kogito/event/EventPublisher.java
@@ -21,13 +21,11 @@ package org.kie.kogito.event;
 import java.util.Collection;
 
 /**
- * Responsible for publishing events for consumption to the "outside world"
- * 
- * Depending on the implementation it can be to push over the wire or use an
- * in memory queue to notify other parties about particular events.
- * 
- * In case any filtering needs to take place, this is where it should happen.
+ * <b>Event Publisher</b> extension point.
  *
+ * <p>
+ * Publishes workflow engine lifecycle events (such as process instance state changes, user task events,
+ * and definition updates) for consumption to the "outside world".
  */
 public interface EventPublisher {
 
@@ -36,17 +34,16 @@ public interface EventPublisher {
     String PROCESS_DEFINITIONS_TOPIC_NAME = "kogito-processdefinitions-events";
 
     /**
-     * Publishes individual event
-     * 
-     * @param event event to be published
+     * Publishes a single workflow data event.
+     *
+     * @param event the non-null {@link DataEvent} to publish
      */
     void publish(DataEvent<?> event);
 
     /**
-     * Publish collection of events. It's up to implementation to publish them
-     * individually or as complete collection.
-     * 
-     * @param events events to be published
+     * Publishes a collection of workflow data events.
+     *
+     * @param events the non-null {@link Collection} of {@link DataEvent} instances to publish
      */
     void publish(Collection<DataEvent<?>> events);
 }
diff --git a/kogito-api/kogito-api/src/main/java/org/kie/kogito/internal/process/workitem/KogitoWorkItemHandler.java b/kogito-api/kogito-api/src/main/java/org/kie/kogito/internal/process/workitem/KogitoWorkItemHandler.java
index 3f131a46081..734bb63941a 100644
--- a/kogito-api/kogito-api/src/main/java/org/kie/kogito/internal/process/workitem/KogitoWorkItemHandler.java
+++ b/kogito-api/kogito-api/src/main/java/org/kie/kogito/internal/process/workitem/KogitoWorkItemHandler.java
@@ -24,45 +24,94 @@ import java.util.Set;
 
 import org.kie.kogito.Application;
 
+/**
+ * <b>Work Item Handler</b> extension point.
+ *
+ * <p>
+ * Defines the contract for executing custom business logic when a BPMN Custom Task
+ * is reached by the workflow engine. Implementations can execute synchronously or initiate asynchronous
+ * execution and complete at a later time via the work item manager.
+ */
 public interface KogitoWorkItemHandler {
 
     /**
-     * This will allow access other part of the system.
-     * 
-     * @return
+     * Returns the {@link Application} context associated with this handler.
+     *
+     * @return the associated {@link Application} instance, or {@code null} if unassigned
      */
     Application getApplication();
 
+    /**
+     * Sets the {@link Application} context for this handler.
+     *
+     * @param app the {@link Application} context to associate
+     */
     void setApplication(Application app);
 
     /**
-     * Returns name that it should be registered with, by default simple class name;
+     * Returns the unique task name this handler is bound to in BPMN definitions.
      *
-     * @return name that should this handler be registered with
+     * @return the non-null task name identifying this handler; defaults to the simple class name
      */
     default String getName() {
         return getClass().getSimpleName();
     }
 
-    /*
-     * Transition to another phase from initial
+    /**
+     * Transitions a work item from its current lifecycle phase to the target phase.
+     *
+     * @param manager the non-null work item manager governing the execution
+     * @param workItem the non-null work item instance undergoing phase transition
+     * @param transition the non-null requested phase transition
+     * @return an {@link Optional} containing the next chained transition token, or {@link Optional#empty()} when execution completes
      */
     Optional<WorkItemTransition> transitionToPhase(KogitoWorkItemManager manager, KogitoWorkItem workItem, WorkItemTransition transition);
 
+    /**
+     * Returns the set of allowed target phase transitions from the specified phase status.
+     *
+     * @param phaseStatus the non-null current phase status
+     * @return an unmodifiable {@link Set} of allowed transition phase identifiers
+     */
     Set<String> allowedTransitions(String phaseStatus);
 
+    /**
+     * Creates a new work item phase transition token.
+     *
+     * @param phaseId the non-null target phase identifier
+     * @param phaseStatus the status of the phase
+     * @param map the data payload associated with the transition
+     * @param policy optional security or execution policies
+     * @return a new non-null {@link WorkItemTransition} token
+     */
     WorkItemTransition newTransition(String phaseId, String phaseStatus, Map<String, Object> map, Policy... policy);
 
     /**
-     * The given work item should be activate.
+     * Creates the initial starting transition token when a work item is activated.
      *
-     * @param workItem the work item that should be executed
-     * @param manager the manager that requested the work item to be executed
+     * @param data initial input data parameters passed from the task node
+     * @param policies optional execution policies
+     * @return a new non-null starting {@link WorkItemTransition} token
      */
     WorkItemTransition startingTransition(Map<String, Object> data, Policy... policies);
 
+    /**
+     * Creates a completion transition token for this work item.
+     *
+     * @param phaseStatus the target phase status upon completion
+     * @param data output data results to be mapped back to process variables
+     * @param policies optional execution policies
+     * @return a new non-null completion {@link WorkItemTransition} token
+     */
     WorkItemTransition completeTransition(String phaseStatus, Map<String, Object> data, Policy... policies);
 
+    /**
+     * Creates an abort transition token when a work item is cancelled or terminated.
+     *
+     * @param phaseStatus the target phase status upon abort
+     * @param policies optional execution policies
+     * @return a new non-null abort {@link WorkItemTransition} token
+     */
     WorkItemTransition abortTransition(String phaseStatus, Policy... policies);
 
 }
diff --git a/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/UserTaskAssignmentStrategy.java b/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/UserTaskAssignmentStrategy.java
index 47086286508..fd3527b570e 100644
--- a/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/UserTaskAssignmentStrategy.java
+++ b/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/UserTaskAssignmentStrategy.java
@@ -22,14 +22,32 @@ import java.util.Optional;
 
 import org.kie.kogito.auth.IdentityProvider;
 
+/**
+ * <b>User Task Assignment Strategy</b> extension point.
+ *
+ * <p>
+ * Computes user task assignments dynamically when human tasks are created or reassigned.
+ */
 public interface UserTaskAssignmentStrategy {
 
     static final String DEFAULT_NAME = "default";
 
+    /**
+     * Returns the unique strategy name identifying this assignment implementation.
+     *
+     * @return the non-null strategy identifier; defaults to the fully qualified class name
+     */
     default String getName() {
         return getClass().getName();
     }
 
+    /**
+     * Computes the assigned user for the specified user task instance.
+     *
+     * @param userTaskInstance the non-null user task instance requiring assignment
+     * @param identityProvider the non-null caller security identity
+     * @return an {@link Optional} containing the assigned username, or {@link Optional#empty()} if no assignment is resolved
+     */
     Optional<String> computeAssignment(UserTaskInstance userTaskInstance, IdentityProvider identityProvider);
 
 }
diff --git a/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/UserTaskEventListener.java b/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/UserTaskEventListener.java
index 2eb19f5b174..f0b2e791189 100644
--- a/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/UserTaskEventListener.java
+++ b/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/UserTaskEventListener.java
@@ -25,48 +25,110 @@ import org.kie.kogito.usertask.events.UserTaskDeadlineEvent;
 import org.kie.kogito.usertask.events.UserTaskStateEvent;
 import org.kie.kogito.usertask.events.UserTaskVariableEvent;
 
+/**
+ * <b>User Task Event Listener</b> extension point.
+ *
+ * <p>
+ * Listens for human task lifecycle events, including state transitions,
+ * assignment changes, input/output variable updates, comments, attachments, and deadline expirations.
+ */
 public interface UserTaskEventListener {
 
+    /**
+     * Invoked when a user task deadline or notification timer triggers.
+     *
+     * @param event the non-null {@link UserTaskDeadlineEvent}
+     */
     default void onUserTaskDeadline(UserTaskDeadlineEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when a user task undergoes a state transition.
+     *
+     * @param event the non-null {@link UserTaskStateEvent}
+     */
     default void onUserTaskState(UserTaskStateEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when a user task assignment or ownership changes.
+     *
+     * @param event the non-null {@link UserTaskAssignmentEvent}
+     */
     default void onUserTaskAssignment(UserTaskAssignmentEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when an input variable is assigned to or modified on a user task.
+     *
+     * @param event the non-null {@link UserTaskVariableEvent}
+     */
     default void onUserTaskInputVariable(UserTaskVariableEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when an output variable is set or modified on a user task.
+     *
+     * @param event the non-null {@link UserTaskVariableEvent}
+     */
     default void onUserTaskOutputVariable(UserTaskVariableEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when an attachment is added to a user task.
+     *
+     * @param event the non-null {@link UserTaskAttachmentEvent}
+     */
     default void onUserTaskAttachmentAdded(UserTaskAttachmentEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when an attachment is removed from a user task.
+     *
+     * @param event the non-null {@link UserTaskAttachmentEvent}
+     */
     default void onUserTaskAttachmentDeleted(UserTaskAttachmentEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when an attachment on a user task is updated.
+     *
+     * @param event the non-null {@link UserTaskAttachmentEvent}
+     */
     default void onUserTaskAttachmentChange(UserTaskAttachmentEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when a comment on a user task is updated.
+     *
+     * @param event the non-null {@link UserTaskCommentEvent}
+     */
     default void onUserTaskCommentChange(UserTaskCommentEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when a comment is added to a user task.
+     *
+     * @param event the non-null {@link UserTaskCommentEvent}
+     */
     default void onUserTaskCommentAdded(UserTaskCommentEvent event) {
         // nothing
     }
 
+    /**
+     * Invoked when a comment is deleted from a user task.
+     *
+     * @param event the non-null {@link UserTaskCommentEvent}
+     */
     default void onUserTaskCommentDeleted(UserTaskCommentEvent event) {
         // nothing
     }
diff --git a/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/lifecycle/UserTaskLifeCycle.java b/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/lifecycle/UserTaskLifeCycle.java
index d45e7d98aa6..f8417447fcb 100644
--- a/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/lifecycle/UserTaskLifeCycle.java
+++ b/kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/lifecycle/UserTaskLifeCycle.java
@@ -27,28 +27,100 @@ import org.kie.kogito.auth.IdentityProvider;
 import org.kie.kogito.jobs.descriptors.UserTaskInstanceJobDescription;
 import org.kie.kogito.usertask.UserTaskInstance;
 
+/**
+ * <b>User Task Lifecycle</b> extension point.
+ *
+ * <p>
+ * Defines the state machine, valid transition paths, and execution hooks governing Human Task instances.
+ */
 public interface UserTaskLifeCycle {
 
+    /**
+     * Returns the transition identifier used to activate a newly created user task.
+     *
+     * @return the non-null starting transition identifier
+     */
     String startTransition();
 
+    /**
+     * Returns the transition identifier used for task reassignment.
+     *
+     * @return the non-null reassignment transition identifier
+     */
     String reassignTransition();
 
+    /**
+     * Returns the transition identifier used for task abort.
+     *
+     * @return the non-null abort transition identifier
+     */
     String abortTransition();
 
+    /**
+     * Executes a state transition on the target user task instance.
+     *
+     * @param userTaskInstance the non-null user task instance undergoing transition
+     * @param transition the non-null transition token defining source, target, and payload data
+     * @param identity the non-null caller identity requesting the transition
+     * @return an {@link Optional} containing a chained follow-up transition token, or {@link Optional#empty()} when complete
+     * @throws UserTaskTransitionException if the requested transition is invalid from the current task state
+     */
     Optional<UserTaskTransitionToken> transition(UserTaskInstance userTaskInstance, UserTaskTransitionToken transition, IdentityProvider identity);
 
+    /**
+     * Creates a new transition token for the specified transition ID, current task instance state, and data payload.
+     *
+     * @param transitionId the non-null transition identifier
+     * @param userTaskInstance the non-null target task instance
+     * @param data the data parameters to include in the transition
+     * @return a new non-null {@link UserTaskTransitionToken}
+     */
     UserTaskTransitionToken newTransitionToken(String transitionId, UserTaskInstance userTaskInstance, Map<String, Object> data);
 
+    /**
+     * Creates an optional reassignment transition token.
+     *
+     * @param defaultUserTaskInstance the non-null user task instance
+     * @param data data parameters including the target assignee
+     * @return an {@link Optional} containing the reassignment transition token, or {@link Optional#empty()} if unsupported
+     */
     default Optional<UserTaskTransitionToken> newReassignmentTransitionToken(UserTaskInstance defaultUserTaskInstance, Map<String, Object> data) {
         return Optional.empty();
     }
 
+    /**
+     * Creates a completion transition token for this user task.
+     *
+     * @param userTaskInstance the non-null target user task instance
+     * @param data output data results to set on the completed task
+     * @return a new non-null completion {@link UserTaskTransitionToken}
+     */
     UserTaskTransitionToken newCompleteTransitionToken(UserTaskInstance userTaskInstance, Map<String, Object> data);
 
+    /**
+     * Creates an abort transition token for this user task.
+     *
+     * @param userTaskInstance the non-null target user task instance
+     * @param data optional abort metadata
+     * @return a new non-null abort {@link UserTaskTransitionToken}
+     */
     UserTaskTransitionToken newAbortTransitionToken(UserTaskInstance userTaskInstance, Map<String, Object> data);
 
+    /**
+     * Returns all valid target transitions allowed from the current state of the user task instance for the specified identity.
+     *
+     * @param ut the non-null target user task instance
+     * @param identity the non-null requesting user identity
+     * @return an unmodifiable {@link List} of allowed {@link UserTaskTransition} instances
+     */
     List<UserTaskTransition> allowedTransitions(UserTaskInstance ut, IdentityProvider identity);
 
+    /**
+     * Handles timer-triggered deadlines and escalations for this user task instance.
+     *
+     * @param jobDescription the non-null timer job descriptor
+     * @param userTaskInstance the non-null associated user task instance
+     */
     default void handleTimer(UserTaskInstanceJobDescription jobDescription, UserTaskInstance userTaskInstance) {
 
     }


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@kie.apache.org
For additional commands, e-mail: commits-help@kie.apache.org