Merge branch 'main' of https://github.com/serverlessworkflow/sdk-java.git into main

fjtirado · fjtirado · commit 9ac84cad845e · 2025-07-09T14:35:18.000+02:00
diff --git a/api/src/main/java/io/serverlessworkflow/api/WorkflowFormat.java b/api/src/main/java/io/serverlessworkflow/api/WorkflowFormat.java
@@ -18,24 +18,56 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import java.nio.file.Path;
 
+/**
+ * Enum representing the supported formats for Serverless Workflow definitions.
+ *
+ * <p>Provides utility methods to determine the format based on file name or path, and to access the
+ * corresponding {@link ObjectMapper} for serialization and deserialization.
+ */
 public enum WorkflowFormat {
+  /** JSON format for workflow definitions. */
   JSON(ObjectMapperFactory.jsonMapper()),
+
+  /** YAML format for workflow definitions. */
   YAML(ObjectMapperFactory.yamlMapper());
 
   private final ObjectMapper mapper;
 
+  /**
+   * Determines the {@link WorkflowFormat} from a file path by inspecting its file extension.
+   *
+   * @param path the file path to inspect
+   * @return the corresponding {@link WorkflowFormat}
+   */
   public static WorkflowFormat fromPath(Path path) {
     return fromFileName(path.getFileName().toString());
   }
 
+  /**
+   * Determines the {@link WorkflowFormat} from a file name by inspecting its extension. Returns
+   * {@code JSON} if the file name ends with ".json", otherwise returns {@code YAML}.
+   *
+   * @param fileName the file name to inspect
+   * @return the corresponding {@link WorkflowFormat}
+   */
   public static WorkflowFormat fromFileName(String fileName) {
     return fileName.endsWith(".json") ? JSON : YAML;
   }
 
+  /**
+   * Constructs a {@link WorkflowFormat} with the specified {@link ObjectMapper}.
+   *
+   * @param mapper the object mapper for this format
+   */
   private WorkflowFormat(ObjectMapper mapper) {
     this.mapper = mapper;
   }
 
+  /**
+   * Returns the {@link ObjectMapper} associated with this workflow format.
+   *
+   * @return the object mapper for this format
+   */
   public ObjectMapper mapper() {
     return mapper;
   }
diff --git a/api/src/main/java/io/serverlessworkflow/api/WorkflowReader.java b/api/src/main/java/io/serverlessworkflow/api/WorkflowReader.java
@@ -23,52 +23,141 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 
+/** Utility class for reading and parsing Serverless Workflow definitions from various sources. */
 public class WorkflowReader {
 
+  /**
+   * Reads a workflow from an {@link InputStream} using the specified format.
+   *
+   * @param input the input stream containing the workflow definition
+   * @param format the workflow format
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflow(InputStream input, WorkflowFormat format) throws IOException {
     return defaultReader().read(input, format);
   }
 
+  /**
+   * Reads a workflow from a {@link Reader} using the specified format.
+   *
+   * @param input the reader containing the workflow definition
+   * @param format the workflow format
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflow(Reader input, WorkflowFormat format) throws IOException {
     return defaultReader().read(input, format);
   }
 
+  /**
+   * Reads a workflow from a byte array using the specified format.
+   *
+   * @param input the byte array containing the workflow definition
+   * @param format the workflow format
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflow(byte[] input, WorkflowFormat format) throws IOException {
     return defaultReader().read(input, format);
   }
 
+  /**
+   * Reads a workflow from a file path, inferring the format from the file extension.
+   *
+   * @param path the path to the workflow file
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflow(Path path) throws IOException {
     return readWorkflow(path, WorkflowFormat.fromPath(path), defaultReader());
   }
 
+  /**
+   * Reads a workflow from a file path using the specified format.
+   *
+   * @param path the path to the workflow file
+   * @param format the workflow format
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflow(Path path, WorkflowFormat format) throws IOException {
     return readWorkflow(path, format, defaultReader());
   }
 
+  /**
+   * Reads a workflow from a string using the specified format.
+   *
+   * @param input the string containing the workflow definition
+   * @param format the workflow format
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflowFromString(String input, WorkflowFormat format)
       throws IOException {
     return defaultReader().read(input, format);
   }
 
+  /**
+   * Reads a workflow from the classpath, inferring the format from the file name.
+   *
+   * @param classpath the classpath location of the workflow file
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflowFromClasspath(String classpath) throws IOException {
     return readWorkflowFromClasspath(classpath, defaultReader());
   }
 
+  /**
+   * Reads a workflow from the classpath using the specified class loader and format.
+   *
+   * @param classpath the classpath location of the workflow file
+   * @param cl the class loader to use
+   * @param format the workflow format
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflowFromClasspath(
       String classpath, ClassLoader cl, WorkflowFormat format) throws IOException {
     return readWorkflowFromClasspath(classpath, defaultReader());
   }
 
+  /**
+   * Reads a workflow from a file path using a custom reader.
+   *
+   * @param path the path to the workflow file
+   * @param reader the custom {@link WorkflowReaderOperations}
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflow(Path path, WorkflowReaderOperations reader)
       throws IOException {
     return readWorkflow(path, WorkflowFormat.fromPath(path), reader);
   }
 
+  /**
+   * Reads a workflow from a file path using the specified format and custom reader.
+   *
+   * @param path the path to the workflow file
+   * @param format the workflow format
+   * @param reader the custom {@link WorkflowReaderOperations}
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflow(
       Path path, WorkflowFormat format, WorkflowReaderOperations reader) throws IOException {
     return reader.read(Files.readAllBytes(path), format);
   }
 
+  /**
+   * Reads a workflow from the classpath using a custom reader.
+   *
+   * @param classpath the classpath location of the workflow file
+   * @param reader the custom {@link WorkflowReaderOperations}
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs
+   */
   public static Workflow readWorkflowFromClasspath(
       String classpath, WorkflowReaderOperations reader) throws IOException {
     return readWorkflowFromClasspath(
@@ -78,6 +167,17 @@ public static Workflow readWorkflowFromClasspath(
         reader);
   }
 
+  /**
+   * Reads a workflow from the classpath using the specified class loader, format, and custom
+   * reader.
+   *
+   * @param classpath the classpath location of the workflow file
+   * @param cl the class loader to use
+   * @param format the workflow format
+   * @param reader the custom {@link WorkflowReaderOperations}
+   * @return the parsed {@link Workflow}
+   * @throws IOException if an I/O error occurs or the resource is not found
+   */
   public static Workflow readWorkflowFromClasspath(
       String classpath, ClassLoader cl, WorkflowFormat format, WorkflowReaderOperations reader)
       throws IOException {
@@ -89,10 +189,20 @@ public static Workflow readWorkflowFromClasspath(
     }
   }
 
+  /**
+   * Returns a {@link WorkflowReaderOperations} instance that performs no validation.
+   *
+   * @return a no-validation reader
+   */
   public static WorkflowReaderOperations noValidation() {
     return NoValidationHolder.instance;
   }
 
+  /**
+   * Returns a {@link WorkflowReaderOperations} instance that performs validation.
+   *
+   * @return a validation reader
+   */
   public static WorkflowReaderOperations validation() {
     return ValidationHolder.instance;
   }
@@ -105,6 +215,11 @@ private static class ValidationHolder {
     private static final WorkflowReaderOperations instance = new ValidationReader();
   }
 
+  /**
+   * Returns the default {@link WorkflowReaderOperations} instance (no validation).
+   *
+   * @return the default reader
+   */
   private static WorkflowReaderOperations defaultReader() {
     return NoValidationHolder.instance;
   }
diff --git a/api/src/main/java/io/serverlessworkflow/api/WorkflowWriter.java b/api/src/main/java/io/serverlessworkflow/api/WorkflowWriter.java
@@ -23,34 +23,89 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 
+/**
+ * Utility class for writing Serverless Workflow definitions to various outputs and formats.
+ *
+ * <p>This class provides static methods to serialize {@link Workflow} objects to files, streams,
+ * writers, byte arrays, or strings in either JSON or YAML format. The format is determined by the
+ * {@link WorkflowFormat} parameter or inferred from file extensions.
+ */
 public class WorkflowWriter {
 
+  /**
+   * Writes a {@link Workflow} to the given {@link OutputStream} in the specified format.
+   *
+   * @param output the output stream to write the workflow to
+   * @param workflow the workflow object to serialize
+   * @param format the format to use (JSON or YAML)
+   * @throws IOException if an I/O error occurs during writing
+   */
   public static void writeWorkflow(OutputStream output, Workflow workflow, WorkflowFormat format)
       throws IOException {
     format.mapper().writeValue(output, workflow);
   }
 
+  /**
+   * Writes a {@link Workflow} to the given {@link Writer} in the specified format.
+   *
+   * @param output the writer to write the workflow to
+   * @param workflow the workflow object to serialize
+   * @param format the format to use (JSON or YAML)
+   * @throws IOException if an I/O error occurs during writing
+   */
   public static void writeWorkflow(Writer output, Workflow workflow, WorkflowFormat format)
       throws IOException {
     format.mapper().writeValue(output, workflow);
   }
 
+  /**
+   * Writes a {@link Workflow} to the specified file path, inferring the format from the file
+   * extension.
+   *
+   * @param output the file path to write the workflow to
+   * @param workflow the workflow object to serialize
+   * @throws IOException if an I/O error occurs during writing
+   */
   public static void writeWorkflow(Path output, Workflow workflow) throws IOException {
     writeWorkflow(output, workflow, WorkflowFormat.fromPath(output));
   }
 
+  /**
+   * Writes a {@link Workflow} to the specified file path in the given format.
+   *
+   * @param output the file path to write the workflow to
+   * @param workflow the workflow object to serialize
+   * @param format the format to use (JSON or YAML)
+   * @throws IOException if an I/O error occurs during writing
+   */
   public static void writeWorkflow(Path output, Workflow workflow, WorkflowFormat format)
       throws IOException {
     try (OutputStream out = Files.newOutputStream(output)) {
       writeWorkflow(out, workflow, format);
     }
   }
 
+  /**
+   * Serializes a {@link Workflow} to a string in the specified format.
+   *
+   * @param workflow the workflow object to serialize
+   * @param format the format to use (JSON or YAML)
+   * @return the serialized workflow as a string
+   * @throws IOException if an error occurs during serialization
+   */
   public static String workflowAsString(Workflow workflow, WorkflowFormat format)
       throws IOException {
     return format.mapper().writeValueAsString(workflow);
   }
 
+  /**
+   * Serializes a {@link Workflow} to a byte array in the specified format.
+   *
+   * @param workflow the workflow object to serialize
+   * @param format the format to use (JSON or YAML)
+   * @return the serialized workflow as a byte array
+   * @throws IOException if an error occurs during serialization
+   */
   public static byte[] workflowAsBytes(Workflow workflow, WorkflowFormat format)
       throws IOException {
     try (ByteArrayOutputStream out = new ByteArrayOutputStream()) {
@@ -59,5 +114,6 @@ public static byte[] workflowAsBytes(Workflow workflow, WorkflowFormat format)
     }
   }
 
+  // Private constructor to prevent instantiation
   private WorkflowWriter() {}
 }
