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 <[email protected]> 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 >= 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: [email protected] For additional commands, e-mail: [email protected]
