Assorted Changes (#373)

* move `DBOS` `registerLifecycleListener`, `registerWorkflow`,
`getRegisteredWorkflow`, `getRegisteredWorkflows`,
`getRegisteredWorkflowInstances`, `getExternalState` and
`upsertExternalState` to `DBOSIntegration`
* Remove `@Step.retriesAllowed`
* Validate StepOptions
* fix/improve javadocs

---------

Co-authored-by: Copilot <copilot@github.com>

Author: devhawk

transact-spring-boot-starter/src/main/java/dev/dbos/transact/spring/DBOSWorkflowRegistrar.java

@@ -101,6 +101,7 @@ public void afterSingletonsInstantiated() {
       beanFactory = configurableCtx.getBeanFactory();
     }
 
+    var integration = dbos.integration();
     for (Map.Entry<Class<?>, List<String>> entry : beanNamesByClass.entrySet()) {
       Class<?> targetClass = entry.getKey();
       List<String> beanNames = entry.getValue();
@@ -128,7 +129,7 @@ public void afterSingletonsInstantiated() {
             }
             var wfTag = method.getAnnotation(Workflow.class);
             if (wfTag != null) {
-              dbos.registerWorkflow(wfTag, rawTarget, method, registerName);
+              integration.registerWorkflow(wfTag, rawTarget, method, registerName);
             }
           }
         }

transact-spring-boot-starter/src/test/java/dev/dbos/transact/spring/DBOSWorkflowRegistrarTest.java

@@ -10,6 +10,7 @@
 import static org.mockito.Mockito.when;
 
 import dev.dbos.transact.DBOS;
+import dev.dbos.transact.internal.DBOSIntegration;
 import dev.dbos.transact.workflow.Step;
 import dev.dbos.transact.workflow.Workflow;
 
@@ -73,6 +74,9 @@ private static ConfigurableApplicationContext mockCtx(
   @Test
   void registersBeansWithWorkflowMethods() throws Exception {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "workflowBean");
     var bean = new BeanWithWorkflow();
@@ -86,25 +90,31 @@ void registersBeansWithWorkflowMethods() throws Exception {
     var wfTag = method.getAnnotation(Workflow.class);
     assertNotNull(wfTag);
 
-    verify(mockDbos).registerWorkflow(eq(wfTag), eq(bean), eq(method), eq(null));
+    verify(mockIntegration).registerWorkflow(eq(wfTag), eq(bean), eq(method), eq(null));
   }
 
   @Test
   void skipsBeansWithoutWorkflowMethods() {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "plainBean");
 
     when(mockCtx.getBean("plainBean")).thenReturn(new BeanWithoutWorkflow());
 
     new DBOSWorkflowRegistrar(mockDbos, mockCtx).afterSingletonsInstantiated();
 
-    verify(mockDbos, never()).registerWorkflow(any(), any(), any(), any());
+    verify(mockIntegration, never()).registerWorkflow(any(), any(), any(), any());
   }
 
   @Test
   void skipsBeansThatThrowOnLookup() {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "badBean");
 
@@ -113,12 +123,15 @@ void skipsBeansThatThrowOnLookup() {
     // should complete without throwing
     new DBOSWorkflowRegistrar(mockDbos, mockCtx).afterSingletonsInstantiated();
 
-    verify(mockDbos, never()).registerWorkflow(any(), any(), any(), any());
+    verify(mockIntegration, never()).registerWorkflow(any(), any(), any(), any());
   }
 
   @Test
   void processesMultipleBeans() {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "wfBean", "plainBean");
     var wfBean = new BeanWithWorkflow();
@@ -129,13 +142,16 @@ void processesMultipleBeans() {
 
     new DBOSWorkflowRegistrar(mockDbos, mockCtx).afterSingletonsInstantiated();
 
-    verify(mockDbos).registerWorkflow(any(), eq(wfBean), any(), eq(null));
-    verify(mockDbos, never()).registerWorkflow(any(), eq(plainBean), any(), any());
+    verify(mockIntegration).registerWorkflow(any(), eq(wfBean), any(), eq(null));
+    verify(mockIntegration, never()).registerWorkflow(any(), eq(plainBean), any(), any());
   }
 
   @Test
   void registersMultipleBeansOfSameClassUsingBeanNames() {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "primaryBean", "secondaryBean");
     var primaryBean = new BeanWithWorkflow();
@@ -153,13 +169,16 @@ void registersMultipleBeansOfSameClassUsingBeanNames() {
 
     new DBOSWorkflowRegistrar(mockDbos, mockCtx).afterSingletonsInstantiated();
 
-    verify(mockDbos).registerWorkflow(any(), eq(primaryBean), any(), eq(null));
-    verify(mockDbos).registerWorkflow(any(), eq(secondaryBean), any(), eq("secondaryBean"));
+    verify(mockIntegration).registerWorkflow(any(), eq(primaryBean), any(), eq(null));
+    verify(mockIntegration).registerWorkflow(any(), eq(secondaryBean), any(), eq("secondaryBean"));
   }
 
   @Test
   void beanWithBothWorkflowAndStep_onlyRegistersWorkflow() throws Exception {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "mixedBean");
     var bean = new BeanWithWorkflowAndStep();
@@ -169,15 +188,18 @@ void beanWithBothWorkflowAndStep_onlyRegistersWorkflow() throws Exception {
     new DBOSWorkflowRegistrar(mockDbos, mockCtx).afterSingletonsInstantiated();
 
     var method = BeanWithWorkflowAndStep.class.getMethod("myWorkflow");
-    verify(mockDbos).registerWorkflow(any(), eq(bean), eq(method), eq(null));
-    verify(mockDbos, never())
+    verify(mockIntegration).registerWorkflow(any(), eq(bean), eq(method), eq(null));
+    verify(mockIntegration, never())
         .registerWorkflow(
             any(), any(), eq(BeanWithWorkflowAndStep.class.getMethod("myStep")), any());
   }
 
   @Test
   void beanLookupFailureMidScan_doesNotPreventOtherBeanRegistration() {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "badBean", "goodBean");
     var goodBean = new BeanWithWorkflow();
@@ -187,12 +209,15 @@ void beanLookupFailureMidScan_doesNotPreventOtherBeanRegistration() {
 
     new DBOSWorkflowRegistrar(mockDbos, mockCtx).afterSingletonsInstantiated();
 
-    verify(mockDbos).registerWorkflow(any(), eq(goodBean), any(), eq(null));
+    verify(mockIntegration).registerWorkflow(any(), eq(goodBean), any(), eq(null));
   }
 
   @Test
   void inheritedWorkflowMethods_areDetectedAndRegistered() throws Exception {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "derivedBean");
     var bean = new DerivedWorkflowBean();
@@ -202,12 +227,15 @@ void inheritedWorkflowMethods_areDetectedAndRegistered() throws Exception {
     new DBOSWorkflowRegistrar(mockDbos, mockCtx).afterSingletonsInstantiated();
 
     var method = BaseWorkflowBean.class.getDeclaredMethod("baseWorkflow");
-    verify(mockDbos).registerWorkflow(any(), eq(bean), eq(method), eq(null));
+    verify(mockIntegration).registerWorkflow(any(), eq(bean), eq(method), eq(null));
   }
 
   @Test
   void nonSingletonBeanWithWorkflow_throwsIllegalStateException() {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "prototypeBean");
 
@@ -222,6 +250,9 @@ void nonSingletonBeanWithWorkflow_throwsIllegalStateException() {
   @Test
   void nonSingletonBeanWithStep_throwsIllegalStateException() {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "prototypeBean");
 
@@ -236,6 +267,9 @@ void nonSingletonBeanWithStep_throwsIllegalStateException() {
   @Test
   void registersMultipleBeansOfSameClassWithBeanNamesWhenNoneIsPrimary() {
     var mockDbos = mock(DBOS.class);
+    var mockIntegration = mock(DBOSIntegration.class);
+    when(mockDbos.integration()).thenReturn(mockIntegration);
+
     var mockBeanFactory = mock(ConfigurableListableBeanFactory.class);
     var mockCtx = mockCtx(mockBeanFactory, "beanA", "beanB");
     var beanA = new BeanWithWorkflow();
@@ -253,7 +287,7 @@ void registersMultipleBeansOfSameClassWithBeanNamesWhenNoneIsPrimary() {
 
     new DBOSWorkflowRegistrar(mockDbos, mockCtx).afterSingletonsInstantiated();
 
-    verify(mockDbos).registerWorkflow(any(), eq(beanA), any(), eq("beanA"));
-    verify(mockDbos).registerWorkflow(any(), eq(beanB), any(), eq("beanB"));
+    verify(mockIntegration).registerWorkflow(any(), eq(beanA), any(), eq("beanA"));
+    verify(mockIntegration).registerWorkflow(any(), eq(beanB), any(), eq("beanB"));
   }
 }

transact/src/main/java/dev/dbos/transact/DBOS.java

@@ -2,11 +2,8 @@
 
 import dev.dbos.transact.config.DBOSConfig;
 import dev.dbos.transact.context.DBOSContext;
-import dev.dbos.transact.database.ExternalState;
 import dev.dbos.transact.execution.DBOSExecutor;
 import dev.dbos.transact.execution.DBOSLifecycleListener;
-import dev.dbos.transact.execution.RegisteredWorkflow;
-import dev.dbos.transact.execution.RegisteredWorkflowInstance;
 import dev.dbos.transact.execution.ThrowingRunnable;
 import dev.dbos.transact.execution.ThrowingSupplier;
 import dev.dbos.transact.internal.DBOSIntegration;
@@ -35,7 +32,6 @@
 import java.time.Duration;
 import java.time.Instant;
 import java.util.Arrays;
-import java.util.Collection;
 import java.util.HashSet;
 import java.util.Iterator;
 import java.util.List;
@@ -66,7 +62,9 @@ public class DBOS implements AutoCloseable {
   private final Set<DBOSLifecycleListener> lifecycleRegistry = ConcurrentHashMap.newKeySet();
   private final DBOSConfig config;
   private final AtomicReference<DBOSExecutor> dbosExecutor = new AtomicReference<>();
-  private final DBOSIntegration integration = new DBOSIntegration(dbosExecutor::get);
+  private final DBOSIntegration integration =
+      new DBOSIntegration(
+          dbosExecutor::get, this::registerLifecycleListener, this::registerWorkflow);
 
   private AlertHandler alertHandler;
 
@@ -132,7 +130,7 @@ public static String version() {
    *
    * @param listener
    */
-  public void registerLifecycleListener(@NonNull DBOSLifecycleListener listener) {
+  private void registerLifecycleListener(@NonNull DBOSLifecycleListener listener) {
     if (dbosExecutor.get() != null) {
       throw new IllegalStateException("Cannot register lifecycle listener after DBOS is launched");
     }
@@ -226,7 +224,7 @@ public void registerQueues(@NonNull Queue... queues) {
    * @param instanceName optional instance name for the workflow (can be null)
    * @throws IllegalStateException if called after DBOS is launched
    */
-  public void registerWorkflow(
+  private void registerWorkflow(
       @NonNull Workflow wfTag,
       @NonNull Object target,
       @NonNull Method method,
@@ -345,13 +343,7 @@ private DBOSExecutor ensureLaunched(String caller) {
    * @param duration amount of time to sleep
    */
   public void sleep(@NonNull Duration duration) {
-    if (!DBOSContext.inWorkflow()) {
-      try {
-        Thread.sleep(duration.toMillis());
-      } catch (InterruptedException e) {
-        Thread.currentThread().interrupt();
-      }
-    } else if (DBOSContext.inStep()) {
+    if (!DBOSContext.inWorkflow() || DBOSContext.inStep()) {
       try {
         Thread.sleep(duration.toMillis());
       } catch (InterruptedException e) {
@@ -896,28 +888,29 @@ public void applySchedules(@NonNull WorkflowSchedule... schedules) {
     ensureLaunched("applySchedules").applySchedules(Arrays.asList(schedules));
   }
 
-  // /**
-  //  * Enqueue all executions of a schedule that would have run between {@code start} (exclusive)
-  // and
-  //  * {@code end} (exclusive). Uses the same deterministic workflow IDs as the live scheduler, so
-  //  * already-executed times are skipped.
-  //  *
-  //  * @param scheduleName name of an existing schedule
-  //  * @param start start of the backfill window (exclusive)
-  //  * @param end end of the backfill window (exclusive)
-  //  * @return handles to the enqueued executions
-  //  */
+  /**
+   * Enqueue all executions of a schedule that would have run between {@code start} (exclusive) and
+   * {@code end} (exclusive).
+   *
+   * <p>Uses the same deterministic workflow IDs as the live scheduler, so already-executed times
+   * are skipped.
+   *
+   * @param scheduleName name of an existing schedule
+   * @param start start of the backfill window (exclusive)
+   * @param end end of the backfill window (exclusive)
+   * @return handles to the enqueued executions
+   */
   public @NonNull List<WorkflowHandle<Object, Exception>> backfillSchedule(
       @NonNull String scheduleName, @NonNull Instant start, @NonNull Instant end) {
     return ensureLaunched("backfillSchedule").backfillSchedule(scheduleName, start, end);
   }
 
-  // /**
-  //  * Immediately enqueue the scheduled workflow at the current time.
-  //  *
-  //  * @param scheduleName name of an existing schedule
-  //  * @return handle to the enqueued execution
-  //  */
+  /**
+   * Immediately enqueue the scheduled workflow at the current time.
+   *
+   * @param scheduleName name of an existing schedule
+   * @return handle to the enqueued execution
+   */
   public <T, E extends Exception> @NonNull WorkflowHandle<T, E> triggerSchedule(
       @NonNull String scheduleName) {
     return ensureLaunched("triggerSchedule").triggerSchedule(scheduleName);
@@ -1016,76 +1009,6 @@ public void setWorkflowDelay(@NonNull String workflowId, @NonNull Instant delayU
     return ensureLaunched("listWorkflowSteps").listWorkflowSteps(workflowId, true, limit, offset);
   }
 
-  /**
-   * Get all workflows registered with DBOS.
-   *
-   * @return list of all registered workflow methods
-   */
-  public @NonNull Collection<RegisteredWorkflow> getRegisteredWorkflows() {
-    return ensureLaunched("getRegisteredWorkflows").getRegisteredWorkflows();
-  }
-
-  /**
-   * Finds a registered workflow by its workflow name, class name, and instance name.
-   *
-   * @param workflowName the name of the workflow
-   * @param className the name of the class containing the workflow
-   * @return an Optional containing the RegisteredWorkflow if found, otherwise empty
-   */
-  public Optional<RegisteredWorkflow> getRegisteredWorkflow(
-      @NonNull String workflowName, @NonNull String className) {
-    return getRegisteredWorkflow(workflowName, className, "");
-  }
-
-  /**
-   * Finds a registered workflow by its workflow name, class name, and instance name.
-   *
-   * @param workflowName the name of the workflow
-   * @param className the name of the class containing the workflow
-   * @param instanceName the name of the workflow instance
-   * @return an Optional containing the RegisteredWorkflow if found, otherwise empty
-   */
-  public Optional<RegisteredWorkflow> getRegisteredWorkflow(
-      @NonNull String workflowName, @NonNull String className, @NonNull String instanceName) {
-    return ensureLaunched("getRegisteredWorkflow")
-        .getRegisteredWorkflow(workflowName, className, instanceName);
-  }
-
-  /**
-   * Get all workflow classes registered with DBOS.
-   *
-   * @return list of all class instances containing registered workflow methods
-   */
-  public @NonNull Collection<RegisteredWorkflowInstance> getRegisteredWorkflowInstances() {
-    return ensureLaunched("getRegisteredWorkflowInstances").getRegisteredWorkflowInstances();
-  }
-
-  /**
-   * Get a system database record stored by an external service A unique value is stored per
-   * combination of service, workflowName, and key
-   *
-   * @param service Identity of the service maintaining the record
-   * @param workflowName Fully qualified name of the workflow
-   * @param key Key assigned within the service+workflow
-   * @return Optional containing the value associated with the service+workflow+key combination, or
-   *     empty if not found
-   */
-  public Optional<ExternalState> getExternalState(String service, String workflowName, String key) {
-    return ensureLaunched("getExternalState").getExternalState(service, workflowName, key);
-  }
-
-  /**
-   * Insert or update a system database record stored by an external service A timestamped unique
-   * value is stored per combination of service, workflowName, and key
-   *
-   * @param state ExternalState containing the service, workflow, key, and value to store
-   * @return Value associated with the service+workflow+key combination, in case the stored value
-   *     already had a higher version or timestamp
-   */
-  public ExternalState upsertExternalState(ExternalState state) {
-    return ensureLaunched("upsertExternalState").upsertExternalState(state);
-  }
-
   /**
    * Marks a breaking change within a workflow. Returns true for new workflows (i.e. workflow sthat
    * reach this point in the workflow after the breaking change was created) and false for old