Dispatcher & Base Classes
Relevant source files
The following files were used as context for generating this wiki page:
The FlextDbOracleDispatcher serves as a unified integration helper for flext-db-oracle services, bridging the gap between command-based messaging and the core database service layer. It is built upon the FlextService base class and utilizes a centralized command pattern to route database operations such as connection management, query execution, and schema introspection.
The architecture follows Clean Architecture principles, ensuring that the foundation layer (base classes and initialization) supports the higher-level application and domain layers. This separation allows the dispatcher to act as a factory and registration hub for various Oracle-specific command handlers.
Sources: src/flext_db_oracle/dispatcher.py:1-24, src/README.md:46-75
FlextDbOracleDispatcher Architecture
The dispatcher is responsible for wiring FlextDbOracleServices to a central command bus. It categorizes handlers into logical groups: connection management, query operations, and schema/metadata tasks.
Command Handler Categories
The dispatcher organizes Oracle operations into three primary handler sets:
| Category | Handlers | Purpose |
|---|---|---|
| Connection | connect, disconnect, test_connection | Manages lifecycle of the Oracle database session. |
| Query | execute_query, fetch_one, execute_statement, execute_many | Handles SQL execution and data retrieval. |
| Schema | get_schemas, get_tables, get_columns | Provides introspection into database objects and structures. |
Sources: src/flext_db_oracle/dispatcher.py:34-159
Dispatcher Initialization Flow
The following diagram illustrates how the dispatcher is built and wired to the underlying services.
The build_dispatcher method serves as a factory, ensuring all functional handlers are correctly registered to process incoming commands.
Sources: src/flext_db_oracle/dispatcher.py:64-91
Base Classes and Service Integration
The dispatcher inherits from FlextService, which provides the standard execution interface within the FLEXT ecosystem. It specifically identifies FlextContainer as its container type for dependency injection.
Core Handler Logic
The handlers within the dispatcher act as adapters. They validate command types, extract parameters, and call the corresponding methods on the FlextDbOracleServices facade.
- Result Wrapping: Every handler is wrapped in a function that ensures the return value is a
p.Result[t.JsonValue]. This maintains consistency across the messaging bus. - Command Validation: Query handlers specifically check if incoming data matches specific models like
m.DbOracle.ExecuteQueryCommandto safely extract SQL and parameters.
def _wrap(
fn: Callable[[t.JsonValue], t.JsonValue],
) -> Callable[[t.JsonValue], p.Result[t.JsonValue]]:
def wrapped(*args: t.JsonValue) -> p.Result[t.JsonValue]:
result = fn(*args)
return r[t.JsonValue].ok(result)
return wrapped
Sources: src/flext_db_oracle/dispatcher.py:27-31, src/flext_db_oracle/dispatcher.py:81-89
Service Interaction Sequence
When a command is dispatched, the following flow occurs:
The dispatcher simplifies the output for the command bus, often returning specific counts or formatted strings rather than complex database cursors.
Sources: src/flext_db_oracle/dispatcher.py:93-112, tests/unit/test_dispatcher.py:25-33
Key Implementation Details
Parameter Handling
In query-related handlers, the dispatcher utilizes m.ConfigMap.model_validate to transform raw JSON dictionaries into structured root models for database parameters. This ensures type safety when passing data to the infrastructure layer.
Sources: src/flext_db_oracle/dispatcher.py:100-103, src/flext_db_oracle/dispatcher.py:117-120
Schema Introspection
Schema handlers often concatenate results into comma-separated strings for compatibility with simple JSON-based messaging interfaces.
Sources: src/flext_db_oracle/dispatcher.py:151-158
Summary
The FlextDbOracleDispatcher and its foundation in the FLEXT base classes provide a standardized way to expose Oracle database operations to the broader application. By mapping internal FlextDbOracleServices logic to a command-based dispatcher, the system achieves a decoupled architecture where database tasks can be invoked via message passing while maintaining strict result contracts.
Sources: src/flext_db_oracle/dispatcher.py:27-32, src/README.md:103-120