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:

Artifact Type	Description	Examples
API Service Classes	Entry points containing methods for service operations	BusinessPartnerService, DefaultPetstoreApi
Model Classes	Data objects with properties, getters, setters, and builders	BusinessPartner, Pet, Order
Query/Request Builders	Fluent APIs returned by service methods	GetAllBusinessPartnerFluentHelper
Complex Types	Nested data structures	BusinessPartnerAddress

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:

• FluentHelperRead for queries
• FluentHelperCreate for creation
• FluentHelperUpdate for updates
• FluentHelperDelete for deletion
• FluentHelperFunction for 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 implementation
• fluent-result: Fluent API for handling result structures
• cloudplatform-connectivity: Destination and HTTP abstractions
• connectivity-apache-httpclient4: Apache HttpClient 4 integration
• cloudplatform-core: ThreadContext and Try utilities
• gson: 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 abstractions
• spring-web: RestTemplate and HTTP utilities
• jackson-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 ODataRequestExecutable with these methods:
  • execute(Destination): Executes request using destination
  • executeRequest(Destination): Returns raw HTTP response
  • executeRequest(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:

1. Resolves the destination using DestinationAccessor
2. Retrieves an HttpClient using HttpClientAccessor
3. Applies authentication headers via DestinationHeaderProvider
4. Executes the HTTP request
5. 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.x
• HttpClient5Accessor: 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:

1. getAllBusinessPartner() instantiates GetAllBusinessPartnerFluentHelper
2. Fluent methods build OData query URL and options
3. execute(destination) delegates to FluentHelperRead.execute()
4. FluentHelperRead uses ODataRequestExecutable interface
5. 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:

1. The current tenant is retrieved from TenantAccessor
2. Destination cache keys include the tenant ID
3. Authentication tokens are tenant-scoped
4. 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:

1. GetAllBusinessPartnerFluentHelper: Generated by odata-generator
2. FluentHelperRead: From odata-core module
3. ODataRequestRead: From odata-client module
4. DestinationAccessor: From cloudplatform-connectivity
5. HttpClientAccessor: From connectivity-apache-httpclient4
6. DestinationHeaderProvider: From cloudplatform-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-httpclient4 or connectivity-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:

Concern	Default Implementation	Customization Point
HTTP Client	Apache HttpClient 4 or 5 (classpath-based)	HttpClientAccessor.setHttpClientFactory()
Destination	BTP Destination Service	DestinationAccessor.setLoader()
Authentication	OAuth2 with XSUAA	Destination configuration
Caching	Caffeine with 5-minute TTL	CacheManager.getInstance()
Resilience	Resilience4j defaults	Destination properties
Tenant Context	Thread-local storage	ThreadContextAccessor

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-core
• cloudplatform-connectivity
• connectivity-destination-service
• connectivity-oauth
• connectivity-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