Service Runtime & Helpers
Relevant source files
The following files were used as context for generating this wiki page:
The Service Runtime & Helpers module provides the internal infrastructure required to execute the Oracle WMS Singer target within the FLEXT ecosystem. It acts as a bridge between the Meltano-based Singer protocol and the specific requirements of Oracle WMS, handling message adaptation, data transformation, and configuration validation.
This module ensures that incoming Singer messages (SCHEMA, RECORD, STATE) are correctly normalized and routed to the Oracle WMS runtime. It leverages a set of specialized helper classes to manage table mappings, convert data types, and enforce structural constraints required for successful data loading into Oracle WMS environments.
Sources: src/flext_target_oracle_wms/_utilities/service_runtime.py, src/flext_target_oracle_wms/_utilities/helpers.py
Service Runtime Architecture
The service runtime is designed around the FlextTargetOracleWmsServiceRuntime class, which implements internal adapters for the service facade. This architecture utilizes a delegation pattern where a specialized Singer Sink (Sink) wraps the underlying Oracle WMS runtime target.
Runtime Components
| Component | Description |
|---|---|
FlextTargetOracleWmsServiceRuntime | Main entry point for creating service-level Singer sinks. |
Target | A minimal Singer target implementation inheriting from Meltano.SingerTargetBase. |
Sink | An adapter that delegates record processing to the Oracle WMS runtime target. |
Sources: src/flext_target_oracle_wms/_utilities/service_runtime.py:11-20
Message Flow
The runtime manages the flow of data from Singer-compliant streams into the Oracle WMS target logic. The following diagram illustrates the sequence of operations when a record is processed:
Data Transformation & Mapping
The FlextTargetOracleWmsUtilitiesHelpers class contains the core logic for preparing data for the Oracle WMS API. This involves mapping Singer schemas to Oracle structures and converting data types.
WMS Data Transformer
The WMSDataTransformer handles the conversion of incoming RECORD messages. A critical feature of this transformer is that it uppercases all keys in the record to align with Oracle WMS naming conventions.
Sources: src/flext_target_oracle_wms/_utilities/helpers.py:73-86, tests/unit/test_sinks.py:77-83
WMS Type Converter
The WMSTypeConverter ensures that scalar values are Oracle-friendly. It handles complex types (objects/arrays) by serializing them to JSON strings and attempts to preserve numeric types while defaulting to strings for other data.
| Source Type | Transformation Logic |
|---|---|
object, array | Serialized to JSON string using UTF-8 encoding. |
integer, number | Converted to int or float if possible; otherwise kept as str. |
string | Passed through as str. |
Sources: src/flext_target_oracle_wms/_utilities/helpers.py:45-66
Schema Mapping
The WMSSchemaMapper is responsible for building normalized schema maps. It specifically updates the table_name attribute to be the uppercase version of the stream name, ensuring consistency across the integration.
Sources: src/flext_target_oracle_wms/_utilities/helpers.py:119-138
Management & Validation
The system includes dedicated managers for stateful information during the target execution.
Table Manager
The WMSTableManager maintains an in-memory mapping between Singer stream names and their corresponding Oracle WMS table names.
Configuration Validation
The Validation helper ensures that the target settings meet the minimum requirements before execution begins.
| Required Field | Purpose |
|---|---|
base_url | The endpoint for the Oracle WMS Cloud environment. |
username | Authentication credential. |
password | Authentication credential. |
The validator also checks the load_method, which must be one of the valid methods defined in FlextTargetOracleWmsConstants (e.g., APPEND_ONLY, UPSERT, or MERGE).
Sources: src/flext_target_oracle_wms/_utilities/helpers.py:21-39, tests/unit/test_quality.py:53-58
Summary
The Service Runtime & Helpers module provides a robust foundation for the Oracle WMS target by automating protocol adaptation and data normalization. Through the use of delegated Sinks in the service_runtime.py and specialized utility classes in helpers.py, the system ensures that Singer data is reliably transformed and validated according to Oracle WMS requirements.