QLExpress Documentation

To contribute to QLExpress, follow these steps to prepare your local environment:

1. Generate Antlr4 runtime code: Run mvn compile in the project root.
2. Configure automatic code formatting: Create a .git/hooks/pre-commit file to ensure spotless is applied before every commit:

#!/bin/sh
mvn spotless:apply
git add -u
exit 0

3. Run tests: Use mvn test to verify your changes locally.

To contribute to QLExpress, follow these steps to prepare your local environment:

1. Generate Antlr4 code: Run mvn compile in the project root to generate the necessary runtime code.
2. Configure Code Formatting: Use the spotless plugin to ensure code adheres to project standards. You can automate this by creating a .git/hooks/pre-commit file.
3. Run Tests: Always execute mvn test locally to ensure code quality before submitting changes.

# Create a pre-commit hook to automate formatting
#!/bin/sh
mvn spotless:apply
git add -u
exit 0

QLExpress supports common Java 8 syntax, including for-each loops, Stream API, and functional interfaces.

To use the Stream API on Java collections, you must ensure your Security Policy is configured to allow access to Java methods.

Lambda Expressions can be assigned to Java 8 functional interfaces (like Function, Consumer, or Predicate) or passed as arguments to methods accepting these interfaces.

To improve performance, you can enable caching so that identical expressions are not re-compiled.

Standard Cache: Enable the cache option in the runner. Note that this cache has no size limit and is suitable for a finite number of expressions. Use clearCompileCache() to prevent memory issues.

Serializable Pre-compiled Cache: For distributed environments, you can pre-compile scripts on a production machine, serialize the SerializableParseCache (using Jackson, Fastjson2, etc.), and distribute it to consumer machines. Consumers should load it as a LoadedParseCache for high-frequency execution.

You can execute a QLExpress script by passing a plain Java object as the context using the execute(String, Object, QLOptions) method. In this mode, variable names in the script correspond to the fields or accessible getter methods of the provided object.

Typical Scenario: Passing an existing DTO or POJO that carries context data so the script can read its fields directly.

QLExpress4 supports string interpolation using the $^{expression} syntax. This allows you to embed calculation results directly into strings.

Example: "Hello, $^{user.name}"

Escaping: To keep the literal characters, use \$: "\$^{expression}".

Template Engine: You can use executeTemplate to render template strings without manually adding quotes.

To use QLExpress4 in your Java project, add the following dependency to your pom.xml. It is recommended to use the latest stable version 4.1.2.

Requirements:

• JDK 8 or higher

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>qlexpress4</artifactId>
    <version>4.1.2</version>
</dependency>

To allow non-technical users to write natural language rules, use the @QLAlias annotation on your Java classes, fields, or methods. This maps technical names to user-friendly aliases used within QLExpress scripts.

Example mapping:

• Class @QLAlias("用户") maps to 用户 in scripts.
• Field @QLAlias("是vip") maps to 是vip in scripts.

@QLAlias("用户")
public class User {
    @QLAlias("是vip")
    private boolean vip;
    // ...
}

// Usage in script:
// "用户.是vip? 订单.金额 * 0.8 : 订单.金额"