Glossary

Relevant source files

• APIJSONORM/src/main/java/apijson/RequestMethod.java
• APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java
• APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java
• APIJSONORM/src/main/java/apijson/orm/Operation.java
• CONTRIBUTING.md
• Document-Chinese.md
• Document.md
• README-Chinese.md
• README.md

Purpose and Scope

This page serves as the official reference glossary for APIJSON-specific terminology, protocol keywords, architectural constructs, and database/security entities. It defines concepts ranging from JSON request syntax modifiers (e.g., @combine) and query resolution strategies (e.g., APP JOIN) to security roles (Visitor), configuration mappings (RAW_MAP), and metadata models (Access and Request tables). Each entry is accompanied by technical descriptions, data flow insights, and code pointers to help developers navigate the codebase efficiently.

---

1. Terminology Index

APP JOIN

• Definition: A strategy used by APIJSON to resolve multi-table associations and joins at the application layer rather than relying exclusively on traditional SQL database JOIN clauses. When client JSON requests reference fields across separate entities (e.g., matching a Moment to its publisher User via reference paths), the parser executes separate queries or batches them efficiently, assembling the nested JSON structure programmatically in memory (AbstractSQLExecutor).
• Code Pointers:
  • apijson.orm.AbstractSQLExecutor APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java
  • apijson.orm.Join APIJSONORM/src/main/java/apijson/orm/Join.java

Tag

• Definition: A logical group identifier or entity name (typically corresponding to a table name or custom method category) used in request routing, access control configuration (ACCESS_MAP), and structure validation (REQUEST_MAP). For example, the User tag governs permissions and rules associated with user records.
• Code Pointers:
  • apijson.orm.AbstractVerifier APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java118-120

@combine

• Definition: A query combination keyword used to define complex logical relationships (such as combining multiple conditions with AND or OR semantics) across fields or groups of keys in a query filter, superseding default single-operator evaluations.
• Code Pointers:
  • apijson.orm.AbstractSQLConfig APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java62-67

Visitor

• Definition: Represents the context of the user or client making the API request, containing authentication state, user ID, contact lists, and role assignments (UNKNOWN, LOGIN, CONTACT, CIRCLE, OWNER, ADMIN) used by the verifier during permission checks.
• Code Pointers:
  • apijson.orm.Verifier APIJSONORM/src/main/java/apijson/orm/Verifier.java
  • apijson.orm.AbstractVerifier APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java74-96

Access Table (Access)

• Definition: A configuration database table that defines Role-Based Access Control (RBAC) policies per table and request method. It maps which user roles are permitted to perform specific operations (e.g., GET, POST, PUT, DELETE) on specific entity tags.
• Code Pointers:
  • apijson.orm.model.Access APIJSONORM/src/main/java/apijson/orm/model/Access.java
  • apijson.orm.AbstractVerifier APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java111-115

Request Table (Request)

• Definition: A configuration database table and metadata registry that enforces structure validation rules (MUST, REFUSE, TYPE, VERIFY, etc.) for specific request tags and versions, ensuring clients send well-formed and authorized payloads.
• Code Pointers:
  • apijson.orm.model.Request APIJSONORM/src/main/java/apijson/orm/model/Request.java
  • apijson.orm.AbstractVerifier APIJSONORM/src/main/java/apijson/orm/model/Request.java

RAW_MAP

• Definition: A static configuration map in AbstractSQLConfig that allows developers to register custom raw SQL fragments or substrings mapped to specific keys. When invoked, these raw snippets bypass standard escaping or column mapping to allow advanced database expressions.
• Code Pointers:
  • apijson.orm.AbstractSQLConfig APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java101-102

Fake Delete

• Definition: A soft-delete mechanism where delete operations (DELETE) do not physically remove rows from the database table. Instead, the framework updates a designated status column (configured via KEY_DELETED_KEY and KEY_DELETED_VALUE) to mark records as deleted, while automatically filtering them out of subsequent GET queries using KEY_NOT_DELETED_VALUE.
• Code Pointers:
  • apijson.orm.AbstractSQLConfig APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java57-59
  • apijson.orm.AbstractVerifier APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java115

Subquery

• Definition: A nested query structure generated dynamically when request filters reference values or datasets from other tables or parent objects (using operators like exists, in, or reference paths), compiled into standard SQL subselects or executed via APP JOIN batching.
• Code Pointers:
  • apijson.orm.AbstractSQLConfig APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java

Operation

• Definition: An enumeration defining structural validation and modification directives applied to request fields, including MUST, REFUSE, TYPE, VERIFY, EXIST, UNIQUE, INSERT, UPDATE, REPLACE, REMOVE, IF, and ALLOW_PARTIAL_UPDATE_FAIL.
• Code Pointers:
  • apijson.orm.Operation APIJSONORM/src/main/java/apijson/orm/Operation.java11-165

RequestMethod

• Definition: An enumeration extending standard HTTP verbs with APIJSON-specific execution modes (GET, HEAD, GETS, HEADS, POST, PUT, DELETE, CRUD). GETS and HEADS encapsulate secure/private read operations transmitted via POST to protect sensitive query parameters.
• Code Pointers:
  • apijson.RequestMethod APIJSONORM/src/main/java/apijson/RequestMethod.java14-54

---

2. Conceptual Mapping to Code Entities

The following diagrams illustrate how high-level APIJSON concepts map directly to underlying Java classes and runtime components within the codebase.

Diagram: Glossary Term to Code Entity Mapping

Sources: APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java

Diagram: Protocol Keyword and Operation Resolution Flow

Sources: APIJSONORM/src/main/java/apijson/RequestMethod.java APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java

---

Sources:

• APIJSONORM/src/main/java/apijson/RequestMethod.java
• APIJSONORM/src/main/java/apijson/orm/AbstractSQLConfig.java
• APIJSONORM/src/main/java/apijson/orm/AbstractSQLExecutor.java
• APIJSONORM/src/main/java/apijson/orm/AbstractVerifier.java
• APIJSONORM/src/main/java/apijson/orm/Operation.java
• APIJSONORM/src/main/java/apijson/orm/Verifier.java