Skip to main content

UserContext – Customizible Core Runtime of TeaQL

Overview​

UserContext is the central runtime context of the TeaQL framework.
It represents a rich, request-scoped execution environment that unifies data access, request/response handling, validation, internationalization, concurrency control, logging, caching, and UI feedback.

In practice, UserContext functions as a combination of:

  • Application Context
  • Request Context
  • Unit of Work
  • Infrastructure Facade

It is the backbone that allows TeaQL to remain domain-centric and framework-agnostic.

Key Responsibilities​

1. Query Execution & Data Access Hub​

UserContext is the primary entry point for executing TeaQL requests and entity operations:

  • Execute SearchRequest for single entity, list, or stream
  • Perform aggregation queries
  • Persist entity graphs
  • Reload entities from persistence

This centralizes all runtime execution logic and decouples domain logic from repositories.

2. Repository & Metadata Resolution​

Through TQLResolver, UserContext dynamically resolves:

  • Repositories
  • Entity descriptors and metadata
  • Framework-managed beans

This design avoids direct dependency on Spring and enables TeaQL to run in different environments.

3. Request & Response Abstraction​

UserContext abstracts HTTP-level details by delegating to RequestHolder and ResponseHolder:

  • HTTP method, headers, parameters, and body
  • Client IP and proxy chain resolution
  • Response header manipulation
  • UI commands (toast, back, home)

Business logic remains independent of the underlying web framework.

4. Local Context Storage (Request Scope)​

A built-in local storage provides request-scoped state management:

  • Temporary data sharing
  • Validation error accumulation
  • Deduplication and flags

This replaces ad-hoc ThreadLocal or request attributes with a structured API.

5. Entity Validation & Error Translation​

UserContext orchestrates the full validation pipeline:

  • Entity-specific Checker execution
  • Batch and single-entity validation
  • Precise error location tracking
  • Natural language error translation

Validation errors are translated into human-readable messages and raised as structured exceptions.

6. Natural Language Translation & i18n​

Validation errors and messages support multilingual output:

  • English by default
  • Chinese view-oriented translation when configured
  • Pluggable translator mechanism

This operates at the domain semantic level, not just UI text.

7. Concurrency Control & Task Execution​

UserContext provides built-in task execution with locking semantics:

  • Local locks and distributed locks
  • Synchronous and asynchronous execution
  • Single-instance task execution (non-reentrant)

Typical use cases include scheduled jobs, idempotent actions, and background processing.

8. Centralized Logging Facade​

Logging methods automatically resolve the caller class:

  • Supports INFO / DEBUG / WARN / ERROR levels
  • Marker-aware logging
  • Eliminates repetitive logger definitions

This simplifies consistent logging across the system.

9. UI Feedback & Flow Control​

The context supports UI-oriented feedback mechanisms:

  • Toast notifications
  • Navigation commands (back, home)
  • Duplicate form submission protection
  • Business-level error messaging

These features enable smooth integration with front-end clients without tight coupling.

10. Lifecycle Hooks & Extensibility​

UserContext defines extensibility points for future evolution:

  • beforeCreate / beforeUpdate / beforeDelete
  • afterLoad
  • Event dispatch hooks

These hooks support auditing, domain events, and cross-cutting concerns.

Architectural Significance​

From an architectural perspective, UserContext acts as:

The runtime container and execution boundary of TeaQL

It allows:

  • Entities to remain persistence-agnostic
  • Requests to be transport-agnostic
  • Business logic to be infrastructure-agnostic

All infrastructure concerns are centralized and accessed through a single, coherent abstraction.

Summary​

Without UserContext, TeaQL would be merely a DSL.
With UserContext, TeaQL becomes a complete, executable runtime framework.

UserContext enables TeaQL to scale from simple CRUD to complex, distributed, and multilingual enterprise systems while maintaining clean domain boundaries.