Core ORM Architecture

Relevant source files

• APIJSONORM/pom.xml
• APIJSONORM/src/main/java/apijson/Log.java
• APIJSONORM/src/main/java/apijson/orm/Parser.java
• APIJSONORM/src/main/java/apijson/orm/SQLConfig.java

This document provides a detailed technical dive into the APIJSONORM library's internal architecture and component design. It explains how the system transforms JSON requests into database queries and structured responses through a series of specialized abstract components.

For information about the APIJSON protocol and JSON request/response format, see APIJSON Protocol. For database-specific configuration and multi-database support, see Database Support. For security and access control mechanisms, see Security and Access Control.

---

Component Architecture Overview

APIJSONORM follows a template method pattern where abstract base classes define the ORM logic and concrete implementations provide environment-specific behavior (e.g., database drivers, connection pools).

Core ORM Components

Component	Code Entity	Primary Role
Parser	Parser	Interface orchestrating the overall request lifecycle and managing global state like version and tag. APIJSONORM/src/main/java/apijson/orm/Parser.java18-19
SQL Config	SQLConfig	Interface for building SQL statements, handling dialects, and managing whitelists for tables and columns. APIJSONORM/src/main/java/apijson/orm/SQLConfig.java18
Object Parser	ObjectParser	Decomposes JSON objects into table-specific configurations and handles recursive parsing. APIJSONORM/src/main/java/apijson/orm/ObjectParser.java18
SQL Executor	SQLExecutor	Executes JDBC statements, manages connections, and implements result caching. APIJSONORM/src/main/java/apijson/orm/SQLExecutor.java18
Verifier	Verifier	Enforces RBAC and structural validation rules. APIJSONORM/src/main/java/apijson/orm/Verifier.java15
Function Parser	FunctionParser	Executes remote functions via script engines or Java reflection. APIJSONORM/src/main/java/apijson/orm/FunctionParser.java14

Architecture Diagram: Code Entity Space

The following diagram maps the logical ORM flow to the specific classes and interfaces in the codebase.

Sources: APIJSONORM/src/main/java/apijson/orm/Parser.java18-134 APIJSONORM/src/main/java/apijson/orm/SQLConfig.java18-196 APIJSONORM/src/main/java/apijson/orm/ObjectParser.java18-50

---

Request Processing Pipeline

The ORM processes requests through a recursive descent pipeline. Each nested JSON object or array triggers a new parsing context.

1. Initialization: The Parser extracts global parameters like tag, role, and version via setTag, setRole, and setVersion. APIJSONORM/src/main/java/apijson/orm/Parser.java29-33
2. Validation: Verifier checks user permissions and validates the request structure via onVerifyLogin, onVerifyContent, and onVerifyRole. APIJSONORM/src/main/java/apijson/orm/Parser.java101-103
3. Decomposition: Parser triggers parsing via parse(M request) APIJSONORM/src/main/java/apijson/orm/Parser.java51 For each object, it calls createObjectParser to initialize a configuration context. APIJSONORM/src/main/java/apijson/orm/Parser.java83
4. SQL Generation: SQLConfig generates the SQL string via gainSQL(boolean prepared). APIJSONORM/src/main/java/apijson/orm/SQLConfig.java196
5. Execution: SQLExecutor handles the database interaction through executeSQL(SQLConfig config, boolean isSubquery). APIJSONORM/src/main/java/apijson/orm/Parser.java105
6. Assembly: Results are recursively assembled into the final response structure via parseResponse. APIJSONORM/src/main/java/apijson/orm/Parser.java53-54

For a step-by-step walkthrough, see Request Processing Pipeline.

---

SQLConfig: SQL Generation Engine

SQLConfig is the core of APIJSON's "zero-code" SQL generation. It transforms high-level JSON logic into secure, optimized SQL across multiple dialects.

Database Support

APIJSON supports a wide range of databases, defined as constants in the SQLConfig interface:

• Relational: DATABASE_MYSQL, DATABASE_POSTGRESQL, DATABASE_SQLSERVER, DATABASE_ORACLE, DATABASE_MARIADB. APIJSONORM/src/main/java/apijson/orm/SQLConfig.java20-25
• NewSQL/Distributed: DATABASE_TIDB, DATABASE_COCKROACHDB, DATABASE_OPENGAUSS. APIJSONORM/src/main/java/apijson/orm/SQLConfig.java26-54
• OLAP/BigData: DATABASE_CLICKHOUSE, DATABASE_DORIS, DATABASE_SNOWFLAKE. APIJSONORM/src/main/java/apijson/orm/SQLConfig.java32-37
• NoSQL/Specialized: DATABASE_REDIS, DATABASE_MONGODB, DATABASE_ELASTICSEARCH, DATABASE_MILVUS. APIJSONORM/src/main/java/apijson/orm/SQLConfig.java30-49

SQL Dialect Mapping: Natural Language to Code

This diagram shows how user-provided JSON operators and keywords are mapped to internal configuration logic within SQLConfig.

For details on SQL generation and dialect handling, see SQL Configuration and Generation.

Sources: APIJSONORM/src/main/java/apijson/orm/SQLConfig.java20-56 APIJSONORM/src/main/java/apijson/orm/SQLConfig.java203-247

---

SQLExecutor: Execution and Transaction Management

SQLExecutor manages the physical interaction with the database and provides hooks for performance monitoring and transaction control.

• Performance Constraints: The Parser enforces limits on execution such as getMaxSQLCount, getMaxQueryDepth, and getMaxUpdateCount. APIJSONORM/src/main/java/apijson/orm/Parser.java89-93
• Transaction Control: The Parser interface provides methods for transaction management which are delegated to the executor, including begin(int isolation), commit(), and rollback(). APIJSONORM/src/main/java/apijson/orm/Parser.java125-128
• Result Handling: Successful operations return a result via newSuccessResult(), while failures are encapsulated via newErrorResult(Exception e). APIJSONORM/src/main/java/apijson/orm/Parser.java131-132

For details on caching strategies and execution logic, see Database Execution and Caching.

Sources: APIJSONORM/src/main/java/apijson/orm/Parser.java85-132

---

Core Architecture Child Pages

• Component Overview — Detailed look at the primary interfaces and abstract classes.
• Request Processing Pipeline — The full lifecycle of an APIJSON request.
• SQL Configuration and Generation — How JSON is transformed into SQL across 30+ databases.
• Database Execution and Caching — JDBC execution, transaction management, and performance optimizations.
• JSON Request and Response Interfaces — Documentation of the JSONRequest and JSONResponse data structures.