Request Processing Pipeline

Relevant source files

• APIJSONORM/src/main/java/apijson/orm/AbstractObjectParser.java
• APIJSONORM/src/main/java/apijson/orm/AbstractParser.java
• APIJSONORM/src/main/java/apijson/orm/OnParseCallback.java

Purpose and Scope

This page traces the full lifecycle of an APIJSON request — from a raw JSON string entering AbstractParser to a JSON response map being returned. It covers global parameter extraction, verification gates, transaction management, recursive JSON tree parsing, per-table role enforcement, SQL construction and execution, caching, and response assembly.

The pipeline is primarily implemented in the apijson.orm package, centered around the AbstractParser class which orchestrates the flow between verification, object parsing, and SQL execution.

---

Top-Level Pipeline

The following diagram illustrates the end-to-end flow of a request through the core architectural components.

Diagram: Full Request Lifecycle Through Core Classes

Sources: apijson/orm/AbstractParser.java274-315 apijson/orm/AbstractObjectParser.java206-230 apijson/orm/AbstractParser.java625 apijson/orm/AbstractParser.java1010-1030

---

1. Request Initialization and Global Parameters

When parse(String request) is called, the AbstractParser first converts the string into a Map using JSON.parseObject apijson/orm/AbstractParser.java280-285 It then extracts global keywords that affect the entire execution context.

Configuration and Limits

The AbstractParser defines several static and instance-level limits to protect system resources:

• MAX_QUERY_COUNT: Maximum records per query (default 100) apijson/orm/AbstractParser.java78
• MAX_QUERY_DEPTH: Maximum recursion depth for nested objects (default 5) apijson/orm/AbstractParser.java83
• MAX_SQL_COUNT: Maximum number of SQL statements per request (default 200) apijson/orm/AbstractParser.java80
• MAX_OBJECT_COUNT: Maximum number of objects in a single request (default 5) apijson/orm/AbstractParser.java81

Global Keyword Extraction

The parser identifies special keys in the root JSON object:

Keyword	Description	Implementation Detail
tag	Identifies the Request structure for validation	setTag(tag) apijson/orm/AbstractParser.java269-272
version	API versioning for logic branching	setVersion(version) apijson/orm/AbstractParser.java258-261
@role	The permission role (e.g., ADMIN, OWNER)	setGlobalRole(role) apijson/orm/AbstractParser.java410-415
@database	Target database type (MYSQL, POSTGRESQL, etc.)	setGlobalDatabase(db) apijson/orm/AbstractParser.java420-425
@explain	If true, returns the SQL execution plan	setGlobalExplain(explain) apijson/orm/AbstractParser.java430-435

Sources: apijson/orm/AbstractParser.java69-123 apijson/orm/AbstractParser.java250-272 apijson/orm/AbstractParser.java410-435

---

2. The Recursive Parsing Logic

The core of APIJSON is its ability to handle deeply nested JSON structures. This is managed by the interplay between AbstractParser and AbstractObjectParser.

Object Parsing Flow (AbstractObjectParser)

For every JSON object in the request tree, an ObjectParser is created via onObjectParse apijson/orm/AbstractParser.java625-630

1. Entry Classification: The parser iterates through the object's keys, separating them into tables, functions, and child objects apijson/orm/AbstractObjectParser.java232-240
2. Special Keyword Handling: It checks for control keywords like KEY_TRY and KEY_DROP to determine if a failure in this object should fail the whole request apijson/orm/AbstractObjectParser.java97-102
3. SQL Configuration: For table keys, an AbstractSQLConfig is populated with filters, pagination, and join information apijson/orm/AbstractObjectParser.java69-85
4. Role Verification: Before execution, onVerifyRole(config) is called to ensure the requested role has access to the table and specific columns apijson/orm/AbstractObjectParser.java547
5. Execution: The SQLExecutor runs the generated SQL and returns the data apijson/orm/AbstractObjectParser.java551
6. Remote Functions: It handles function calls defined with key() syntax. These can be executed before SQL execution (-), after SQL but before children (0), or after children (+) apijson/orm/AbstractObjectParser.java184-190
7. Child Recursion: After the parent object is resolved, onChildParse() is triggered for nested objects apijson/orm/AbstractObjectParser.java194-195

Sources: apijson/orm/AbstractObjectParser.java69-240 apijson/orm/AbstractParser.java625-630

---

3. SQL Generation and Execution

The transition from "Natural Language Space" to "Code Entity Space" and finally "Database Space" happens through the SQLConfig and SQLExecutor components.

Diagram: JSON to SQL Mapping

Key Execution Steps:

1. SQL Building: The SQLExecutor calls config.gainSQL(false) to construct the SQL string based on the database dialect apijson/orm/AbstractObjectParser.java551
2. Statement Management: AbstractSQLExecutor obtains and executes a java.sql.Statement or PreparedStatement.
3. Result Conversion: The database ResultSet is processed into a Map (M) apijson/orm/AbstractObjectParser.java222-223
4. Transaction Isolation: The AbstractParser sets transaction isolation levels. For query methods (GET, HEAD), it defaults to TRANSACTION_NONE, while for update methods (POST, PUT, DELETE), it uses TRANSACTION_REPEATABLE_READ apijson/orm/AbstractParser.java247-249

Sources: apijson/orm/AbstractObjectParser.java550-560 apijson/orm/AbstractParser.java247-249 apijson/orm/AbstractObjectParser.java222-223

---

4. Response Assembly and Error Handling

Once the recursive tree traversal is complete, the AbstractParser finalizes the response:

1. Success Wrapping: If successful, it wraps the data in a standard format, adding a code: 200 and msg: "success" apijson/orm/AbstractParser.java380-385
2. Warning Collection: Any non-fatal issues (like null references or missing optional fields) are collected in warnMap and returned in the response apijson/orm/AbstractParser.java164-183
3. Error Handling: If an exception occurs (e.g., ConflictException), extendErrorResult(e) is called to generate a response with the appropriate error code and stack trace if IS_RETURN_STACK_TRACE is enabled apijson/orm/AbstractParser.java390-395 apijson/orm/AbstractParser.java69
4. Transaction Finalization: The parser calls commit() if all operations succeeded, or rollback() if any part of a multi-statement request failed apijson/orm/AbstractParser.java1020-1030

Sources: apijson/orm/AbstractParser.java69 apijson/orm/AbstractParser.java164-183 apijson/orm/AbstractParser.java380-395 apijson/orm/AbstractParser.java1020-1030