Generated Code Runtime
Relevant source files
- cloudplatform/caching/pom.xml
- cloudplatform/cloudplatform-connectivity/pom.xml
- cloudplatform/connectivity-apache-httpclient4/pom.xml
- cloudplatform/connectivity-apache-httpclient5/pom.xml
- cloudplatform/connectivity-dwc/pom.xml
- cloudplatform/resilience4j/pom.xml
- datamodel/fluent-result/pom.xml
- datamodel/odata-v4/odata-v4-api-sample/pom.xml
- datamodel/odata-v4/odata-v4-core/pom.xml
- datamodel/odata-v4/pom.xml
- datamodel/odata/odata-api-sample/pom.xml
- datamodel/odata/odata-core/pom.xml
- datamodel/odata/pom.xml
- datamodel/openapi/openapi-api-sample/pom.xml
- datamodel/openapi/openapi-generator-maven-plugin/src/test/resources/DataModelGeneratorMojoUnitTest/testInvocationWithAllParameters/pom.xml
- datamodel/openapi/pom.xml
- datamodel/pom.xml
- latest.json
- testutil/pom.xml
Purpose and Scope
This document describes the structure of generated client code and the runtime infrastructure required for execution. It explains the anatomy of generated API service classes and model classes, their runtime dependencies (openapi-core, odata-core, odata-v4-core), and typical usage patterns for executing requests.
The generated code consists of two main artifact types:
- API Service Classes: Type-safe methods for invoking service operations
- Model Classes: POJOs representing data entities with fluent builders
For information about the code generation process itself, see page 4.1. For configuring generator plugins, see page 4.4.
Structure of Generated Code
Generated Artifacts Overview
The SDK generators produce two distinct categories of Java classes:
Sources: datamodel/odata/odata-api-sample/pom.xml139-150 datamodel/openapi/openapi-api-sample/pom.xml110-144
Package Structure
Generated code follows a consistent package structure:
com.sap.cloud.sdk.datamodel.{protocol}.{servicename}
├── api/ # API service classes
│ └── BusinessPartnerService.java
├── model/ # Model/entity classes
│ ├── BusinessPartner.java
│ ├── BusinessPartnerAddress.java
│ └── ...
└── selectable/ # Field selectors (OData only)
└── BusinessPartnerSelectable.java
For OpenAPI:
com.company.api/ # API package (configurable)
└── DefaultPetstoreApi.java
com.company.model/ # Model package (configurable)
├── Pet.java
├── Order.java
└── ...
Sources: datamodel/odata/odata-api-sample/pom.xml145 datamodel/openapi/openapi-api-sample/pom.xml112-113
Runtime Dependency Model
Generated client code delegates to progressively lower-level abstractions for protocol handling, HTTP communication, and platform integration.
Dependency Layers
| Layer | Modules | Purpose |
|---|---|---|
| Generated Client Layer | User's generated code | Type-safe API service classes and model classes |
| Protocol Core Layer | odata-core, odata-v4-core, openapi-core | Protocol-specific request builders and executors |
| Connectivity Layer | cloudplatform-connectivity, connectivity-apache-httpclient4/5 | HTTP communication and destination management |
| Platform Core Layer | cloudplatform-core, security, tenant, caching, resilience | Cross-cutting platform concerns |
Sources: datamodel/odata/odata-api-sample/pom.xml31-124 datamodel/odata-v4/odata-v4-api-sample/pom.xml31-103 datamodel/openapi/openapi-api-sample/pom.xml31-97
Generated API Service Classes
API service classes provide the entry point for invoking service operations. They contain methods that return request builder instances.
OData v2 API Service Structure
Generated OData v2 service classes contain methods for entity set operations:
Each method returns a fluent helper that extends base classes from odata-core:
FluentHelperReadfor queriesFluentHelperCreatefor creationFluentHelperUpdatefor updatesFluentHelperDeletefor deletionFluentHelperFunctionfor function imports
Sources: datamodel/odata/odata-api-sample/pom.xml139-150
OData v4 API Service Structure
OData v4 service classes follow similar patterns but use v4-specific fluent helpers from odata-v4-core that support:
- Lambda expressions in filters
- Navigation property expansion with nested queries
- Delta queries
- Bound actions and functions
Sources: datamodel/odata-v4/odata-v4-api-sample/pom.xml118-131
OpenAPI API Service Structure
OpenAPI-generated service classes contain methods directly corresponding to API operations:
OpenAPI methods return response objects directly rather than fluent helpers, though they delegate to request builders internally.
Sources: datamodel/openapi/openapi-api-sample/pom.xml104-145
Generated Model Classes
Model classes represent data entities with properties, accessors, and builder patterns.
OData Model Class Structure
OData-generated model classes extend VdmEntity<T> or VdmComplex from odata-core:
Key Properties:
@SerializedName: Maps Java properties to OData property names (Gson serialization)- Extends
VdmEntity<T>: Provides entity lifecycle methods (getKey, getType, etc.) - Navigation properties: Lazy-loaded via separate requests
Sources: datamodel/odata/odata-api-sample/pom.xml49-51
OpenAPI Model Class Structure
OpenAPI-generated models are plain POJOs with Jackson annotations:
Key Properties:
@JsonProperty: Maps Java properties to JSON field names (Jackson serialization)- Builder pattern: Fluent API for object construction
- Enum types: Generated for constrained string values
Sources: datamodel/openapi/openapi-api-sample/pom.xml51-53 datamodel/openapi/openapi-api-sample/pom.xml126-134
Required Runtime Dependencies
OData v2 Generated Code
OData v2 clients require odata-core as the primary dependency:
Transitive Dependencies Provided:
odata-client: Low-level OData protocol implementationfluent-result: Fluent API for handling result structurescloudplatform-connectivity: Destination and HTTP abstractionsconnectivity-apache-httpclient4: Apache HttpClient 4 integrationcloudplatform-core: ThreadContext and Try utilitiesgson: JSON serialization for OData
Sources: datamodel/odata/odata-api-sample/pom.xml32-77
OData v4 Generated Code
OData v4 clients require odata-v4-core:
The dependency structure mirrors OData v2 but uses v4-specific protocol implementations supporting OData 4.0 features.
Sources: datamodel/odata-v4/odata-v4-api-sample/pom.xml32-59
OpenAPI Generated Code
OpenAPI clients require openapi-core:
Transitive Dependencies Provided:
cloudplatform-connectivity: Destination and HTTP abstractionsspring-web: RestTemplate and HTTP utilitiesjackson-databind: JSON serialization for REST APIs
Sources: datamodel/openapi/openapi-api-sample/pom.xml32-61
Runtime Architecture: Class Dependencies
The following diagram maps generated code classes to their runtime dependencies, showing concrete class names from both generated code and SDK modules.
Diagram: Generated Code to Runtime Module Dependencies
Sources: datamodel/odata/odata-api-sample/pom.xml32-77 datamodel/odata-v4/odata-v4-api-sample/pom.xml32-59 datamodel/openapi/openapi-api-sample/pom.xml32-61
Core Runtime Classes by Protocol
OData v2 Runtime Classes
Generated OData v2 code extends base classes from odata-core module:
| Class | Package | Extended By | Purpose |
|---|---|---|---|
VdmEntity<T> | com.sap.cloud.sdk.datamodel.odata.helper | All entity classes (e.g., BusinessPartner) | Base for entity objects with key access, type information |
VdmComplex | com.sap.cloud.sdk.datamodel.odata.helper | Complex type classes (e.g., Address) | Base for complex types without keys |
FluentHelperRead<T> | com.sap.cloud.sdk.datamodel.odata.helper | Query fluent helpers | Provides select(), filter(), orderBy(), execute() |
FluentHelperCreate<T> | com.sap.cloud.sdk.datamodel.odata.helper | Create fluent helpers | Handles POST requests for entity creation |
FluentHelperUpdate<T> | com.sap.cloud.sdk.datamodel.odata.helper | Update fluent helpers | Handles PUT/PATCH for entity updates |
FluentHelperDelete | com.sap.cloud.sdk.datamodel.odata.helper | Delete fluent helpers | Handles DELETE requests |
FluentHelperFunction<T, R> | com.sap.cloud.sdk.datamodel.odata.helper | Function import helpers | Executes OData function imports |
ODataRequestExecutable | com.sap.cloud.sdk.datamodel.odata.helper | All fluent helpers | Defines execute(Destination) method |
Key Interfaces:
- All fluent helpers implement
ODataRequestExecutablewith these methods:execute(Destination): Executes request using destinationexecuteRequest(Destination): Returns raw HTTP responseexecuteRequest(HttpClient): Direct execution with HTTP client
Sources: datamodel/odata/odata-api-sample/pom.xml32-77
OData v4 Runtime Classes
OData v4 uses analogous classes in odata-v4-core with v4-specific features:
| Class | Package | Key Differences from v2 |
|---|---|---|
VdmEntity<T> | com.sap.cloud.sdk.datamodel.odatav4.core | Supports v4 navigation, actions, functions |
FluentHelperRead<T> | com.sap.cloud.sdk.datamodel.odatav4.core | Adds expand() with nested queries, search() |
FluentHelperAction<T> | com.sap.cloud.sdk.datamodel.odatav4.core | Bound/unbound actions (v4 feature) |
FluentHelperFunction<T> | com.sap.cloud.sdk.datamodel.odatav4.core | Composable functions |
Sources: datamodel/odata-v4/odata-v4-api-sample/pom.xml32-59
OpenAPI Runtime Classes
OpenAPI-generated code uses classes from openapi-core:
| Class | Package | Purpose |
|---|---|---|
OpenApiService | com.sap.cloud.sdk.datamodel.openapi.core | Base class for API service implementations |
OpenApiRequestBuilder | com.sap.cloud.sdk.datamodel.openapi.core | Fluent API for building REST requests |
OpenApiRequestException | com.sap.cloud.sdk.datamodel.openapi.core | Exception wrapper for failed requests |
Sources: datamodel/openapi/openapi-api-sample/pom.xml32-61
Integration with Connectivity Layer
Generated code does not perform HTTP operations directly. Instead, it delegates to the connectivity layer, which provides destination management, authentication, and HTTP client abstraction.
Destination-Based Execution
The standard execution pattern for generated clients:
The execute(Destination) method internally:
- Resolves the destination using
DestinationAccessor - Retrieves an
HttpClientusingHttpClientAccessor - Applies authentication headers via
DestinationHeaderProvider - Executes the HTTP request
- Parses the response into typed entities
HTTP Client Abstraction
Generated code uses HttpClient interface from cloudplatform-connectivity, which has two implementations:
HttpClient4Accessor: Uses Apache HttpClient 4.xHttpClient5Accessor: Uses Apache HttpClient 5.x
The connectivity layer automatically selects the appropriate implementation based on classpath availability, with HttpClient 5 preferred when both are present.
Sources: cloudplatform/connectivity-apache-httpclient4/pom.xml1-142 cloudplatform/connectivity-apache-httpclient5/pom.xml1-125
Typical Usage Patterns
OData v2 Query Execution
Standard pattern for executing OData v2 queries with generated code:
Behind the Scenes:
getAllBusinessPartner()instantiatesGetAllBusinessPartnerFluentHelper- Fluent methods build OData query URL and options
execute(destination)delegates toFluentHelperRead.execute()FluentHelperReadusesODataRequestExecutableinterface- Request execution resolves
Destination→HttpClient→ HTTP request
Sources: datamodel/odata/odata-api-sample/pom.xml32-77
OData v2 Entity Creation
Sources: datamodel/odata/odata-api-sample/pom.xml139-150
OData v4 with Navigation Expansion
OData v4 supports nested query options in expansions:
Sources: datamodel/odata-v4/odata-v4-api-sample/pom.xml32-59
OpenAPI REST Invocation
OpenAPI-generated APIs have direct method invocations:
Sources: datamodel/openapi/openapi-api-sample/pom.xml104-145
Destination Service Integration Sequence
When executing against BTP, generated clients automatically integrate with DestinationService:
Diagram: Request Execution Flow
Sources: datamodel/odata/odata-api-sample/pom.xml89-93
Integration with Cloud Platform Features
Generated code automatically benefits from cloud platform features through its use of the connectivity layer.
Multi-Tenancy Support
Generated clients are tenant-aware. When executing requests in a multi-tenant environment:
- The current tenant is retrieved from
TenantAccessor - Destination cache keys include the tenant ID
- Authentication tokens are tenant-scoped
- HTTP headers propagate tenant context
This happens transparently without application code changes.
Sources: cloudplatform/tenant/pom.xml31-60 cloudplatform/connectivity-destination-service/pom.xml63-64
Security Context Propagation
Generated clients propagate security context:
- User JWT tokens are extracted from
AuthTokenAccessor - Tokens are forwarded in Authorization headers or exchanged for technical tokens
- Principal information is available to destination retrieval logic
Sources: cloudplatform/security/pom.xml31-55 cloudplatform/connectivity-oauth/pom.xml54-83
Caching
The connectivity layer caches:
- Destination configurations (TTL configurable)
- OAuth2 access tokens (until expiry)
- HTTP connection pools
Generated code benefits from caching without explicit configuration. Caffeine provides the cache implementation.
Sources: cloudplatform/caching/pom.xml31-61 cloudplatform/connectivity-destination-service/pom.xml38-39
Resilience Patterns
Resilience patterns are applied at the connectivity layer:
| Pattern | Implementation | Default Behavior |
|---|---|---|
| Circuit Breaker | Resilience4j | Opens after 5 failures |
| Retry | Resilience4j | 3 attempts with exponential backoff |
| Timeout | Resilience4j | 10 seconds |
| Bulkhead | Resilience4j | 100 concurrent calls |
Generated code inherits these patterns when executing through destinations configured with resilience.
Sources: cloudplatform/resilience4j/pom.xml31-96 cloudplatform/connectivity-destination-service/pom.xml55-56
Runtime Execution Flow
Diagram: Complete Request Execution Pipeline
Key Class Names in Flow:
GetAllBusinessPartnerFluentHelper: Generated byodata-generatorFluentHelperRead: Fromodata-coremoduleODataRequestRead: Fromodata-clientmoduleDestinationAccessor: Fromcloudplatform-connectivityHttpClientAccessor: Fromconnectivity-apache-httpclient4DestinationHeaderProvider: Fromcloudplatform-connectivity
Sources: datamodel/odata/odata-api-sample/pom.xml32-77 datamodel/odata/odata-api-sample/pom.xml89-93
Shared Utility Dependencies
Generated code and runtime modules share common utility libraries:
| Library | Artifact ID | Usage |
|---|---|---|
| Vavr | vavr | Functional data structures (Try, Option, Either) |
| Guava | guava | Collections utilities |
| Gson | gson | JSON serialization (OData v2) |
| Jackson | jackson-databind | JSON serialization (OData v4, OpenAPI) |
| SLF4J | slf4j-api | Logging facade |
| Lombok | lombok | Code generation (provided scope) |
| Apache HttpClient | httpclient / httpclient5 | HTTP communication |
| Apache HttpCore | httpcore / httpcore5 | HTTP primitives |
Scope Note: Lombok is a provided-scope dependency used during code generation but not required at runtime. All generated getters, setters, builders, and constructors are already compiled into the generated classes.
Sources: datamodel/odata/odata-core/pom.xml56-108 datamodel/odata-v4/odata-v4-core/pom.xml56-108
Minimal Runtime Configuration
Required Dependencies
Generated code requires protocol-specific core modules and connectivity:
For OData v2:
For OData v4:
For OpenAPI:
Each core module transitively provides:
- HTTP connectivity (
cloudplatform-connectivity) - Apache HttpClient integration (
connectivity-apache-httpclient4orconnectivity-apache-httpclient5) - Platform core utilities (
cloudplatform-core) - JSON serialization (Gson for OData, Jackson for OpenAPI)
Sources: datamodel/odata/odata-api-sample/pom.xml32-77 datamodel/odata-v4/odata-v4-api-sample/pom.xml32-59 datamodel/openapi/openapi-api-sample/pom.xml32-61
Zero-Configuration Defaults
Generated clients work out-of-the-box with:
No code configuration required for standard SAP BTP deployments.
Sources: datamodel/odata/odata-api-sample/pom.xml31-124
Optional Runtime Enhancements
Deploy with Confidence (DWC) Integration
Add certificate-based authentication by including the DWC module:
With this dependency, generated clients automatically support:
- mTLS for service authentication
- DWC destination retrieval
- Certificate-based identity propagation
- Megaclite service binding resolution
No code changes required in generated clients.
Sources: datamodel/openapi/openapi-api-sample/pom.xml31-97
Apache HttpClient 5 Upgrade
Switch to Apache HttpClient 5 by adding:
HttpClient 5 provides improved connection pooling and HTTP/2 support. The SDK automatically detects and uses HttpClient 5 when both versions are on the classpath.
Sources: datamodel/odata/odata-api-sample/pom.xml31-124
Serialization and Deserialization
OData Serialization (Gson)
OData v2 and v4 use Gson for JSON serialization with field name mapping:
Key Points:
@SerializedName: Maps Java camelCase to OData PascalCase- Gson handles null values and optional fields
- Custom type adapters for dates (
LocalDateTime,ZonedDateTime)
Sources: datamodel/odata/odata-api-sample/pom.xml49-51
OpenAPI Serialization (Jackson)
OpenAPI uses Jackson with Spring Boot defaults:
Key Points:
@JsonProperty: Explicit JSON field names- Jackson modules for Java 8 time types (
jackson-datatype-jsr310) - Support for polymorphic types with
@JsonSubTypes
Sources: datamodel/openapi/openapi-api-sample/pom.xml51-53 datamodel/openapi/openapi-api-sample/pom.xml89-92
Testing Generated Code
Test Dependencies
Runtime modules include test utilities for integration testing:
Sources: datamodel/odata/odata-api-sample/pom.xml89-113 datamodel/openapi/openapi-api-sample/pom.xml63-77
WireMock for Mocking Services
Sample test pattern using WireMock to mock OData/REST endpoints:
Sources: datamodel/odata/odata-api-sample/pom.xml110-113 datamodel/odata-v4/odata-v4-api-sample/pom.xml94-97
Dependency Resolution Strategy
The SDK uses Maven's dependency management to ensure version consistency:
BOM Import
Applications should import the SDK BOM to manage all runtime versions:
This ensures all SDK modules and their transitive dependencies use compatible versions.
SDK Core Bundle
For convenience, applications can use the sdk-core bundle that aggregates essential connectivity modules:
This pulls in:
cloudplatform-corecloudplatform-connectivityconnectivity-destination-serviceconnectivity-oauthconnectivity-apache-httpclient5
Sources: cloudplatform/connectivity-destination-service/pom.xml1-10 latest.json1-3
Version Compatibility
Generated code is forward-compatible within major versions. Code generated with SDK 5.x can run with any 5.y runtime version where y >= x. This allows:
- Updating runtime dependencies without regenerating clients
- Using newer runtime features (caching improvements, new auth methods) with older generated code
- Gradual migration strategies
Breaking changes occur only at major version boundaries (e.g., 5.x to 6.x).
Sources: latest.json1-3
Refresh this wiki
On this page
- Generated Code Runtime
- Purpose and Scope
- Structure of Generated Code
- Generated Artifacts Overview
- Package Structure
- Runtime Dependency Model
- Dependency Layers
- Generated API Service Classes
- OData v2 API Service Structure
- OData v4 API Service Structure
- OpenAPI API Service Structure
- Generated Model Classes
- OData Model Class Structure
- OpenAPI Model Class Structure
- Required Runtime Dependencies
- OData v2 Generated Code
- OData v4 Generated Code
- OpenAPI Generated Code
- Runtime Architecture: Class Dependencies
- Core Runtime Classes by Protocol
- OData v2 Runtime Classes
- OData v4 Runtime Classes
- OpenAPI Runtime Classes
- Integration with Connectivity Layer
- Destination-Based Execution
- HTTP Client Abstraction
- Typical Usage Patterns
- OData v2 Query Execution
- OData v2 Entity Creation
- OData v4 with Navigation Expansion
- OpenAPI REST Invocation
- Destination Service Integration Sequence
- Integration with Cloud Platform Features
- Multi-Tenancy Support
- Security Context Propagation
- Caching
- Resilience Patterns
- Runtime Execution Flow
- Shared Utility Dependencies
- Minimal Runtime Configuration
- Required Dependencies
- Zero-Configuration Defaults
- Optional Runtime Enhancements
- Deploy with Confidence (DWC) Integration
- Apache HttpClient 5 Upgrade
- Serialization and Deserialization
- OData Serialization (Gson)
- OpenAPI Serialization (Jackson)
- Testing Generated Code
- Test Dependencies
- WireMock for Mocking Services
- Dependency Resolution Strategy
- BOM Import
- SDK Core Bundle
- Version Compatibility
