Army — A Better Way to Write SQL in Java, A Better Blocking ORM Framework

<dependencies>
    <dependency>
        <groupId>io.qinarmy</groupId>
        <artifactId>army-jdbc</artifactId>
        <version>0.6.8-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>io.qinarmy</groupId>
        <artifactId>army-postgre</artifactId>
        <version>0.6.8-SNAPSHOT</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <configuration>
                <annotationProcessors>io.army.modelgen.ArmyMetaModelDomainProcessor</annotationProcessors>
            </configuration>
        </plugin>
    </plugins>
</build>

public void createSessionFactory() {
    final Map<String, Object> envMap = new HashMap<>();
    envMap.put(ArmyKey.DATABASE.name, Database.MySQL);
    envMap.put(ArmyKey.DIALECT.name, MySQLDialect.MySQL80);

    final DataSource dataSource = createDataSource();
    sessionFactory = SyncFactoryBuilder.builder()
            .name("army-test")
            .packagesToScan(List.of("io.army.example.stock.domain"))
            .datasource(dataSource)
            .environment(StandardEnvironment.from(envMap))
            .build();
}

// Stock: table with a unique composite index
@Table(name = "stock",
       indexes = @Index(name = "${DEFAULT_VALUE}", unique = true,
                        fieldList = {"exchange", "code"}), // auto-generates: uni_stock_exchange_code
       comment = "stock")
public class Stock { }

// StockQuotes: table with unique index on (stockId, date)
@Table(name = "stock_quotes",
       indexes = @Index(name = "${DEFAULT_VALUE}", unique = true,
                        fieldList = {"stockId", "date"}), // auto-generates: uni_stock_quotes_stockId_date
       comment = "daily stock quotes")
public class StockQuotes { }

// UploadRecord: table with multiple non-unique indexes
@Table(name = "upload_record",
       indexes = {
           @Index(name = "${DEFAULT_VALUE}", fieldList = "userId"),
           @Index(name = "${DEFAULT_VALUE}", fieldList = "fileHash")
       },
       comment = "uploaded document record")
public class UploadRecord { }

# File: META-INF/army/TableMeta.properties

# Override column name
# Used when @Column(name = "${DEFAULT}") or @Column(name = "${RUNTIME}")
com.example.domain.Stock.userName.Column.name=user_name

# Override column comment
com.example.domain.Stock.status.Column.comment=custom status

# Override column precision (e.g., increase VARCHAR length to 512)
com.example.domain.Stock.name.Column.precision=512

# Override column scale (e.g., increase decimal places to 4)
com.example.domain.Stock.offerPrice.Column.scale=4

# Override column default value (SQL expression)
com.example.domain.Stock.status.Column.defaultValue='ACTIVE'

# Override column collation
com.example.domain.Stock.name.Column.collation=en_US.utf8

// Simple column: auto name (exchange → exchange), NOT NULL, updatable only on INSERT
@Column(notNull = true, updatable = false, precision = 5, comment = "exchange code")
public String exchange;

// Decimal column with precision and scale → DDL: DECIMAL(10, 2)
@Column(precision = 10, scale = 2, defaultValue = "0.00", comment = "offer price")
public BigDecimal offerPrice;

// Enum column with a string default → DDL includes: DEFAULT 'NORMAL'
@Column(notNull = true, precision = 10, defaultValue = "'NORMAL'", comment = "listing status")
public StockStatus status;

// Date column with SQL default expression
@Column(defaultValue = "DATE '1970-01-01'", comment = "listing date")
public LocalDate listingDate;

// Managed field: auto-set by the framework on INSERT, never updatable
@Column
public LocalDateTime createTime;

# File: META-INF/army/TableMeta.properties

# Option 1: Switch generator type at runtime (POST, PRECEDE, or DEFAULT)
com.example.domain.Stock.id.Generator.type=POST

# Option 2: Load a custom GeneratorStrategy (takes precedence over .Generator.type)
# Format: fully.qualified.StrategyClass[:jsonParams]
com.example.domain.Stock.id.GeneratorStrategy=io.army.generator.Snowflake8GeneratorStrategy:{"startTime":1779111192831}

# Override SQL type mapping for the id column (optional)
com.example.domain.Stock.id.Mapping.value=io.army.mapping.SqlBigIntType

// Stock entity: startTime=1779012232202
@Generator(value = "io.army.generator.snowflake.Snowflake8Generator",
           params = @Param(name = "startTime", value = "1779012232202"))
@Column
public long id;

// StockQuotes entity: different startTime for a different ID space
@Generator(value = "io.army.generator.snowflake.Snowflake8Generator",
           params = @Param(name = "startTime", value = "1779111192831"))
@Column
public long id;

// SHA-256 hash → fixed-length CHAR(44) instead of VARCHAR
@Column(precision = 44, comment = "file hash (SHA-256, standard base64)")
@Mapping("io.army.mapping.SqlCharType")
public String fileHash;

// List<Long> → JSONB (PostgreSQL) or JSON (MySQL), defaulting to '[]'
@Column(notNull = true, defaultValue = "'[]'", comment = "vector ID list")
@Mapping("io.army.mapping.PreferredJsonbType")
private List<Long> vectorIdList;

// Stock: unique composite index — no duplicate (exchange, code) pairs
@Table(name = "stock",
       indexes = @Index(name = "${DEFAULT_VALUE}", unique = true,
                        fieldList = {"exchange", "code"})) // → uni_stock_exchange_code

// StockQuotes: unique index — one quote record per stock per trading day
@Table(name = "stock_quotes",
       indexes = @Index(name = "${DEFAULT_VALUE}", unique = true,
                        fieldList = {"stockId", "date"})) // → uni_stock_quotes_stockId_date

// UploadRecord: two non-unique indexes for fast lookup
@Table(name = "upload_record",
       indexes = {
           @Index(name = "${DEFAULT_VALUE}", fieldList = "userId"),  // → idx_upload_record_userId
           @Index(name = "${DEFAULT_VALUE}", fieldList = "fileHash") // → idx_upload_record_fileHash
       })

// Standard B-tree index with column collation
@Index(name = "${DEFAULT_VALUE}", unique = true, type = "btree",
    fields = {
        @IndexField(name = "exchange"),
        @IndexField(name = "code", collation = "en_US.utf8")
    })

// PostgreSQL HNSW vector index for embedding similarity search
@Index(name = "${DEFAULT_VALUE}", type = "hnsw",
    fields = @IndexField(name = "embedding", opclass = "vector_cosine_ops"))

MinBaseDomain<T>           → @Column createTime         (auto-set on INSERT, never updatable)
  └─ BaseDomain<T>         → + @Column updateTime, version  (auto-set on INSERT/UPDATE; version auto-incremented)
      └─ StockBaseDomain<T> → + @Column stockId, date        (foreign key + trading date)
          ├── Stock              → table: stock               (exchange, code, name, status...)
          ├── StockQuotes        → table: stock_quotes        (open, high, low, volume...)
          ├── StockCandles       → table: stock_candles       (OHLCV data)
          └── StockRankDaily     → table: stock_rank_daily    (daily ranking)

// Level 1: Every entity needs a creation timestamp
@MappedSuperclass
public abstract class MinBaseDomain<T extends MinBaseDomain<T>> {

    @Column
    public LocalDateTime createTime;   // Auto-set by the framework on INSERT
}

// Level 2: Add update tracking and optimistic locking
@MappedSuperclass
public abstract class BaseDomain<T extends BaseDomain<T>> extends MinBaseDomain<T> {

    @Column
    public LocalDateTime updateTime;   // Auto-refreshed on every INSERT / UPDATE

    @Column
    public int version;                 // Auto-incremented on UPDATE (optimistic lock)
}

// Level 3: Add fields shared by all stock-related entities
@MappedSuperclass
public abstract class StockBaseDomain<T extends StockBaseDomain<T>> extends BaseDomain<T> {

    @Column(notNull = true, updatable = false, comment = "stock id")
    public Long stockId;

    @Column(notNull = true, updatable = false, comment = "trading date")
    public LocalDate date;
}

// Concrete entity: inherits createTime/updateTime/version/stockId/date from the chain
@Table(name = "stock_quotes", comment = "daily stock quotes",
       indexes = @Index(name = "${DEFAULT_VALUE}", unique = true,
                        fieldList = {"stockId", "date"}))
public class StockQuotes extends StockBaseDomain<StockQuotes> {

    @Generator(value = "io.army.generator.snowflake.Snowflake8Generator",
               params = @Param(name = "startTime", value = "1779111192831"))
    @Column
    public long id;

    @Column(precision = 9, scale = 3, comment = "open price")
    public BigDecimal open;
    // ... more fields
}

// ── Table name: auto-derive from class name, allow override via properties ──
// Without properties: StockQuotes → "stock_quotes"
// With properties: com.example.domain.StockQuotes.Table.name=stock_v2
@Table(name = "${DEFAULT}", comment = "stock data")

// ── Table name: MUST be in properties, startup fails otherwise ──
// Used when team A defines the entity but team B controls deployment name
@Table(name = "${RUNTIME}", comment = "cross-team table")

// ── Column name: camelCase → snake_case by default, configurable ──
// Without properties: userName → "user_name"
// With properties: com.example.Stock.userName.Column.name=login_name
@Column(name = "${DEFAULT}")
public String userName;

// ── Column precision: must be configured at startup — varies by deployment ──
// Without properties: throws MetaException
// With properties: com.example.Stock.embedding.Column.precision=768
@Column(precision = Column.RUNTIME_EXP)
public String embedding;

// ── Index name: always auto-generate, never override ──
// @Table(name = "stock") + @Index(fieldList = "userId")
// → unique: uni_stock_user_id, non-unique: idx_stock_user_id
@Index(name = "${DEFAULT_VALUE}", fieldList = "userId")

// ── Index name: default generation but allow override via properties ──
// Without properties: same as ${DEFAULT_VALUE}
// With properties: com.example.IndexMeta[0].name=my_index
@Index(name = "${DEFAULT}", fieldList = "userId")

// ── Optional index: skip entirely on staging, keep in production ──
// Without properties: index is silently skipped
// With properties: com.example.IndexMeta[0].type=btree → index is created
@Index(name = "idx_stock", type = "${OPTIONAL}", fieldList = "userId")

// ── Column default value: type-appropriate zero ──
// LocalDateTime → '1970-01-01 00:00:00'
// BigDecimal → 0
// String → ''
@Column(defaultValue = "${DEFAULT}", comment = "upload complete time")
public LocalDateTime uploadCompleteTime;

// ── Generator type: defer to deployment config ──
// Development: POST (auto-increment), Production: PRECEDE (Snowflake)
@Generator(type = GeneratorType.RUNTIME)
@Column
public long id;

{fully.qualified.ClassName}.{fieldName|Table}.{AttributeCategory}.{attributeName}

# File: META-INF/army/TableMeta.properties
# Place in: src/main/resources/META-INF/army/TableMeta.properties

# ── @Table ──
com.example.domain.Stock.Table.name=stock_v2
com.example.domain.Stock.Table.comment=stock data v2
com.example.domain.Stock.Table.schema=public
com.example.domain.Stock.Table.ddlMode=NONE

# ── @Column ──
com.example.domain.Stock.userName.Column.name=user_name
com.example.domain.Stock.status.Column.comment=custom status
com.example.domain.Stock.name.Column.precision=512
com.example.domain.Stock.offerPrice.Column.scale=4
com.example.domain.Stock.status.Column.defaultValue='ACTIVE'
com.example.domain.Stock.name.Column.collation=en_US.utf8

# ── @Generator ──
com.example.domain.Stock.id.Generator.type=POST
com.example.domain.Stock.id.GeneratorStrategy=io.army.generator.Snowflake8GeneratorStrategy:{"startTime":1779111192831}

# ── @Mapping ──
com.example.domain.Stock.id.Mapping.value=io.army.mapping.SqlBigIntType

# ── @Index ──
com.example.domain.Stock.IndexMeta[0].name=idx_stock_custom
com.example.domain.Stock.IndexMeta[0].type=btree

# Skip an optional index (empty value = skip)
com.example.domain.Stock.IndexMeta[1].type=

# ── @IndexField (per-column index settings) ──
com.example.domain.Stock.IndexMeta[0].field.code.collation=en_US.utf8
com.example.domain.Stock.IndexMeta[0].field.embedding.opclass=vector_cosine_ops

# ── @DdlMode ──
com.example.domain.LegacyData.Table.ddlMode=NONE

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Mapping {

    /// Fully-qualified class name of the MappingType implementation.
    /// Used as a string to avoid compile-time dependencies on dialect-specific classes.
    String value() default "";

    /// The MappingType class itself (takes precedence over value()).
    Class<?> type() default void.class;

    /// Extra configuration parameters (e.g., PostgreSQL enum type name).
    String[] params() default {};

    /// Java method reference for constructing or creating instances of the mapped type.
    /// Format: "ClassName::new" (constructor) or "ClassName::methodName" (static factory).
    /// Consumed by PgSingleRangeType.fromMethod / PgMultiRangeType.fromMethod and array variants
    /// via PgRangeType.createRangeFunction; resolved by _ArmyPgRangeType.loadConstructor / loadFactoryMethod.
    /// For non-range types, dispatched via _MappingFactory.doMap.
    String func() default "";

    /// Character set for text-based binary mappings (e.g., LongBlobType + InputStream).
    String charset() default "";

    /// Element types for collection mappings (e.g., MySQL SET).
    Class<?>[] elements() default {};
}

@Column(notNull = true, updatable = false, comment = "first chat message content")
@Mapping("io.army.mapping.TextType")
private String firstContent;

// From SpringAiChatMemory (chat memory module)
@Column(name = "${DEFAULT}", notNull = true, comment = "${DEFAULT}")
@Mapping("io.army.mapping.TextType")
private String content;

// From SpringAiVectorStore (vector store module)
@Column(name = "${DEFAULT}", comment = "${DEFAULT}")
@Mapping("io.army.mapping.TextType")
private String content;

@Column(precision = 44, comment = "file hash, SHA-256 algorithm, standard base64")
@Mapping("io.army.mapping.SqlCharType")
public String fileHash;

///  Mapping#value() should be one of below:
///  - SqlBigIntType
///  - StringType
///  - UUIDType
@Column(name = "${DEFAULT}", notNull = true, precision = Column.DEFAULT_EXP)
@Mapping("${DEFAULT}")
private String conversationId;

# Use Long-based conversation ID
com.example.stock.domain.StockChatVectorStore.conversationId.Mapping.value=io.army.mapping.SqlBigIntType

# Or use UUID-based
# com.example.stock.domain.StockChatVectorStore.conversationId.Mapping.value=io.army.mapping.UUIDType

// Auto-inferred: Integer[] → IntegerArrayType → INTEGER[]
@Column(name = "tag_ids")
private Integer[] tagIds;

// PostgreSQL ENUM array — element type inferred from field component type via reflection
@Mapping("io.army.mapping.array.NameEnumArrayType")
private Gender[] genders;

/// Java type: float[] → MappingType: VectorType → PostgreSQL: VECTOR
@Column(name = "${DEFAULT}", notNull = true,
        precision = Column.DEFAULT_EXP,  // required: embed dimension configured at runtime
        comment = "${DEFAULT}")
@Mapping("io.army.mapping.VectorType")
private float[] embedding;

// Long-term chat memory vector store — uses HNSW index with cosine similarity
@Table(name = "stock_chat_vector_store",
        indexes = {
                @Index(name = "${DEFAULT_VALUE}", type = "hnsw",
                       fields = @IndexField(name = "embedding",
                                            opclass = "vector_cosine_ops")),
                @Index(name = "${DEFAULT_VALUE}", fieldList = "conversationId"),
                @Index(name = "${DEFAULT_VALUE}", type = "gin", fieldList = "metadata")
        },
        comment = "stock chat long-term memory vector store")
public class StockChatVectorStore extends SpringAiChatVectorStore {
}

// Document vector store — uses HNSW index with L2 (Euclidean) distance
@Table(name = "stock_document_vector_store",
        indexes = {
                @Index(name = "${DEFAULT_VALUE}", type = "hnsw",
                       fields = @IndexField(name = "embedding",
                                            opclass = "vector_l2_ops")),
                @Index(name = "${DEFAULT_VALUE}", unique = true, fieldList = "documentId"),
                @Index(name = "${DEFAULT_VALUE}", type = "gin", fieldList = "metadata")
        },
        comment = "stock document vector store")
public class StockDocumentVectorStore extends SpringAiVectorStore {
}

@Column(name = "${DEFAULT}", notNull = true, defaultValue = "'{}'", comment = "${DEFAULT}")
@Mapping("io.army.mapping.PreferredJsonbType")
private Map<String, Object> metadata;

/// store one of below :
/// 1. AssistantMessage.getToolCalls()
/// 2. ToolResponseMessage.getResponses()
@Column(name = "${DEFAULT}", notNull = true, defaultValue = "'[]'",
        comment = "${DEFAULT}")
@Mapping("io.army.mapping.PreferredJsonbType")
private String specializedData;

// Inside ArmyMessageChatMemory.copyMessageInfo()
if (message instanceof AssistantMessage a) {
    o.setSpecializedData(codec.encode(a.getToolCalls()));
} else if (message instanceof ToolResponseMessage t) {
    o.setSpecializedData(codec.encode(t.getResponses()));
}

@Column(notNull = true, defaultValue = "'[]'", comment = "vector ID list")
@Mapping("io.army.mapping.PreferredJsonbType")
private List<Long> vectorIdList;

/// Custom mapping: maps a Java `Currency` record to PostgreSQL `NUMERIC(10,2)`.
public final class CurrencyType extends UserMappingType   // io.army.mapping.UserMappingType
        implements MappingType.SqlDecimal {

    // 1. Static factory method — required for @Mapping resolution
    public static CurrencyType from(final Class<?> javaType) {
        if (javaType != Currency.class) {
            throw errorJavaType(CurrencyType.class, javaType);
        }
        return INSTANCE;
    }

    public static final CurrencyType INSTANCE = new CurrencyType();

    // 2. Constructor must be non-public (private or package-private)
    private CurrencyType() {
    }

    // 3. Declare the Java type this mapping handles
    @Override
    public Class<?> javaType() {
        return Currency.class;
    }

    // 4. Map to the concrete SQL DataType per database
    @Override
    public DataType map(final ServerMeta meta) {
        final DataType dataType;
        switch (meta.serverDatabase()) {
            case PostgreSQL:
                dataType = PgType.NUMERIC;
                break;
            case MySQL:
                dataType = MySQLType.DECIMAL;
                break;
            default:
                throw mapError(this, meta);
        }
        return dataType;
    }

    // 5. Serialize Java value → SQL parameter
    @Override
    public BigDecimal beforeBind(DataType dataType, MappingEnv env, Object source) {
        if (!(source instanceof Currency c)) {
            throw paramError(this, dataType, source, null);
        }
        return c.value();
    }

    // 6. Deserialize database value → Java object
    @Override
    public Currency afterGet(DataType dataType, MappingEnv env, Object source) {
        final Currency value;
        if (source instanceof Currency c) {
            value = c;
        } else if (source instanceof BigDecimal bd) {
            value = new Currency(bd);
        } else if (source instanceof String s) {
            value = new Currency(new BigDecimal(s));
        } else {
            throw dataAccessError(this, dataType, source, null);
        }
        return value;
    }

    // 7. Required: override hashCode/equals for singleton types
    @Override
    public int hashCode() {
        return System.identityHashCode(this);
    }

    @Override
    public boolean equals(Object obj) {
        return obj instanceof CurrencyType;
    }
}

/// Custom mapping: maps `Currency[]` to PostgreSQL `NUMERIC[]`.
public final class CurrencyArrayType extends UserArrayType
        implements MappingType.SqlArray {

    public static CurrencyArrayType from(final Class<?> javaType) {
        final CurrencyArrayType instance;
        if (javaType == Currency[].class) {
            instance = LINEAR;
        } else if (javaType == Object.class) {
            instance = UNLIMITED;
        } else if (!javaType.isArray()) {
            throw errorJavaType(CurrencyArrayType.class, javaType);
        } else if (ArrayUtils.underlyingComponent(javaType) == Currency.class) {
            instance = new CurrencyArrayType(javaType);
        } else {
            throw errorJavaType(CurrencyArrayType.class, javaType);
        }
        return instance;
    }

    /// Used for default array parsing when the database returns an array
    /// of unknown dimensions. Typically consumed by {@code io.army.dialect.MappingHandler}
    /// implementations.
    public static final CurrencyArrayType UNLIMITED = new CurrencyArrayType(Object.class);

    public static final CurrencyArrayType LINEAR = new CurrencyArrayType(Currency[].class);

    private final Class<?> javaType;

    /// private constructor
    private CurrencyArrayType(Class<?> javaType) {
        this.javaType = javaType;
    }

    @Override
    public final Class<?> javaType() {
        return this.javaType;
    }

    @Override
    public final Class<?> underlyingJavaType() {
        return Currency.class;
    }

    @Override
    public final DataType map(final ServerMeta meta) {
        final DataType dataType;
        switch (meta.serverDatabase()) {
            case PostgreSQL:
                dataType = PgType.NUMERIC_ARRAY;
                break;
            default:
                throw mapError(this, meta);
        }
        return dataType;
    }

    @Override
    public final MappingType elementType() {
        final MappingType instance;
        final Class<?> javaType = this.javaType;
        if (javaType == Object.class) { // unlimited dimension array
            instance = this;
        } else if (javaType == Currency[].class) {
            instance = CurrencyType.INSTANCE;
        } else {
            instance = from(javaType.getComponentType());
        }
        return instance;
    }

    @Override
    public MappingType arrayTypeOfThis() throws CriteriaException {
        final Class<?> javaType = this.javaType;
        if (javaType == Object.class) { // unlimited dimension array
            return this;
        }
        return from(ArrayUtils.arrayClassOf(javaType));
    }

    // beforeBind / afterGet omitted for brevity — see built-in array types for reference

    @Override
    public int hashCode() {
        return this.javaType.hashCode();
    }

    @Override
    public boolean equals(Object obj) {
        final boolean match;
        if (obj == this) {
            match = true;
        } else if (obj instanceof CurrencyArrayType o) {
            match = o.javaType == this.javaType;
        } else {
            match = false;
        }
        return match;
    }
}

// SELECT entry
Select stmt = SQLs.query()...asQuery();

// INSERT entry
Insert stmt = SQLs.singleInsert()...asInsert();

// UPDATE entries
Update stmt = SQLs.singleUpdate()...asUpdate();   // single table
Update stmt = SQLs.domainUpdate()...asUpdate();   // domain (primarily child table)

// DELETE entries
Delete stmt = SQLs.singleDelete()...asDelete();   // single table
Delete stmt = SQLs.domainDelete()...asDelete();   // domain (primarily child table)

// Batch domain variants
BatchUpdate bStmt = SQLs.batchDomainUpdate()...asUpdate().namedParamList(paramList);
BatchDelete bDel = SQLs.batchDomainDelete()...asDelete().namedParamList(paramList);