Skip to content

Supported Features

Here is the complete feature matrix for LarkBatis.

  • Supported: Implemented, optimized, and fully tested.
  • Narrowed: Supported with specific compile-time constraints.
  • Dropped: Omitted by design to eliminate reflection and runtime interpretation. Produces a clear compile error naming the alternative.

Version 0.1.0.

Statements

Feature Status Notes
@Select @Insert @Update @Delete Accepts String[] (lines joined with a single space)
<select> <insert> <update> <delete> in mapper XML Namespace matches interface FQN; id matches method name. Details
Mixing annotations and XML in one mapper Resolved per method; having both or neither is a compile error
#{} bind parameters Resolved against method parameter types at compile time
${} raw splices Strictly restricted to SqlFragment, closed-value types, or @OrderBy. Details
@Param annotations Explicit parameter naming
@Options(useGeneratedKeys, keyProperty, keyColumn) Details
<selectKey> Write sequence lookup as an explicit query
@SelectProvider / @InsertProvider Runtime SQL generation methods are invisible to the compiler. Use XML or the escape hatch
Untyped Map or Object parameters Compiler requires concrete types to generate parameter setters. Use typed objects or @Param
RowBounds in-memory paging Page in SQL using LIMIT and OFFSET parameters

Dynamic SQL

Feature Status Notes
<if> Compiled to boolean locals and evaluated once
<choose> / <when> / <otherwise> Mutual exclusion baked into generated bytecode
<where> / <set> Constant-folded without runtime string scans
<trim> Literal attributes only, folded at compile time
<sql> / <include> Static refid only, inlined at compile time
<foreach> Statically-typed collections/arrays/maps. Throws on empty collections. Details
@PadPow2 Bounds dynamic IN clause SQL variants to power-of-two lengths
<bind> Compute values in Java and pass as parameters
Full OGNL in test Replaced by a type-checked test grammar
databaseId attribute Use dedicated mapper interfaces per database vendor

Results & Mapping

Feature Status Notes
resultType convention mapping snake_case → camelCase applied at compile time
Positional column reads Hardcoded column indexes for parsed select lists
Name-based metadata fallback Used for SELECT * or dynamic splices; resolved once from metadata
Scalar returns long, String, etc. read column 1 directly without bean allocation
List<T> returns Standard collection return
Stream<T> returns Stream rows over open cursor; caller closes. Details
<resultMap> Explicit column-to-property mapping (no implicit guessing)
<association> / <collection> Single-level nesting via SQL join; query must be ordered by parent ID
Nested select= in result maps Causes N+1 queries. Use SQL joins instead
<discriminator> Use separate queries with distinct return types
<constructor> results Provide standard no-arg constructor and setters
Result map extends, columnPrefix, autoMapping Declare mappings explicitly or use resultType
Lazy loading Requires dynamic proxy per object. Use joins or explicit second query
Type aliases Use fully-qualified class names

Types & Handlers

Feature Status Notes
Primitives and boxed wrappers Boxed wrappers use JdbcCodec for proper null handling
String, BigDecimal, BigInteger, byte[] Built-in direct JDBC mapping
java.sql.Date, Time, Timestamp Built-in direct JDBC mapping
Instant, LocalDate, LocalTime, LocalDateTime Built-in conversion via JdbcCodec
Enums (by name) Built-in mapping; enums are closed-value types safe for ${}
@Column Explicit column name on field, setter, or getter. Details
@Handler custom handlers Declared on properties, parameters, or in mapper XML. Details
Global type handlers (-Alarkbatis.typeHandlers) Configured per Java type at compile time. Details
Runtime TypeHandler discovery Replaced by explicit compile-time configuration

Sessions, Transactions & Execution

Feature Status Notes
LarkBatisTx scopes & vote-to-commit Standalone transaction manager. Details
Spring @Transactional Automatic integration via DataSourceUtils
Spring exception translation Translates JDBC exceptions to Spring's DataAccessException hierarchy
Spring Boot auto-configuration Single starter compatible with Spring Boot 3 and Boot 4
Generated Spring @Configuration Registers mappers as beans with proxyBeanMethods = false
Batch inserts Declared via method signature (List<T> parameter)
Multi-row VALUES via <foreach> Generates multi-row insert statements
Escape hatch (query, queryOne, queryStream, update) Executes dynamic SQL safely via SqlFragment
ExecutorType.BATCH / REUSE Replaced by batch method signatures
Interceptor plugins Replaced with explicit SQL, type handlers, or Spring AOP. See recipes
Second-level cache (<cache>, <cache-ref>) Cache at the service level (e.g. Spring Cache, Redis)
First-level cache Connections are returned immediately to the pool
Runtime addMapper() Mapper registry is closed at compile time
Multiple DataSources per mapper Configure one session per DataSource and declare @Bean methods manually
Dynamic SQL logging (log-sql) Configured at the connection pool or driver level (datasource-proxy, p6spy)

Build & Tooling

Feature Status Notes
Annotation processor (javac) Standard javac compiler (ECJ is not supported)
Gradle plugin Details
Maven plugin Requires <extensions>true</extensions>
JPMS named modules Real named modules for all published artifacts
Lombok compatibility Declare LarkBatis processor after Lombok in build file
Incremental compilation Compile with -parameters flag for reliable incremental builds
Test-scoped mappers Mappers belong in main compilation source sets
GraalVM native image Zero runtime reflection by design (smoke test pending in M5)
Migration scanner larkbatis-scan CLI tool. Details