Overview
Relevant source files
This document provides an introduction to the SAP Cloud SDK for Java repository, its architecture, module organization, and key concepts. It explains what the SDK is, how it is structured as a Maven multi-module project, and how developers consume and extend it.
For detailed information about specific subsystems, see:
- Maven build structure and dependency management: Maven Architecture
- Cloud connectivity and destination management: Cloud Platform Connectivity
- OData and OpenAPI code generation: Data Model Generation
- Build system configuration: Build System and Quality Assurance
- CI/CD pipeline details: CI/CD Pipeline
What is the SAP Cloud SDK for Java
The SAP Cloud SDK for Java is a toolkit for building cloud-native applications on SAP Business Technology Platform (SAP BTP). It provides infrastructure for connectivity, authentication, multi-tenancy, resilience, and protocol-specific client generation. The SDK enables developers to focus on business logic while the framework handles cross-cutting concerns.
The SDK is distributed as a collection of Maven modules published to Maven Central under the group ID com.sap.cloud.sdk. The current development version is 5.27.0-SNAPSHOT as defined in pom.xml6
Key capabilities:
- Connectivity: Destination service integration, OAuth2 authentication, HTTP client adapters
- Code Generation: Type-safe Java clients from OData v2/v4 and OpenAPI specifications
- Multi-Tenancy: Tenant isolation, principal propagation, subscriber-aware caching
- Resilience: Circuit breakers, retries, timeouts, bulkheads via Resilience4j
- BTP Integration: Service binding discovery, XSUAA authentication, IAS support
Sources: README.md23-28 pom.xml1-10
Repository Structure
The repository is organized as a Maven multi-module project with a hierarchical parent POM structure. The root aggregator POM at pom.xml1-1367 coordinates seven top-level modules:
Module Overview
Sources: pom.xml29-38 README.md1-91
Core Module Groups
The SDK's functionality is distributed across specialized module groups. Each group addresses a specific concern and contains multiple sub-modules.
Cloud Platform Modules
The cloudplatform directory contains modules for connectivity and platform integration under the group ID com.sap.cloud.sdk.cloudplatform:
Key Classes and Responsibilities:
cloudplatform-core: Foundation module providingThreadContext,ScpCfCloudPlatform, andRequestHeaderAccessorfor managing execution contextcloudplatform-connectivity: Central connectivity abstractions includingDestination,DestinationService, andHttpClientAccessorconnectivity-destination-service: BTP Destination Service client withDestinationServiceAdapterand cachingconnectivity-oauth: OAuth2 token management viaOAuth2Serviceand service-specific property suppliersconnectivity-apache-httpclient4/5: HTTP client implementations wrapping Apache HttpClient 4.x and 5.xsecurity: JWT parsing,AuthToken,AuthTokenAccessor, andSecurityContextmanagementtenant: Multi-tenant isolation throughTenantAccessorandTenantabstractionsresilience:ResilienceConfigurationand decorators for circuit breakers, retries, timeoutscaching:CacheManagerfor request-scoped and tenant-aware caching
Sources: pom.xml32 dependency-bundles/modules-bom/pom.xml57-145
Data Model Modules
The datamodel directory contains protocol-specific client libraries and generators under the group ID com.sap.cloud.sdk.datamodel:
Key Artifacts:
odata-client: Low-level OData protocol handling, request buildersodata-core: OData v2 Virtual Data Model (VDM) runtime base classesodata-v4-core: OData v4 VDM runtime base classesodata-generator: Maven plugin and logic for generating OData v2 type-safe clientsodata-v4-generator: Maven plugin and logic for generating OData v4 type-safe clientsopenapi-core: Generic OpenAPI client runtime withOpenApiRequestBuilderopenapi-generator: Maven plugin for generating OpenAPI type-safe clientsfluent-result:Result<T>monad for functional error handlingdatamodel-metadata-generator: Metadata extraction for generated code documentation
Sources: dependency-bundles/modules-bom/pom.xml162-222
Dependency Management Strategy
The SDK uses a two-tier Bill of Materials (BOM) strategy to separate concerns between external third-party dependencies and internal SDK modules.
Versioning Details:
- Single Version Property: All internal modules share the version
${sdk.version}defined in pom.xml52 and dependency-bundles/bom/pom.xml47 - Version Synchronization: The property is updated by automation scripts during releases (see Version Management Automation)
- Consumer Simplicity: Applications import only
sdk-bomin theirdependencyManagementsection, then declare SDK modules without version numbers
Key External Dependencies:
| Dependency | Version | Purpose |
|---|---|---|
| Apache HttpClient 5 | 5.6 | Primary HTTP client implementation |
| Apache HttpClient 4 | 4.5.14 | Legacy HTTP client support |
| XSUAA Client | 3.6.6 | SAP BTP authentication integration |
| Service Binding API | 0.21.0 | Service discovery and configuration |
| Resilience4j | 2.3.0 | Circuit breakers and resilience patterns |
| Jackson | 2.21.1 | JSON/XML serialization |
| Caffeine | 3.2.3 | High-performance caching |
| Vavr | 1.0.0 | Functional programming utilities |
Sources: dependency-bundles/bom/pom.xml44-84 dependency-bundles/modules-bom/pom.xml44-48
Key Entry Points for Consumers
SDK BOM Consumption
Consumer applications should import sdk-bom in their dependency management section and then declare SDK modules without explicit versions:
Typical Consumer POM Structure:
SDK Core Convenience Bundle
For applications that need the most common SDK functionality, the sdk-core dependency bundle aggregates essential modules:
SDK Core Contents:
cloudplatform-core: Foundation and context managementcloudplatform-connectivity: Destination and HTTP client APIsconnectivity-apache-httpclient5: Default HTTP client implementationconnectivity-destination-service: BTP Destination Service integrationconnectivity-oauth: OAuth2 authentication flowssecurity: JWT and authentication token handlingtenant: Multi-tenancy supportresilience4j: Resilience patterns implementationcaching: Caching infrastructure
A single dependency on sdk-core transitively includes all these modules.
Sources: dependency-bundles/modules-bom/pom.xml51-55 dependency-bundles/bom/pom.xml1-9
Module Organization in Maven
The parent POM hierarchy follows this structure:
Parent POM Responsibilities:
-
sdk-parent(pom.xml1-1367):- Defines
${sdk.version}property at pom.xml52 - Imports
sdk-bomfor dependency versions at pom.xml139-145 - Configures build plugins: compiler, enforcer, formatter, checkstyle, PMD, SpotBugs, JaCoCo
- Sets Java version to 17 at pom.xml54
- Defines quality gates and code analysis thresholds
- Defines
-
Category Parents (
cloudplatform-parent,datamodel-parent, etc.):- Inherit from
sdk-parent - May override specific plugin configurations
- Aggregate sub-modules within their category
- Inherit from
Sources: pom.xml1-1367 pom.xml29-38
Build and Quality Assurance
The project enforces strict quality standards through automated checks:
Quality Gates
| Check | Tool | Threshold | Configuration |
|---|---|---|---|
| Code Coverage | JaCoCo | 75% instruction coverage | pom.xml896-919 |
| Static Analysis | Checkstyle | Max 14 high-priority issues | pom.xml839-855 |
| Bug Detection | SpotBugs | 0 violations | pom.xml920-931 |
| Code Quality | PMD | 0 violations | pom.xml856-875 |
| Code Formatting | formatter-maven-plugin | Enforced | pom.xml715-735 |
| Dependency Analysis | maven-dependency-plugin | Unused/convergence checks | pom.xml766-813 |
Maven Enforcer Rules
The build enforces several dependency rules via the Maven Enforcer Plugin:
- Banned Dependencies: Deprecated libraries like JUnit 4, old servlet APIs, commons-httpclient
- Scope Requirements: Logger bridges must use
runtimeortestscope - Dependency Convergence: All transitive dependencies must converge to a single version
- Version Requirements: Maven ≥3.5, Java 17
Sources: pom.xml533-713
Artifact Publishing
Releases are published to Maven Central via the Sonatype Central Publishing Maven Plugin. The release profile activates additional plugins for:
- Source JAR Generation:
maven-source-pluginat dependency-bundles/bom/pom.xml305-316 - Javadoc Generation:
maven-javadoc-pluginwith delombok support at dependency-bundles/bom/pom.xml345-363 - GPG Signing:
maven-gpg-pluginfor artifact signatures at dependency-bundles/bom/pom.xml366-377 - Central Publishing:
central-publishing-maven-pluginfor Maven Central deployment at dependency-bundles/bom/pom.xml411-420
The distribution management configuration points to:
- Releases:
https://central.sonatype.com/api/v1/publisher/upload - Snapshots:
https://common.repositories.cloud.sap/artifactory/build-snapshots-cloudsdk
Sources: dependency-bundles/bom/pom.xml292-487 pom.xml942-1107
Project Metadata
Sources: pom.xml1-43 README.md1-7
Getting Started
To build the project locally:
For new applications, use the Spring Boot 3 archetype:
Sources: README.md73-90 archetypes/pom.xml33-35
Summary
The SAP Cloud SDK for Java is a comprehensive toolkit organized as a Maven multi-module project. It provides:
- Modular Architecture: Specialized modules for connectivity, code generation, and SAP BTP integration
- Simplified Dependency Management: Two-tier BOM strategy with unified versioning
- Quality Assurance: Automated checks for code coverage, static analysis, and dependency hygiene
- Developer Productivity: Maven archetypes and convenience bundles for quick project setup
- Enterprise-Ready: Multi-tenancy, resilience patterns, and OAuth2 authentication built-in
For detailed exploration of specific subsystems, continue to the child pages in this documentation.
Refresh this wiki
On this page
- Overview
- What is the SAP Cloud SDK for Java
- Repository Structure
- Core Module Groups
- Cloud Platform Modules
- Data Model Modules
- Dependency Management Strategy
- Key Entry Points for Consumers
- SDK BOM Consumption
- SDK Core Convenience Bundle
- Module Organization in Maven
- Build and Quality Assurance
- Quality Gates
- Maven Enforcer Rules
- Artifact Publishing
- Project Metadata
- Getting Started
- Summary