Copilot commented on code in PR #7173:
URL: https://github.com/apache/incubator-kie/pull/7173#discussion_r4261948534
##########
kogito-api/kogito-api/src/main/java/org/kie/kogito/calendar/BusinessCalendar.java:
##########
@@ -21,27 +21,28 @@
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);
Review Comment:
The updated JavaDoc introduces stronger guarantees and specifics that aren’t
established by the interface contract: \"always >= 0\", \"non-null ISO-8601 or
custom cron/interval\", and \"never null\". Unless these are enforced (or
explicitly specified as requirements for implementations), the docs should be
softened back to implementation-defined wording (e.g., \"time expression
supported by the implementation\" and avoid absolute return guarantees).
##########
kogito-api/kogito-api/src/main/java/org/kie/kogito/usertask/lifecycle/UserTaskLifeCycle.java:
##########
@@ -27,28 +27,100 @@
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
Review Comment:
The JavaDoc promises \"an unmodifiable List\", but the signature doesn’t
enforce that and existing implementations may return a mutable list. If
immutability is intended as a hard contract, consider explicitly stating it as
a requirement for implementations (and ideally enforcing it where created).
Otherwise, remove \"unmodifiable\" to avoid overstating guarantees.
##########
kogito-api/kogito-api/src/main/java/org/kie/kogito/internal/process/workitem/KogitoWorkItemHandler.java:
##########
@@ -24,45 +24,94 @@
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
Review Comment:
Similar to the user task lifecycle API, this JavaDoc states the returned Set
is \"unmodifiable\" without any enforcement at the interface level. If
immutability is not guaranteed across implementations, please remove
\"unmodifiable\" or restate it as a recommendation/requirement for implementers.
##########
kie-api/src/main/java/org/kie/api/event/process/ProcessEventListener.java:
##########
@@ -21,122 +21,138 @@
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) { }
Review Comment:
The sentence \"Invoked when a process instance migration occurs across.\" is
grammatically incorrect/incomplete. Please rephrase (e.g., drop \"across\" or
clarify \"across versions/nodes/environments\") so the JavaDoc reads as a
complete sentence.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
