Protocols & Abstractions
Relevant source files
The following files were used as context for generating this wiki page:
The Protocols and Abstractions in the flext-target-oracle-oic project establish a strictly typed, layered architecture for interacting with Oracle Integration Cloud (OIC) within the Singer/Meltano ecosystem. This system relies on Multiple Inheritance (MRO) to compose functionality from foundation protocols, domain-specific Oracle OIC logic, and Singer SDK target behaviors.
By adhering to the Principle of Dependency Inversion (DIP), the project depends on these abstractions rather than concrete implementations, ensuring that components like Sinks, Authenticators, and Models remain decoupled and testable.
Sources: src/flext_target_oracle_oic/protocols.py:12-25, AGENTS.md:120-130
Core Protocol Architecture
The protocol layer serves as the Type-Safe Single Source of Truth (SSOT) for the entire module. The primary protocol class, FlextTargetOracleOicProtocols, inherits from both FlextOracleOicProtocols and FlextMeltanoProtocols. This allows a single access point (p) to reach foundation results, service definitions, Oracle-specific logic, and Meltano target structures.
The diagram shows how the target-specific protocols aggregate interfaces from both the general OIC domain and the Meltano integration framework.
Sources: src/flext_target_oracle_oic/protocols.py:12-40
Test Protocol Extensions
In the testing suite, TestsFlextTargetOracleOicProtocols further extends these abstractions by merging FlextTestsProtocols with the production protocols. This enables test-specific namespaces for Docker and Factory abstractions alongside production OIC protocols.
Sources: tests/protocols.py:16-35
Sink and Target Abstractions
The project implements a hierarchical sink structure to handle different OIC resource types (Connections, Integrations, Packages, and Lookups). These abstractions manage the lifecycle of data records as they flow from the Singer stream into OIC.
Implementation Hierarchy
- FlextTargetOracleOic (Main Entry): Inherits from
FlextMeltanoTargetAbstractions. It acts as the orchestrator, mapping stream names to specific sink classes. - FlextTargetOracleOicBaseSink: Provides the standard implementation for Singer hooks like
process_batchandprocess_record. - Specialized Sinks: Concrete classes (e.g.,
FlextTargetOracleOicConnectionsSink) that inherit from the base sink to handle stream-specific logic.
The flow depicts the resolution of stream-specific sinks from the central Target class.
Sources: src/flext_target_oracle_oic/target.py:20-80
Domain Model Abstractions
Data structures are defined using Pydantic-based domain models within the FlextTargetOracleOicModels namespace. These models ensure that incoming Singer records conform to the required schemas for OIC API interactions.
| Model | Purpose | Key Fields |
|---|---|---|
OICConnection | Represents an OIC Connection resource. | id, name, adapter_type, properties |
OICIntegration | Represents an OIC Integration workflow. | id, name, version, pattern |
OICPackage | Represents a bundled OIC Package. | id, name, version |
OICLookup | Represents OIC DVM/Lookup tables. | name, columns, rows |
Sources: src/flext_target_oracle_oic/models.py:17-70
Authentication Abstraction
The Authenticator class within FlextTargetOracleOicUtilities abstracts the OAuth2 Client Credentials flow required by Oracle Integration Cloud. It manages token acquisition, caching, and header generation.
This diagram illustrates the internal logic of the Authenticator abstraction when a service requests a valid token.
Sources: src/flext_target_oracle_oic/utilities.py:65-115
Technical Governance and Standards
As defined in the project's engineering law, these abstractions must follow several strict principles:
- SSOT (Single Source of Truth): Identity, config, and contracts must have one authoritative source.
- SOLID Principles: Specifically focusing on Interface Segregation (ISP) and Dependency Inversion (DIP) through the use of Protocols.
- YAGNI: Only abstractions required for the current OIC streams are implemented.
- DI (Dependency Injection): Collaborators are injected via protocol-typed parameters rather than hard-wired globals.
Sources: AGENTS.md:110-135
The protocol-driven architecture of flext-target-oracle-oic ensures that the integration remains robust and maintainable by clearly separating the Singer SDK infrastructure from the specific domain models and authentication requirements of Oracle Integration Cloud.