Interfaces & Protocols
Relevant source files
The following files were used as context for generating this wiki page:
The flext-oracle-wms library provides a structured interface for integrating with Oracle Warehouse Management System (WMS) Cloud. It leverages enterprise-grade protocols to ensure type safety, reliability, and consistency across the FLEXT data integration platform. The system is built on a declarative architecture that separates endpoint definitions from the underlying transport logic, enabling automatic entity discovery and high-volume data processing.
Sources: src/README.md:14-35, src/flext_oracle_wms/README.md:46-60
Core Client Interface
The primary interface for interacting with Oracle WMS is the FlextOracleWmsClient. This client acts as the central orchestrator for all API operations, managing the lifecycle of connections and delegating specialized tasks to internal modules.
Client Lifecycle and State
The client follows a strict lifecycle involving initialization, starting, and stopping. It maintains internal state to track whether it has been started and stores discovered entity metadata.
The state machine above illustrates the operational lifecycle of the FlextOracleWmsClient.
Sources: src/flext_oracle_wms/_utilities/client.py:46-56, src/flext_oracle_wms/_utilities/client.py:167-183
Key Client Methods
The client exposes several high-level methods for data operations and system health checks:
| Method | Description | Return Type |
|---|---|---|
start() | Validates settings and initializes the underlying API client. | p.Result[bool] |
discover_entities() | Fetches the list of available WMS entities from the /entities endpoint. | p.Result[t.StrSequence] |
get_entity_data() | Retrieves records for a specific entity with support for limits and filters. | p.Result[t.SequenceOf[t.StrMapping]] |
health_check() | Performs a connectivity and status check against the WMS API. | p.Result[m.Api.HttpResponse] |
stop() | Releases resources and closes active connections. | p.Result[bool] |
Sources: src/flext_oracle_wms/_utilities/client.py:118-183
Authentication Protocols
The library supports multiple authentication methods required by Oracle WMS Cloud, including Basic, Bearer Token, and API Key. The Authenticator utility manages the generation of required headers based on the provided configuration.
Authentication Flow
The authentication process is synchronous and integrated into the client initialization. The client builds default headers by invoking the authenticator before any network requests are dispatched.
The sequence diagram shows how authentication headers are resolved during client setup.
Sources: src/flext_oracle_wms/_utilities/client.py:61-83, examples/03_complete_functionality_showcase.py:112-120
Declarative API Catalog
A cornerstone of the library's design is the declarative API catalog. Instead of hardcoding paths, endpoints are defined in a central catalog (api_catalog.py), which includes metadata such as versioning (e.g., LGF_V10), HTTP methods, and categories.
API Definition Structure
Each API entry in the catalog is accessed through the FlextOracleWmsApi class. This allows the client to dynamically route requests and provides a consistent interface for tools like Singer taps.
| Component | Purpose | Source Reference |
|---|---|---|
api_name | Unique identifier for the endpoint (e.g., company, item). | FlextOracleWmsApi.FLEXT_ORACLE_WMS_APIS |
method | The HTTP verb used (GET, POST, PUT, DELETE). | src/flext_oracle_wms/_utilities/client.py:202-212 |
version | The Oracle WMS API version string (typically LGF_V10). | tests/unit/test_declarative.py:65-71 |
category | Functional grouping (e.g., Inventory, Orders, Warehouse). | examples/03_complete_functionality_showcase.py:126-133 |
Sources: src/flext_oracle_wms/README.md:31-35, examples/03_complete_functionality_showcase.py:123-143
Error Handling and Result Pattern
The library strictly adheres to the Result Pattern (Railway-Oriented Programming). Most operations return a Result (often aliased as p.Result or r), which contains either the successful value or an error description.
Error Categories
Errors are categorized to allow for specific recovery strategies:
- Validation Errors: Issues with input settings or data models.
- Connection Errors: Failures at the network or transport layer.
- API Errors: Non-2xx responses from the Oracle WMS Cloud service.
# Example of handling the Result protocol
result = client.get_entity_data("inventory")
if result.success:
data = result.value # Access successful data
else:
logger.error(f"Query failed: {result.error}") # Handle failure
Sources: src/README.md:104-120, src/flext_oracle_wms/README.md:121-143, src/flext_oracle_wms/_utilities/client.py:214-222
Singer Protocol Compatibility
For data pipeline integration, the library provides utilities to transform Oracle WMS entity schemas into Singer-compatible formats. This includes flattening nested structures and generating standard JSON schemas for streams.
Data Flow for Singer Integration
- Discovery: Client fetches entity list.
- Inspection: Utility performs a "Focused Discovery" by sampling data to determine field types.
- Mapping: Oracle data types are mapped to Singer JSON types (e.g., Oracle timestamps to
date-timeformat). - Schema Generation: A
Singer Catalogis produced, defining key properties and replication methods.
Sources: src/flext_oracle_wms/README.md:37-43, tests/unit/oracle_wms_focused_discovery.py:34-75
Conclusion
The Interfaces and Protocols within flext-oracle-wms ensure that Oracle WMS Cloud integration is both robust and flexible. By utilizing a declarative API catalog, strict authentication protocols, and the Result pattern, the library provides a safe and scalable framework for enterprise data integration. These patterns facilitate seamless operation within the broader FLEXT ecosystem and support standardized data protocols like Singer.