API Client Implementation

Relevant source files

The following files were used as context for generating this wiki page:

• src/flext_target_oracle_wms/_utilities/client.py
• src/flext_target_oracle_wms/_utilities/helpers.py
• src/flext_target_oracle_wms/utilities.py
• tests/integration/test_oracle.py
• tests/unit/test_target.py
• examples/01_basic_usage.py

The API Client Implementation in flext-target-oracle-wms facilitates the ingestion and transformation of Singer-compliant data streams into Oracle WMS Cloud SaaS environments. It acts as the primary runtime coordinator, managing the lifecycle of data extraction from standard input (stdin) or file sources and ensuring subsequent processing into target-compatible formats. The implementation leverages a modular architecture composed of catalog management, stream processing, and data transformation utilities.

The core of the implementation is the Target class, which orchestrates the handling of SCHEMA, RECORD, and STATE messages. It utilizes specialized helpers to uppercase keys, convert data types, and maintain stream-to-table mappings, ensuring strict compliance with Oracle's data structure requirements while maintaining the stateful progress of the integration.

Architecture Overview

The architecture is divided into high-level runtime orchestration and low-level utility helpers. The FlextTargetOracleWmsUtilities class serves as a facade, exposing these components under a unified namespace.

Core Components

Component	Description
Target	The main entry point that handles message dispatching and lifecycle methods (setup, run, cleanup).
CatalogManager	Manages in-memory storage for stream metadata and Singer catalog entries.
StreamProcessor	Coordinates the transformation of records by linking the Table Manager and Data Transformer.
WMSTableManager	Maps Singer streams to Oracle-friendly table names (typically uppercased).
WMSDataTransformer	Handles the mapping of record keys to uppercase and invokes the type converter for values.

Sources: src/flext_target_oracle_wms/_utilities/client.py:99-122, src/flext_target_oracle_wms/utilities.py:20-40, src/flext_target_oracle_wms/_utilities/helpers.py:102-108

System Data Flow

The following diagram illustrates how Singer messages flow through the target implementation:

The Target runtime parses raw JSON lines and dispatches them to specific handlers based on the message type. Record transformation relies on schema information previously registered via Schema messages.
Sources: src/flext_target_oracle_wms/_utilities/client.py:165-195, tests/unit/test_target.py:155-165

Client Implementation Details

Target Runtime Coordination

The Target class (accessible as u.TargetOracleWms.Target) manages the overall execution. It validates incoming configuration against the WmsTargetConfig model and maintains the internal state of registered schemas.

class Target:
    name = "target-oracle-wms"
    
    def __init__(self, settings: t.JsonMapping | m.TargetOracleWms.WmsTargetConfig) -> None:
        self.settings = m.TargetOracleWms.WmsTargetConfig.model_validate(settings)
        self.catalog_manager = FlextTargetOracleWmsUtilitiesClient.CatalogManager()
        self.table_manager = FlextTargetOracleWmsUtilitiesHelpers.WMSTableManager()
        self.stream_processor = FlextTargetOracleWmsUtilitiesClient.StreamProcessor(
            self.table_manager, self.data_transformer
        )

Sources: src/flext_target_oracle_wms/_utilities/client.py:107-124

Message Handling Logic

The client processes three primary message types as defined in the Singer protocol:

1. SCHEMA: Registered in the CatalogManager and used to initialize the StreamProcessor. The stream name is mapped to an Oracle table name (e.g., "inventory" becomes "INVENTORY").
2. RECORD: Transformed using the registered schema. The WMSDataTransformer ensures all keys are uppercased and values are converted to appropriate Oracle types.
3. STATE: Logged and acknowledged to allow the Singer tap to track progress.

Sources: src/flext_target_oracle_wms/_utilities/client.py:133-163, src/flext_target_oracle_wms/_utilities/helpers.py:146-160

Data Transformation and Mapping

Type Conversion

The WMSTypeConverter is responsible for translating Singer types into Oracle-friendly formats. It handles objects and arrays by serializing them to JSON strings and ensures numeric values are correctly identified as integers or floats.

The sequence shows the internal delegation from the transformer to the type converter for every field in a record.
Sources: src/flext_target_oracle_wms/_utilities/helpers.py:44-64

Configuration Parameters

The client requires specific configuration provided through a JSON mapping or environment variables.

Parameter	Type	Required	Description
base_url	String	Yes	The URL of the Oracle WMS Cloud environment.
username	String	Yes	Authentication username.
password	String	Yes	Authentication password.
load_method	String	No	Defaults to APPEND_ONLY. Also supports UPSERT and MERGE.
batch_size	Integer	No	Number of records to process in a single batch.

Sources: src/flext_target_oracle_wms/_utilities/helpers.py:23-38, examples/01_basic_usage.py:27-31, tests/unit/test_target.py:19-27

Integration Patterns

Catalog and Table Management

The CatalogManager stores SingerCatalogEntry objects. When a schema is registered, the WMSTableManager automatically generates a table name by uppercasing the stream name, ensuring consistency with Oracle database conventions.

The relationship between managers shows how the StreamProcessor acts as a middle layer utilizing the WMSTableManager.
Sources: src/flext_target_oracle_wms/_utilities/client.py:28-66, src/flext_target_oracle_wms/_utilities/helpers.py:140-155

Implementation Example

A basic implementation involves instantiating the utilities and registering streams manually or via file processing.

from flext_target_oracle_wms import FlextTargetOracleWmsUtilities
tm = FlextTargetOracleWmsUtilities.TargetOracleWms.WMSTableManager()
tm.register_stream("orders") # Results in table "ORDERS"

Sources: examples/01_basic_usage.py:38-41, src/flext_target_oracle_wms/utilities.py:38

Conclusion

The API Client Implementation provides a robust, state-aware framework for loading Singer data into Oracle WMS. By isolating concerns between the CatalogManager, StreamProcessor, and WMSDataTransformer, the system ensures that complex data types and naming conventions are handled automatically during the ETL process. The use of Pydantic models for configuration validation and the Result pattern for error handling ensures high reliability in production data pipelines.