Overview

Relevant source files

• README.md
• archetypes/pom.xml
• cloudplatform/connectivity-ztis/pom.xml
• datamodel/openapi/openapi-core/pom.xml
• datamodel/openapi/openapi-generator/pom.xml
• datamodel/soap/pom.xml
• dependency-bundles/bom/pom.xml
• dependency-bundles/modules-bom/pom.xml
• pom.xml

Purpose and Scope

This document provides a comprehensive overview of the SAP Cloud SDK for Java, including its architecture, key subsystems, and developer interaction model. The SAP Cloud SDK for Java is a library that simplifies building cloud-native, multi-tenant SaaS applications on SAP Business Technology Platform (SAP BTP). It provides abstractions for connectivity, authentication, resilience, multi-tenancy, and code generation for OData and OpenAPI services.

This page covers the high-level architecture and design principles. For detailed information on specific subsystems:

• Maven setup and dependency management: see Maven Architecture
• Connectivity and destination management: see Cloud Platform Connectivity
• OData and OpenAPI code generation: see Data Model Generation
• Context propagation and cross-cutting concerns: see Thread Context and Cross-Cutting Concerns
• Build, quality gates, and CI/CD: see Build System and Quality Assurance and CI/CD Pipeline

What is the SAP Cloud SDK for Java

The SAP Cloud SDK for Java is an open-source library (Apache 2.0 license) published to Maven Central that enables developers to build extensions and integrations for SAP products running on SAP BTP. The SDK abstracts the complexity of cloud platform services (authentication, destinations, multi-tenancy) and provides type-safe client generation for OData and OpenAPI services.

Sources: README.md23-28 pom.xml8-10

Key Capabilities

The SDK provides four major capability areas:

Capability Area	Description	Key Modules
Connectivity	Abstractions for connecting to remote systems via HTTP, with built-in authentication, destination management, and OAuth2 flows	cloudplatform-connectivity, connectivity-destination-service, connectivity-oauth
Data Model Generation	Maven plugins that generate type-safe Java clients from OData metadata and OpenAPI specifications	odata-generator, odata-v4-generator, openapi-generator
Multi-Tenancy & Security	Thread-safe context management for tenant isolation, JWT authentication, and principal handling	cloudplatform-core, security, tenant
Resilience & Caching	Circuit breaker, retry, bulkhead, rate limiter, and time limiter patterns with tenant-aware caching	resilience, resilience4j, caching

Sources: README.md30-59 dependency-bundles/modules-bom/pom.xml49-217

Repository Structure

The repository follows a Maven multi-module structure with clear separation of concerns:

Maven Coordinates:

• Group ID: com.sap.cloud.sdk
• Root Artifact: sdk-parent
• Current Version: 5.26.0-SNAPSHOT

Sources: pom.xml1-38 dependency-bundles/bom/pom.xml1-10 dependency-bundles/modules-bom/pom.xml1-217

Maven Dependency Management Strategy

The SDK uses a three-tier Bill of Materials (BOM) approach to manage dependencies:

Key Characteristics:

• sdk-bom: Imports external dependency BOMs (XSUAA, Service Binding) and declares versions for third-party libraries (SLF4J 2.0.17, Resilience4j 2.3.0, Caffeine 3.2.3)
• sdk-modules-bom: Declares versions for all SDK modules using the unified sdk.version property
• sdk-core: Transitively includes connectivity, security, tenant, and resilience modules for simplified dependency management

Sources: dependency-bundles/bom/pom.xml85-290 dependency-bundles/modules-bom/pom.xml49-217 pom.xml136-145

Developer Interaction Model

Developers interact with the SDK through three distinct phases:

Phase 1: Project Setup

• Developers use the spring-boot3 archetype to generate a Spring Boot application scaffolded with SDK dependencies
• The generated pom.xml imports sdk-bom in dependencyManagement and declares specific module dependencies

Phase 2: Code Generation (Optional)

• For OData or OpenAPI consumption, developers configure Maven plugins in their pom.xml
• During mvn generate-sources, plugins read API specifications and generate type-safe client code
• Generated code is placed in target/generated-sources and automatically added to the build classpath

Phase 3: Runtime Development

• Applications use SDK APIs to retrieve destinations, manage authentication, and execute requests
• Generated clients (e.g., BusinessPartnerService) use SDK connectivity abstractions under the hood
• SDK handles SAP BTP service integration (Destination, XSUAA, IAS, Connectivity) transparently

Sources: README.md73-84 archetypes/pom.xml33-35

Core Abstraction Layers

The SDK is organized into abstraction layers that separate concerns and allow flexible implementations:

Abstraction Benefits:

• Static Accessors: Single entry points (DestinationAccessor, TenantAccessor) hide implementation complexity
• Interface Contracts: DestinationLoader, DestinationRetrieval allow custom implementations
• Platform Agnostic: Core interfaces don't depend on SAP BTP-specific implementations
• SPI Pattern: Service Provider Interface allows extensions without modifying core code
• Thread Context: Uniform propagation of security, tenant, and custom properties across async boundaries

Sources: pom.xml29-38 Module structure inferred from dependency-bundles/modules-bom/pom.xml

Integration with SAP Business Technology Platform

The SDK provides native integration with SAP BTP services through service binding discovery and OAuth2 flows:

Service Binding Discovery Flow:

1. SDK code calls ServiceBindingAccessor.getServiceBindings()
2. DefaultServiceBindingAccessor reads from environment sources (VCAP_SERVICES, K8s secrets)
3. Service-specific property suppliers (DestinationServicePropertySupplier, XsuaaServicePropertySupplier) parse bindings
4. SDK components use parsed credentials to authenticate to BTP services

Supported BTP Services:

• Destination Service (label: "destination"): Stores destination configurations
• XSUAA (label: "xsuaa"): OAuth2 token service for user and technical authentication
• Identity Authentication (label: "identity"): IAS-based authentication
• Connectivity Service (label: "connectivity"): On-premise connectivity proxy
• Zero Trust Identity Service (label: "ztis"): Certificate-based mutual TLS

Sources: dependency-bundles/bom/pom.xml102-109 cloudplatform/connectivity-ztis/pom.xml49-59

Quality and Build Standards

The SDK enforces strict quality gates through Maven enforcer rules and static analysis:

Enforcer Rules (Validated on Every Build):

• Maven version ≥ 3.5, Java version = 17
• No duplicate dependency versions in POM hierarchy
• Dependency convergence (all transitive versions must align)
• Banned dependencies: JUnit 4, logging frameworks (except SLF4J), deprecated libraries
• Scope enforcement: Java EE APIs must be provided, logger bridges must be runtime

Static Analysis Tools:

• Checkstyle: Code style enforcement using custom rules at codestyle/checkstyle.xml
• PMD: Code quality checks using codestyle/pmd.xml and codestyle/sdk_specific_pmd_rules.xml
• SpotBugs: Bug pattern detection with custom exclusions at codestyle/spotbugs-exclusions.xml
• JaCoCo: Code coverage measurement with reports generated per module

Build Lifecycle:

1. validate: Enforcer plugin validates dependencies and versions
2. process-sources: formatter-maven-plugin and impsort-maven-plugin auto-format code
3. compile: Java 17 compilation with -Xlint:all warnings
4. process-test-classes: Dependency analysis checks for unused/undeclared dependencies
5. test: Surefire executes tests with 4-way forking and JaCoCo instrumentation
6. verify: Checkstyle, PMD, and SpotBugs reports generated

Sources: pom.xml532-932 pom.xml54-77

Release and Artifact Publishing

The SDK publishes artifacts to Maven Central using a two-phase semi-automated release process:

Phase 1: Release Preparation (prepare-release workflow)

• Version calculation script determines next semantic version
• POM versions updated across all modules using set-release-versions.py
• Full CI build triggered with artifact generation (build-release-artifacts=true)
• JavaDoc aggregated across all modules
• Release notes generated from Git history
• Draft GitHub release created with artifacts
• Pull requests created for version updates

Phase 2: Release Execution (perform-release workflow)

• Manual validation: CI must pass, PRs must be mergeable
• Artifacts deployed to Maven Central via central-publishing-maven-plugin
• Artifacts signed with GPG during deployment
• Release PRs merged to main branch
• GitHub release published

Artifact Types:

• JAR: Primary artifact containing compiled classes
• Sources JAR: Generated by maven-source-plugin with -sources classifier
• JavaDoc JAR: Generated by maven-javadoc-plugin with -javadoc classifier (delomboked sources)
• POM: Maven project descriptor with dependencies and metadata

Distribution:

• Releases: Maven Central (https://central.sonatype.com)
• Snapshots: SAP Artifactory (https://common.repositories.cloud.sap/artifactory/build-snapshots-cloudsdk)

Sources: dependency-bundles/bom/pom.xml29-38 dependency-bundles/bom/pom.xml292-487

Version Compatibility and Maturity Levels

The SDK follows semantic versioning (MAJOR.MINOR.PATCH) with maturity indicators:

Maturity Levels:

• Generally Available (GA): Production-ready, backward-compatible within MAJOR version
• Beta: Feature-complete but subject to breaking changes, marked with @Beta annotation
• Deprecated: Scheduled for removal, marked with @Deprecated annotation

Current Version Structure:

• Major Version: 5 (current)
• Minor Version: 26 (incremented for new features)
• Patch Version: 0
• Snapshot: -SNAPSHOT suffix for development versions

Dependency Version Management:

• External dependencies declared in sdk-bom (e.g., SLF4J 2.0.17, Resilience4j 2.3.0)
• SDK module versions unified via sdk.version property
• Spring Framework versions aligned with SAP Java Buildpack (Spring 6.2.15, Spring Security 6.1.5)

Compatibility Policy:

• Patch versions: Bug fixes only, fully backward compatible
• Minor versions: New features, backward compatible
• Major versions: Breaking changes allowed, migration guide provided

Sources: pom.xml6 pom.xml50-52 dependency-bundles/bom/pom.xml44-83

Module Interdependencies

Key dependency relationships between SDK modules:

Module	Depends On	Purpose
sdk-core	cloudplatform-connectivity, security, tenant, resilience4j	Convenience bundle for common dependencies
odata-core	odata-client, cloudplatform-connectivity	OData v2 client runtime depends on connectivity layer
odata-v4-core	odata-client, cloudplatform-connectivity	OData v4 client runtime depends on connectivity layer
openapi-core	cloudplatform-connectivity, connectivity-apache-httpclient5	OpenAPI client runtime uses HttpClient5 transport
connectivity-destination-service	cloudplatform-connectivity, connectivity-oauth	Destination service depends on OAuth2 for token flows
connectivity-apache-httpclient4	cloudplatform-connectivity	HttpClient4 transport implements connectivity abstractions
connectivity-apache-httpclient5	cloudplatform-connectivity	HttpClient5 transport implements connectivity abstractions
resilience4j	resilience-api, cloudplatform-core	Resilience4j implementation depends on API abstractions
security	cloudplatform-core	Security components use ThreadContext from core
tenant	cloudplatform-core	Tenant components use ThreadContext from core

Core Dependencies (Required by Most Modules):

• slf4j-api (2.0.17): Logging facade
• vavr (0.11.0): Functional data structures (Try, Either, Option)
• jsr305 (3.0.2): Nullability annotations (@Nonnull, @Nullable)

Sources: dependency-bundles/modules-bom/pom.xml49-217 datamodel/openapi/openapi-core/pom.xml34-108

Code Generation Workflow

The SDK provides Maven plugins that generate type-safe clients during the build:

Generation Process:

1. Specification Parsing: Plugins read metadata (EDMX, OpenAPI) and build internal model
2. Name Resolution: NamingContext converts API names to valid Java identifiers
3. Code Generation: PojoCodeGenerator generates POJOs, ServiceClassGenerator generates service APIs
4. Metadata Generation: MetadataGenerator creates VDM metadata for runtime introspection
5. Source Output: Generated code written to target/generated-sources/java

Generated Code Characteristics:

• Type Safety: All API operations and parameters are strongly typed
• Fluent API: Chainable method calls for query construction (.select(), .filter(), .top())
• Lombok Integration: Generated classes use Lombok annotations for builders and accessors
• Jackson Integration: JSON serialization/deserialization annotations included
• Javadoc: API documentation generated from service metadata

Sources: datamodel/openapi/openapi-generator/pom.xml1-194 pom.xml520-528

Summary

The SAP Cloud SDK for Java provides a comprehensive framework for building cloud-native applications on SAP BTP. Its architecture separates concerns into layers (connectivity, data models, cross-cutting concerns), uses interface-based abstractions to allow customization, and provides code generation to eliminate boilerplate. The SDK's Maven-based structure, strict quality gates, and integration with BTP services make it suitable for enterprise-grade development.

For detailed information on specific subsystems, refer to the linked wiki pages at the beginning of this document.