You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@kie.apache.org by "josedee (via GitHub)" <gi...@apache.org> on 2026/10/07 04:39:10 UTC

[PR] [incubator-kie#7172] JavaDoc for Common Workflow Extension Points [incubator-kie]

josedee opened a new pull request, #7173:
URL: https://github.com/apache/incubator-kie/pull/7173

   (no comment)


-- 
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: commits-unsubscribe@kie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


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


Re: [PR] [incubator-kie#7172] JavaDoc for Common Workflow Extension Points [incubator-kie]

Posted by "martinweiler (via GitHub)" <gi...@apache.org>.
martinweiler commented on PR #7173:
URL: https://github.com/apache/incubator-kie/pull/7173#issuecomment-6070796409

   The changes look good so far, but I haven't had the chance yet to check them for completeness. @josedee have you identified other extension points that need javadoc updates?


-- 
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: commits-unsubscribe@kie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


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


Re: [PR] [incubator-kie#7172] JavaDoc for Common Workflow Extension Points [incubator-kie]

Posted by "martinweiler (via GitHub)" <gi...@apache.org>.
martinweiler merged PR #7173:
URL: https://github.com/apache/incubator-kie/pull/7173


-- 
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: commits-unsubscribe@kie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


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


Re: [PR] [incubator-kie#7172] JavaDoc for Common Workflow Extension Points [incubator-kie]

Posted by "Copilot (via GitHub)" <gi...@apache.org>.
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 &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);

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: commits-unsubscribe@kie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


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