CompileFlow Documentation

CompileFlow is a high-performance, compile-then-execute process engine designed for stateless, in-memory execution. It works by converting process files (BPMN 2.0 or TBBPM) into optimized Java code, which is then compiled and executed at native speeds.

Key characteristics:

• Ultra-High Performance: Achieves native Java performance via code generation.
• Type-Safe: Provides compile-time validation.
• Multi-Standard: Supports both BPMN 2.0 and TBBPM specifications.
• Visual Design: Compatible with an IntelliJ IDEA plugin for modeling.

A ProcessEngine instance is a heavyweight object that manages multiple internal thread pools, including Compilation, Execution, Event, and Schedule pools. A single engine instance can manage 16-64 background threads.

Warning: Creating a new ProcessEngine for every request or inside a loop will cause severe resource leaks and application instability. Always aim for a single singleton instance per application lifecycle.

CompileFlow provides three distinct ways to extend its functionality depending on your goal:

1. Event Listeners: Use these to observe and react to engine events (e.g., for logging, metrics, or auditing) without modifying core logic.
2. Extension Points: Use these to customize or replace specific engine behaviors (e.g., providing different strategy implementations like pricing rules).
3. Service Providers: Use these to add major new components (e.g., implementing a new ProcessEngineProvider for a custom process type) that the engine must discover at startup.

CompileFlow uses a layered configuration model where settings are applied in a specific order of precedence. If a property is defined in multiple places, the source with the highest priority wins.

Priority Order (Highest to Lowest):

1. Programmatic Configuration: Settings applied via ProcessEngineConfig.builder() in your Java code.
2. Spring Boot (application.yml): Properties defined in your Spring configuration files.
3. Java System Properties: JVM startup arguments (e.g., -Dcompileflow.cache.runtime-max-size=5000).
4. Internal Defaults: The engine's built-in default values.

CompileFlow's hot deployment allows for zero-downtime updates by enabling real-time modifications to business logic, bug fixes, or process flow adjustments without application restarts.

It supports two primary modes:

1. Manual Reload: Using ProcessAdminService.deploy() to explicitly trigger a re-lookup and re-compilation of a process.
2. Automatic Deployment: Using a FlowHotDeployer combined with a detector (like FileSystemChangeDetector or NacosChangeDetector) to monitor external sources and trigger deployments automatically when changes are detected.

This capability is commonly used for externalizing business rules, performing canary releases (by deploying new versions with distinct codes), and executing emergency rollbacks by redeploying known stable XML content.

CompileFlow uses an event-driven architecture based on Java's Service Provider Interface (SPI) to enable monitoring without modifying the core engine.

1. ProcessEventListener Interface: The primary extension point. You implement this to react to engine events.
2. Engine Events: The ProcessEngine publishes events (e.g., process start, completion, or failure) at critical lifecycle points.
3. SPI Registration: Custom listeners are discovered at startup by placing a file in META-INF/extensions/ containing the fully qualified name of your listener class.

For most Spring Boot applications, you can configure the engine by adding properties to your application.yml.

Recommended Primary Settings:

• compileflow.model-type: Choose TBBPM (optimized for enterprise) or BPMN (international standard).
• compileflow.executor.compilation-threads: Number of threads for compiling flows (Recommended: 1-4).
• compileflow.executor.execution-threads: Number of threads for executing flows (Recommended: Start with CPU core count).
• compileflow.cache.runtime-max-size: Max compiled flows in memory (Recommended: 2000-10000 for production).
• compileflow.observability.enabled: Enable monitoring features like metrics and tracing (Essential for production).

compileflow:
  model-type: TBBPM
  executor:
    compilation-threads: 2
    execution-threads: 16
  cache:
    runtime-max-size: 2000
  observability:
    enabled: true

If using Spring Boot with the compileflow-spring-boot-starter, you do not need to manually manage the engine lifecycle. The starter automatically configures a singleton ProcessEngine. You can simply inject it into your services using @Autowired.

import com.alibaba.compileflow.engine.ProcessEngine;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

@Service
public class OrderService {
    
    // ✅ CORRECT: Inject the singleton engine managed by Spring.
    @Autowired
    private ProcessEngine<TbbpmModel> engine;
    
    public void processOrder(OrderRequest request) {
        // Safe and efficient: all requests share the same engine and thread pools.
        engine.execute(ProcessSource.fromCode("bpm.order.process"), request, OrderResponse.class);
    }
}