Advanced Topics

Relevant source files

• APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java
• APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java

This page covers advanced APIJSON features and optimization techniques for production deployments, including caching strategies, performance tuning, distributed query execution, conditional operations, and transaction management. For basic CRUD operations and protocol syntax, see APIJSON Protocol. For security features, see Security and Access Control.

---

Overview of Advanced Capabilities

APIJSON provides several advanced mechanisms to handle complex requirements in production environments:

• Two-layer caching system for optimizing repeated queries and cross-reference resolution.
• Performance optimizations including SQL generation strategies like CTEs (WITH AS) and query profiling.
• Distributed query forwarding via @url directives for microservices integration.
• Conditional operations with flexible update/delete constraints and structural validation.
• Transaction management with automated lifecycle control for multi-statement operations.
• Fake delete (soft deletion) for data preservation and audit compliance.

These features are primarily implemented in the core ORM components: AbstractParser APIJSONORM/src/main/java/apijson/orm/AbstractParser.java39-40 AbstractSQLExecutor APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java28-29 and AbstractSQLConfig APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java27-28

---

7.1 Caching Strategies

APIJSON implements a two-layer caching architecture to minimize redundant database queries and optimize reference resolution. For details, see Caching Strategies.

Two-Layer Cache Architecture

Diagram: APIJSON Two-Layer Cache Implementation

Sources:

• APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java80-104
• APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java169-236

---

7.2 Performance Optimization

APIJSON provides several mechanisms to tune query performance, ranging from static configuration flags to advanced SQL features like CTEs and UNION. For details, see Performance Optimization.

Static Configuration Flags

The AbstractSQLConfig class provides static fields to control SQL generation and query behavior globally:

Static Field	Type	Default	Purpose	Location
ENABLE_WITH_AS	boolean	false	Enable CTE (Common Table Expressions)	APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java45
IS_HAVING_DEFAULT_AND	boolean	false	Use AND instead of OR for @having	APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java35
MAX_WHERE_COUNT	int	10	Max WHERE conditions per query	APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java62
MAX_COMBINE_DEPTH	int	2	Max nesting depth for @combine	APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java63

Sources:

• APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java32-67

Performance Metrics and Profiling

APIJSON tracks execution metrics in AbstractSQLExecutor APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java47-74 to help identify bottlenecks. These include generatedSQLCount APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java52-54 executedSQLCount APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java60-62 and executedSQLDuration APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java67-69 Global limits for query depth and count are enforced in AbstractParser.

---

7.3 Distributed Queries

Request Forwarding via @url

Distributed query support allows an APIJSON server to act as a gateway, forwarding specific object requests to remote APIJSON servers. For details, see Distributed Queries.

Execution Flow and Code Association:

Diagram: Distributed Query Forwarding Logic

Sources:

• APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java169-236

---

7.4 Conditional Operations and Fake Delete

APIJSON supports flexible constraints for mutation operations and a robust "Fake Delete" (soft delete) mechanism to preserve data. For details, see Conditional Operations and Fake Delete.

Operation Constraints

AbstractParser manages the validation lifecycle and supports ignoring empty or blank strings during operations via IGNORE_EMPTY_STRING_METHOD_LIST APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java50-55

Fake Delete Implementation

Fake delete is implemented by defining keys for the deleted status in AbstractSQLConfig APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java57-59 This allows the engine to transform DELETE requests into PUT updates or automatically filter out "deleted" records from GET results.

Key	Purpose
KEY_DELETED_KEY	The column name representing deletion status (e.g., "isDeleted")
KEY_DELETED_VALUE	The value representing a deleted state (e.g., 1 or true)
KEY_NOT_DELETED_VALUE	The value representing an active state (e.g., 0 or false)

Sources:

• APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java57-59

---

7.5 Transaction Management

APIJSON provides automated transaction management for complex multi-statement operations. For details, see Transaction Management.

Transaction Lifecycle

The transaction flow is managed within AbstractParser.

1. Begin: Transactions are initialized for mutation methods (POST, PUT, DELETE).
2. Execute: All sub-objects are parsed and SQL statements executed via executeUpdate APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java150-153
3. Commit/Rollback: Changes are committed if all operations succeed; otherwise, a rollback is triggered.
4. Close: Ensures the database connection is returned to the pool.

Isolation and Execution

Mutation operations (POST, PUT, DELETE) are executed via executeUpdate, while queries use executeQuery APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java145-148 The executor tracks executedSQLCount APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java49 and duration APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java64 to monitor transaction performance.

Sources:

• APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java145-160
• APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java47-74