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 index 6868a6dc..b4401af0 100644 --- 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 index 5980dee6..3285cff4 100644 --- a/api/src/main/java/io/serverlessworkflow/api/WorkflowWriter.java +++ b/api/src/main/java/io/serverlessworkflow/api/WorkflowWriter.java @@ -23,22 +23,61 @@ import java.nio.file.Files; import java.nio.file.Path; +/** + * Utility class for writing Serverless Workflow definitions to various outputs and formats. + * + *
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)) { @@ -46,11 +85,27 @@ public static void writeWorkflow(Path output, Workflow workflow, WorkflowFormat } } + /** + * 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() {} }