From cb39d27dd0b6fe6bd1e57b074a79819b6f75605d Mon Sep 17 00:00:00 2001
From: leif stawnyczy <leifstawnyczy@leifs-mbp.home>
Date: Fri, 8 Mar 2024 09:38:50 -0500
Subject: [PATCH] updating documentation

---
 .../java/ca/uhn/fhir/batch2/package-info.java | 34 +++++++++++++++++--
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/hapi-fhir-storage-batch2/src/main/java/ca/uhn/fhir/batch2/package-info.java b/hapi-fhir-storage-batch2/src/main/java/ca/uhn/fhir/batch2/package-info.java
index 49a7bbb12de..c699d6ef6ed 100644
--- a/hapi-fhir-storage-batch2/src/main/java/ca/uhn/fhir/batch2/package-info.java
+++ b/hapi-fhir-storage-batch2/src/main/java/ca/uhn/fhir/batch2/package-info.java
@@ -48,11 +48,39 @@
  *
  * Job and chunk processing follow state machines described {@link hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_batch/batch2_states.md}
  * Chunks have a simple {@link ca.uhn.fhir.batch2.model.WorkChunkStatusEnum state system} with states
- * QUEUED, IN_PROGRESS, ERRORED, FAILED, COMPLETED.
- * The initial state is QUEUED, and the final states are FAILED, and COMPLETED:
+ * READY, QUEUED, IN_PROGRESS, ERRORED, FAILED, COMPLETED.
+ * The initial state is READY, and the final states are FAILED, and COMPLETED.
+ *
+ * There are 2 primary systems in play during Batch2 Jobs. A Maintenance Job and the Batch2 Job Notification topic.
+ *
+ * <h>The Maintenance Job</h>
+ *
+ * This runs every minute and does the following:
  *
  * <ul>
- *    <li> Chunks are created QUEUED (NB - should be READY or WAITING) and notification is posted to the channel for non-gated steps.</li>
+ *     <li>Moves READY work chunks to QUEUE and publishes it to the Batch2 Notification topic</li>
+ *     <li>Calculates job progress (% of workchunks in complete status).</li>
+ *     <li>If the job is finished, purges any left over work chunks.</li>
+ *     <li>Cleans up any complete, failed, or cancelled jobs.</li>
+ *     <li>Moves any gated jobs onto their next step.</li>
+ *     <li>If the final step of a (gated) job is a reduction step, a reduction step execution will be triggered.</li>
+ * </ul>
+ *
+ * <h>Processing the Messages</h>
+ *
+ * <ul>
+ *     <li>Change the work chunk from QUEUED to IN_PROGRESS</li>
+ *     <li>Change the Job Instance status from QUEUED to IN_PROGRESS</li>
+ *     <li>If the Job Instance is cancelled, change the status to CANCELLED and abort processing</li>
+ *     <li>If the step creates new work chunks, each work chunk will be created in the READY state</li>
+ *     <li>If the step succeeds, the work chunk status is changed from IN_PROGRESS to COMPLETE</li>
+ *     <li>If the step fails, the work chunk status is changed from IN_PROGRESS to either ERRORED or FAILED depending on the severity of the error</li>
+ * </ul>
+ *
+ * <h>The job lifecycle</h>
+ *
+ * <ul>
+ *    <li> Chunks are created READY (NB - should be READY or WAITING) and notification is posted to the channel for non-gated steps.</li>
  *    <li>
  *       Workers receive a notification and advance QUEUED->IN_PROGRESS.
  *       {@link ca.uhn.fhir.batch2.api.IWorkChunkPersistence#onWorkChunkDequeue(String)}