Fenix Documentation

Fenix is a Spring Data JPA extension library designed to simplify the writing of complex and dynamic JPQL (Java Persistence Query Language). It aims to bridge the gap between the simplicity of Spring Data JPA for basic CRUD and the powerful dynamic SQL capabilities found in MyBatis.

Key capabilities include:

• Four ways to write dynamic SQL: Using XML, Java fluent (chaining) API, dynamic condition annotations, and dynamic Specification construction.
• ActiveRecord pattern support.
• Enhanced Batch Operations: Faster support for batch 'create/delete/update' operations, including incremental updates for non-null properties.
• ID Generation: Built-in support for Snowflake algorithm and NanoId primary key generation strategies.
• Flexible Result Mapping: SQL execution results can be mapped to any custom entity object, offering a simpler alternative to standard JPA projections.
• Extensibility: Allows for custom XML semantic tags and tag handlers to generate custom SQL fragments and parameters.

Fenix allows you to extend its XML SQL capabilities by creating custom semantic tags. This is useful for encapsulating complex, reusable dynamic SQL logic (such as data permission checks or complex business rules) into a single, readable XML tag.

To implement a custom tag, you must:

1. Design the XML tag structure: Decide on the tag name and the attributes it will accept (e.g., field, userId).
2. Implement a FenixHandler: Create a Java class that implements the FenixHandler interface to define how the tag translates into SQL fragments and parameters.
3. Map the tag using @Tagger: Use the @Tagger annotation on your handler class to link it to specific XML tag names and optional prefixes.
4. Configure scanning: Tell Fenix where to find your handler classes via configuration.

This approach is superior to using standard logic control (@if/@else) or <choose> tags when the logic is complex and needs to be reused across many different queries.

<!-- Example of a custom tag usage -->
<regionAuth field="x.region" userId="searchMap.userId"/>

<!-- Example of a custom tag with a prefix -->
<andRegionAuth field="x.region" userId="searchMap.userId"/>

By default, Fenix only generates a query condition for a property if its value is not empty.

Default 'Empty' Logic

A property is considered empty (and thus ignored in the query) if:

• It is a standard Java object that is null.
• It is a String that is blank (isBlank()).
• It is an array or collection that is null or empty.

Warning: Avoid using primitive types (like int, long) in your parameter beans. Since primitives cannot be null, they will always be treated as non-empty (e.g., 0 will be treated as a valid query value). Use wrapper classes like Integer or Long instead.

Customizing the Match Logic

If you need specific logic to decide whether a condition should be generated, add a no-argument method to your Java Bean that has the same name as the property and returns a boolean.

If the method returns true, the annotated condition is generated. If false, it is skipped.

@Getter
@Setter
public class BookMatch {
    @Equals
    private String id;

    /**
     * Custom logic: Only generate the 'id' condition if id is not null and not "1".
     */
    public boolean id() {
        return id != null && !id.equals("1");
    }
}

Fenix XML files are used to define JPQL statements with dynamic predicates. By default, Fenix scans the src/main/resources/fenix directory.

XML Structure:

1. The root element <fenixs> must define a namespace that matches the repository name used in @QueryFenix.
2. The <fenix> element must have an id that matches the method identifier used in @QueryFenix.
3. Inside <fenix>, use predicate tags like <in>, <andLike>, and <andBetween> to build dynamic WHERE clauses.

Example BlogRepository.xml:

<fenixs namespace="BlogRepository">
    <fenix id="queryMyBlogs">
        SELECT
            b
        FROM
            Blog AS b
        WHERE
        <in field="b.id" value="ids" match="ids != empty"/>
        <andLike field="b.author" value="blog.author" match="blog.author != empty"/>
        <andLike field="b.title" value="blog.title" match="blog.title != empty"/>
        <andBetween field="b.createTime" start="blog.createTime" end="blog.updateTime" match="(?blog.createTime != empty) || (?blog.updateTime != empty)"/>
    </fenix>
</fenixs>

Fenix uses XML semantic tags to generate dynamic SQL, replacing verbose if/else or foreach logic found in other frameworks. These tags leverage the MVEL template engine to evaluate conditions.

Key concepts:

• Conditional Generation: Most tags include a match attribute. This attribute accepts an MVEL expression. If the expression evaluates to true, the SQL fragment is generated; otherwise, it is omitted. If match is omitted, the fragment is always generated.
• Logical Prefixes: Most tags support AND, OR, and NOT prefixes (e.g., <andEqual>, <orEqual>, <notEqual>) to simplify dynamic query construction.
• Parameter Mapping: Tags automatically map values to named parameters in JPQL. You can use the name attribute to explicitly define the parameter name used in the generated SQL.

<!-- Example of the core idea: conditional generation via match -->
<andEqual field="email" value="user.email" match="?email != empty" />
<!-- If email is not empty, generates: AND email = :user_email -->

The between methods allow for range matching. They take a fieldName, a startValue, and an endValue.

Degradation Behavior

If one of the boundary values is null, the method automatically degrades to a simpler comparison:

• Both non-null: Generates a between ... and ... condition.
• Start non-null, End is null: Degrades to a Greater Than or Equal (>=) condition.
• Start is null, End non-null: Degrades to a Less Than or Equal (<=) condition.
• Both are null: Throws an exception.

API Methods

• andBetween(String fieldName, Object startValue, Object endValue, [boolean match])
• orBetween(String fieldName, Object startValue, Object endValue, [boolean match])
• andNotBetween(String fieldName, Object startValue, Object endValue, [boolean match])
• orNotBetween(String fieldName, Object startValue, Object endValue, [boolean match])

// Standard range match
builder.andBetween("totalPage", minTotalPage, maxTotalPage)

// Degrades to >= minTotalPage
builder.andBetween("totalPage", minTotalPage, null, minTotalPage != null)

// Degrades to <= maxTotalPage
builder.andBetween("totalPage", null, maxTotalPage)