diff --git a/src/main/java/com/alibaba/compileflow/engine/FlowModel.java b/src/main/java/com/alibaba/compileflow/engine/FlowModel.java index 6e24c30..8a0f365 100644 --- a/src/main/java/com/alibaba/compileflow/engine/FlowModel.java +++ b/src/main/java/com/alibaba/compileflow/engine/FlowModel.java @@ -1,9 +1,15 @@ package com.alibaba.compileflow.engine; /** + * Represents a flow model abstraction in the CompileFlow Engine. + * This interface defines the fundamental structure for various types of flow models, + * enabling the engine to handle and process them accordingly. + * * @author wuxiang * @author yusu */ public interface FlowModel { + // No methods are defined in this interface, as it serves as a marker for flow model classes. + } diff --git a/src/main/java/com/alibaba/compileflow/engine/ProcessEngine.java b/src/main/java/com/alibaba/compileflow/engine/ProcessEngine.java index 0635edc..ea36f2a 100644 --- a/src/main/java/com/alibaba/compileflow/engine/ProcessEngine.java +++ b/src/main/java/com/alibaba/compileflow/engine/ProcessEngine.java @@ -19,44 +19,158 @@ import java.util.Map; /** + * Provides methods for executing, triggering, and managing process flows. + * + * @param The type extending {@link FlowModel} representing a flow model * @author wuxiang * @author yusu */ public interface ProcessEngine { + /** + * Executes a process flow with the given code and context. + * + * @param code Unique identifier of the process flow + * @param context Key-value pairs representing the execution context + * @return Result of the execution as a map of key-value pairs + */ Map execute(String code, Map context); + /** + * Triggers a process flow with a specific tag and context. + * + * @param code Unique identifier of the process flow + * @param tag Identifier of the flow's tag + * @param context Key-value pairs representing the execution context + * @return Result of the trigger as a map of key-value pairs + */ Map trigger(String code, String tag, Map context); + /** + * Triggers a process flow with a specific tag, event, and context. + * + * @param code Unique identifier of the process flow + * @param tag Identifier of the flow's tag + * @param event Event to trigger + * @param context Key-value pairs representing the execution context + * @return Result of the trigger as a map of key-value pairs + */ Map trigger(String code, String tag, String event, Map context); + /** + * Pre-compiles a set of process flows by their codes. + * + * @param codes Array of unique identifiers for process flows to compile + */ void preCompile(String... codes); + /** + * Pre-compiles a set of process flows with a custom class loader. + * + * @param classLoader Custom class loader to use during compilation + * @param codes Array of unique identifiers for process flows to compile + */ void preCompile(ClassLoader classLoader, String... codes); + /** + * Loads a process flow by its code. + * + * @param code Unique identifier of the process flow to load + * @return A flow model instance representing the loaded process flow + */ T load(String code); + /** + * Retrieves Java code representation of a process flow. + * + * @param code Unique identifier of the process flow + * @return Java code as a string + */ String getJavaCode(String code); + /** + * Retrieves test code for a process flow. + * + * @param code Unique identifier of the process flow + * @return Test code as a string + */ String getTestCode(String code); - /*** - ** --- Compared with APIs above, following APIs add content of bpm as input directly --- + // --- Methods with content input --- + + /** + * Executes a process flow with the given code, context, and BPM content. + * + * @param code Unique identifier of the process flow + * @param context Key-value pairs representing the execution context + * @param content BPM content in string format + * @return Result of the execution as a map of key-value pairs */ Map execute(String code, Map context, String content); + /** + * Triggers a process flow with a specific tag, context, and BPM content. + * + * @param code Unique identifier of the process flow + * @param tag Identifier of the flow's tag + * @param context Key-value pairs representing the execution context + * @param content BPM content in string format + * @return Result of the trigger as a map of key-value pairs + */ Map trigger(String code, String tag, Map context, String content); + /** + * Triggers a process flow with a specific tag, event, context, and BPM content. + * + * @param code Unique identifier of the process flow + * @param tag Identifier of the flow's tag + * @param event Event to trigger + * @param context Key-value pairs representing the execution context + * @param content BPM content in string format + * @return Result of the trigger as a map of key-value pairs + */ Map trigger(String code, String tag, String event, Map context, String content); + /** + * Pre-compiles a set of process flows with their corresponding BPM content. + * + * @param code2ContentMap Mapping between unique identifiers and BPM content strings + */ void preCompile(Map code2ContentMap); + /** + * Pre-compiles a set of process flows with their corresponding BPM content and a custom class loader. + * + * @param classLoader Custom class loader to use during compilation + * @param code2ContentMap Mapping between unique identifiers and BPM content strings + */ void preCompile(ClassLoader classLoader, Map code2ContentMap); + /** + * Loads a process flow by its code and BPM content. + * + * @param code Unique identifier of the process flow to load + * @param content BPM content in string format + * @return A flow model instance representing the loaded process flow with given content + */ T load(String code, String content); + /** + * Retrieves Java code representation of a process flow with its BPM content. + * + * @param code Unique identifier of the process flow + * @param content BPM content in string format + * @return Java code as a string + */ String getJavaCode(String code, String content); + /** + * Retrieves test code for a process flow with its BPM content. + * + * @param code Unique identifier of the process flow + * @param content BPM content in string format + * @return Test code as a string + */ String getTestCode(String code, String content); } diff --git a/src/main/java/com/alibaba/compileflow/engine/common/extension/ExtensionManager.java b/src/main/java/com/alibaba/compileflow/engine/common/extension/ExtensionManager.java index 9cd359c..1daac99 100644 --- a/src/main/java/com/alibaba/compileflow/engine/common/extension/ExtensionManager.java +++ b/src/main/java/com/alibaba/compileflow/engine/common/extension/ExtensionManager.java @@ -25,6 +25,9 @@ import java.util.stream.Collectors; /** + * Manages extensions and extension points, implementing the {@link Lifecycle} interface. + * It loads, sorts, and retrieves extensions based on their priorities. + * * @author yusu */ public class ExtensionManager implements Lifecycle { diff --git a/src/main/java/com/alibaba/compileflow/engine/common/extension/PluginManager.java b/src/main/java/com/alibaba/compileflow/engine/common/extension/PluginManager.java index 7e0690f..ba9572c 100644 --- a/src/main/java/com/alibaba/compileflow/engine/common/extension/PluginManager.java +++ b/src/main/java/com/alibaba/compileflow/engine/common/extension/PluginManager.java @@ -29,6 +29,9 @@ import java.util.stream.Collectors; /** + * Manages plugins, including loading, dependency checking, and registration of extension points and extensions. + * Implements the {@link Lifecycle} interface for initialization and stopping. + * * @author yusu */ public class PluginManager implements Lifecycle { diff --git a/src/main/java/com/alibaba/compileflow/engine/process/impl/AbstractProcessEngine.java b/src/main/java/com/alibaba/compileflow/engine/process/impl/AbstractProcessEngine.java index dac6c8f..0ffc453 100644 --- a/src/main/java/com/alibaba/compileflow/engine/process/impl/AbstractProcessEngine.java +++ b/src/main/java/com/alibaba/compileflow/engine/process/impl/AbstractProcessEngine.java @@ -126,13 +126,17 @@ public T load(String code, String content) { throw new RuntimeException("No valid flow model found, code is " + code); } - checkCycle(flowModel); - checkContinuous(flowModel); + validateFlowModel(flowModel); sortTransition(flowModel); return flowModel; } + private void validateFlowModel(T flowModel) { + checkCycle(flowModel); + checkContinuous(flowModel); + } + @Override public String getJavaCode(String code) { return getJavaCode(code, null); @@ -179,14 +183,7 @@ private void checkContinuous(TransitionNode node, List visitedNo @SuppressWarnings("unchecked") private void checkCycle(T flowModel) { - DirectedGraph directedGraph = new DirectedGraph<>(); - for (TransitionNode node : flowModel.getAllNodes()) { - List outgoingNodes = node.getOutgoingNodes(); - if (CollectionUtils.isNotEmpty(outgoingNodes)) { - outgoingNodes.forEach( - outgoingNode -> directedGraph.add(DirectedGraph.Edge.of(node, outgoingNode))); - } - } + DirectedGraph directedGraph = buildDirectedGraph(flowModel); List cyclicVertexList = directedGraph.findCyclicVertexList(); if (CollectionUtils.isNotEmpty(cyclicVertexList)) { throw new CompileFlowException("Cyclic nodes found in flow " + flowModel.getCode() @@ -195,6 +192,17 @@ private void checkCycle(T flowModel) { } } + private DirectedGraph buildDirectedGraph(T flowModel) { + DirectedGraph directedGraph = new DirectedGraph<>(); + for (TransitionNode node : flowModel.getAllNodes()) { + List outgoingNodes = node.getOutgoingNodes(); + if (CollectionUtils.isNotEmpty(outgoingNodes)) { + outgoingNodes.forEach(outgoingNode -> directedGraph.add(DirectedGraph.Edge.of(node, outgoingNode))); + } + } + return directedGraph; + } + private void sortTransition(T flowModel) { flowModel.getAllNodes().forEach(node -> node.getTransitions() .sort(Comparator.comparing(TransitionSupport::getPriority).reversed())); diff --git a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/compiler/Compiler.java b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/compiler/Compiler.java index e31122a..6bbdc0e 100644 --- a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/compiler/Compiler.java +++ b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/compiler/Compiler.java @@ -17,10 +17,20 @@ package com.alibaba.compileflow.engine.process.preruntime.compiler; /** + * Represents a compiler interface responsible for compiling Java source code into classes. + * * @author yusu */ public interface Compiler { + /** + * Compiles the given Java source code into a class, using the specified fully qualified class name and class loader. + * + * @param fullClassName The fully qualified name of the class to be compiled + * @param sourceCode The Java source code to compile + * @param classLoader The class loader used for loading the compiled class + * @return The generated class after successful compilation + */ Class compileJavaCode(String fullClassName, String sourceCode, ClassLoader classLoader); } diff --git a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/compiler/JavaCompiler.java b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/compiler/JavaCompiler.java index 7056268..a44de33 100644 --- a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/compiler/JavaCompiler.java +++ b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/compiler/JavaCompiler.java @@ -23,12 +23,24 @@ import java.io.File; /** + * Represents an extension point for compiling Java source code into bytecode. + * Implementations of this interface are responsible for transforming Java source + * into class files according to the specified options. + * @author yusu */ public interface JavaCompiler extends IExtensionPoint { String EXT_COMPILE_CODE = "com.alibaba.compileflow.engine.process.preruntime.compiler.JavaCompiler.compile"; + /** + * Compiles the given Java source and writes the compiled output to a file. + * + * @param javaSource The Java source object containing source code and meta-data + * @param outputFile The target file to write the compiled class + * @param compileOption Options for the compilation process + * @throws Exception Any exception that occurs during the compilation process + */ @ExtensionPoint(code = EXT_COMPILE_CODE, reducePolicy = ReducePolicy.FISRT_MATCH) void compile(JavaSource javaSource, File outputFile, CompileOption compileOption) throws Exception; diff --git a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/converter/FlowModelConverter.java b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/converter/FlowModelConverter.java index cb7cdfc..0c28f3f 100644 --- a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/converter/FlowModelConverter.java +++ b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/converter/FlowModelConverter.java @@ -21,12 +21,29 @@ import java.io.OutputStream; /** + * Interface for converting a FlowStreamSource to a model and vice versa. + * Provides methods to convert a flow stream source into a model object and + * to generate a stream representation of the model. + + * @param The type of the converted model * @author yusu */ public interface FlowModelConverter { + /** + * Converts a FlowStreamSource into a model object. + * + * @param flowStreamSource The input flow stream source + * @return The converted model object + */ T convertToModel(FlowStreamSource flowStreamSource); + /** + * Converts a model object into an OutputStream representing the model's data. + * + * @param model The input model object + * @return An OutputStream containing the serialized representation of the model + */ OutputStream convertToStream(T model); -} \ No newline at end of file +} diff --git a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/generator/Generator.java b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/generator/Generator.java index e3c0fc5..03b764d 100644 --- a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/generator/Generator.java +++ b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/generator/Generator.java @@ -19,11 +19,20 @@ import com.alibaba.compileflow.engine.process.preruntime.generator.code.CodeTargetSupport; /** + * Represents an interface for generating code based on a given target support. + * Implementations of this interface are responsible for generating code snippets + * that can be integrated into a larger code structure. + * @author wuxiang * @author yusu */ public interface Generator { + /** + * Generates code using the provided code target support. + * + * @param codeTargetSupport The support object for generating code + */ void generateCode(CodeTargetSupport codeTargetSupport); } diff --git a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/generator/provider/NodeGeneratorProvider.java b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/generator/provider/NodeGeneratorProvider.java index bc24c47..9aaf650 100644 --- a/src/main/java/com/alibaba/compileflow/engine/process/preruntime/generator/provider/NodeGeneratorProvider.java +++ b/src/main/java/com/alibaba/compileflow/engine/process/preruntime/generator/provider/NodeGeneratorProvider.java @@ -20,12 +20,27 @@ import com.alibaba.compileflow.engine.process.preruntime.generator.Generator; /** + * Interface defining a provider for generators associated with specific nodes. + * This provider manages the mapping between nodes and their corresponding code generation logic. + * @author yusu */ public interface NodeGeneratorProvider { + /** + * Retrieves the generator responsible for generating code for the given node. + * + * @param node The node for which a generator is needed + * @return The generator instance capable of handling the given node + */ Generator getGenerator(Node node); + /** + * Registers a generator to be used for the specified node. + * + * @param node The node to associate with the generator + * @param generator The generator to handle code generation for the node + */ void registerGenerator(Node node, Generator generator); -} \ No newline at end of file +} diff --git a/src/main/java/com/alibaba/compileflow/engine/runtime/ProcessRuntime.java b/src/main/java/com/alibaba/compileflow/engine/runtime/ProcessRuntime.java index 396c516..3990e58 100644 --- a/src/main/java/com/alibaba/compileflow/engine/runtime/ProcessRuntime.java +++ b/src/main/java/com/alibaba/compileflow/engine/runtime/ProcessRuntime.java @@ -3,15 +3,40 @@ import java.util.Map; /** + * Defines the interface for managing process runtimes in the CompileFlow Engine. + * This interface provides methods to interact with process instances, allowing + * the creation, triggering, and manipulation of processes according to the specified context. + * * @author wuxiang * @author yusu */ public interface ProcessRuntime { + /** + * Starts a process instance with the given context. + * + * @param context The initial context containing variables and metadata for the process + * @return A runtime result encapsulating the outcome of the process start operation + */ Map start(Map context); + /** + * Triggers a process instance with a specific tag and context. + * + * @param tag Identifier of the process instance to trigger + * @param context The context containing variables and metadata for the trigger + * @return A runtime result encapsulating the outcome of the trigger operation + */ Map trigger(String tag, Map context); + /** + * Triggers a process instance with a specific tag, event, and context. + * + * @param tag Identifier of the process instance to trigger + * @param event The event to trigger within the process instance + * @param context The context containing variables and metadata for the trigger + * @return A runtime result encapsulating the outcome of the trigger operation + */ Map trigger(String tag, String event, Map context); } diff --git a/src/main/java/com/alibaba/compileflow/engine/runtime/impl/AbstractProcessRuntime.java b/src/main/java/com/alibaba/compileflow/engine/runtime/impl/AbstractProcessRuntime.java index ca7b6e3..f155439 100644 --- a/src/main/java/com/alibaba/compileflow/engine/runtime/impl/AbstractProcessRuntime.java +++ b/src/main/java/com/alibaba/compileflow/engine/runtime/impl/AbstractProcessRuntime.java @@ -25,7 +25,6 @@ import com.alibaba.compileflow.engine.common.util.*; import com.alibaba.compileflow.engine.definition.common.*; import com.alibaba.compileflow.engine.definition.common.var.IVar; -import com.alibaba.compileflow.engine.definition.tbbpm.EventNode; import com.alibaba.compileflow.engine.definition.tbbpm.WaitEventTaskNode; import com.alibaba.compileflow.engine.definition.tbbpm.WaitTaskNode; import com.alibaba.compileflow.engine.process.preruntime.compiler.Compiler; @@ -251,10 +250,6 @@ public String generateTestCode() { return classTarget.generateCode(); } - public boolean hasEventNode() { - return flowModel.getAllNodes().stream().anyMatch(e -> e instanceof EventNode); - } - protected abstract void registerNodeGenerator(NodeContainer nodeContainer); protected abstract boolean isBpmn20(); @@ -636,7 +631,6 @@ private String getFlowTestClassFullName(String code, String id) { } private String wrapClassFullName(String name) { - return "compileflow." + name; } diff --git a/src/main/java/com/alibaba/compileflow/engine/runtime/instance/FlowInstance.java b/src/main/java/com/alibaba/compileflow/engine/runtime/instance/FlowInstance.java index 8297fa1..bd319e5 100644 --- a/src/main/java/com/alibaba/compileflow/engine/runtime/instance/FlowInstance.java +++ b/src/main/java/com/alibaba/compileflow/engine/runtime/instance/FlowInstance.java @@ -17,9 +17,16 @@ package com.alibaba.compileflow.engine.runtime.instance; /** + * Represents a runtime instance of a flow in the CompileFlow Engine. + * This interface defines the fundamental operations and state of a flow instance + * during its execution lifecycle, adhering to the terms and conditions set forth + * in the Apache License Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0). + * * @author wuxiang * @author yusu */ public interface FlowInstance { + // No methods are defined in this interface, as it serves as a marker for flow instance classes. + } diff --git a/src/main/java/com/alibaba/compileflow/engine/runtime/instance/ProcessInstance.java b/src/main/java/com/alibaba/compileflow/engine/runtime/instance/ProcessInstance.java index 7db15c7..b86b670 100644 --- a/src/main/java/com/alibaba/compileflow/engine/runtime/instance/ProcessInstance.java +++ b/src/main/java/com/alibaba/compileflow/engine/runtime/instance/ProcessInstance.java @@ -19,11 +19,19 @@ import java.util.Map; /** + * Represents a running process instance that can be executed. * @author wuxiang * @author yusu */ public interface ProcessInstance extends FlowInstance { + /** + * Executes the process instance with the given context. + * + * @param context The context containing variables and metadata for the execution + * @return A result object encapsulating the outcome of the execution + * @throws Exception If an error occurs during the process execution + */ Map execute(Map context) throws Exception; } diff --git a/src/main/java/com/alibaba/compileflow/engine/runtime/instance/StatefulProcessInstance.java b/src/main/java/com/alibaba/compileflow/engine/runtime/instance/StatefulProcessInstance.java index 52ff182..11d65c2 100644 --- a/src/main/java/com/alibaba/compileflow/engine/runtime/instance/StatefulProcessInstance.java +++ b/src/main/java/com/alibaba/compileflow/engine/runtime/instance/StatefulProcessInstance.java @@ -3,12 +3,31 @@ import java.util.Map; /** + * Represents a stateful process instance that can be triggered and transitioned between states. + * * @author yusu */ public interface StatefulProcessInstance extends ProcessInstance { + /** + * Triggers a state transition for the process instance with a specific tag and context. + * + * @param tag Identifier of the process instance to trigger + * @param context The context containing variables and metadata for the trigger + * @return A runtime result encapsulating the outcome of the trigger operation + * @throws Exception If an error occurs during the process execution + */ Map trigger(String tag, Map context) throws Exception; + /** + * Triggers a state transition for the process instance with a specific tag, event, and context. + * + * @param tag Identifier of the process instance to trigger + * @param event The event to trigger within the process instance + * @param context The context containing variables and metadata for the trigger + * @return A runtime result encapsulating the outcome of the trigger operation + * @throws Exception If an error occurs during the process execution + */ Map trigger(String tag, String event, Map context) throws Exception; }