How azure/azure-cosmosdb-java works
Project Type and Purpose
• This is an open-source Java SDK (v2.x) for the SQL API of Azure Cosmos DB. It provides:
• A high-level async API (AsyncDocumentClient) for Java applications
• Two transport implementations (“gateway” over HTTP/HTTPS, “direct” over TCP with Rntbd)
• Shared domain/model classes, tools (benchmark, examples, test-utils)
• Samples and performance utilities
High-Level Module Breakdown (from the file tree)
• Parent pom.xml
• commons
• Core domain classes (Document, Database, PartitionKey, etc.)
• sdk
• Public async client (AsyncDocumentClient) and client implementation
• gateway
• GatewayStoreModel, HTTP retry policies, session token management, query engine
• direct-impl
• RntbdTransportClient, transport channel pool, health checks, TCP protocol codec
• commons-test-utils
• Test helpers and validators for all modules
• examples
• Standalone sample apps demonstrating usage
• benchmark
• Performance benchmark harness (sync/async mixed workloads)
• faq, changelog, security, CI config
Core Architectural Components
A. Public API Layer
• AsyncDocumentClient.Builder → builds AsyncDocumentClient instance
• Exposes RxJava Observable<ResourceResponse<T>> operations
B. Shared Domain Model
• Classes in commons define resources, exceptions, policies, serializers
C. Transport Abstraction
• IStoreClient / TransportClient interfaces
• Gateway HTTP layer (gateway module)
• Direct TCP layer (direct-impl module with Rntbd protocol)
D. Underlying Service
• Azure Cosmos DB service (external)
• Optional Cosmos DB Emulator (local)
E. Support Tools
• Examples project (usage patterns)
• Benchmark project (performance testing)
• Test utilities (commons-test-utils)
Interactions and Data Flow
1. Client code calls AsyncDocumentClient.<operation>()
2. AsyncDocumentClient checks ConnectionPolicy (Direct vs. Gateway mode)
3. Depending on mode:
– Gateway mode → RxGatewayStoreModel → HTTP over HTTPS → Cosmos DB Gateway endpoint
– Direct mode → RntbdTransportClient → TCP connections → Cosmos DB replica nodes
4. Response flows back through TransportClient → Observable pipeline → user code
5. Session tokens, consistency policies and retry logic applied in gateway/direct layers
Detailed Elements
• API vs. Transport vs. External