Search

    Development

    Find here information on how to configure applications, different supported databases, spring boot integration, and the CDS Maven Plugin.

    Content

    Application Configuration

    This section describes how to configure applications. CAP Java applications can fully leverage Spring Boot’s capabilities for Externalized Configuration. This enables you to define multiple configuration profiles for different scenarios, like local development and cloud deployment.

    For a first introduction, have a look at our sample application and the configuration profiles we added there.

    Now, that you’re familiar with how to configure your application, start to create your own application configuration. See the full list of CDS properties as a reference.

    SAP HANA

    SAP HANA can be configured when running locally as well as when running productively in the cloud. The datasource is auto-configured based on available service bindings in the VCAP_SERVICES environment variable or locally the default-env.json. This only works if an application profile is used, that doesn’t explicitly configure a datasource using spring.datasource.url. Such an explicit configuration always takes precedence over service bindings from the environment.

    Service bindings of type instance-manager (deprecated), service-manager and, in a Spring-based application, hana are used to auto-configure datasources. If multiple datasources are used by the application, you can select one auto-configured datasource to be used by the Persistence Service through the property cds.dataSource.serviceName.

    Datasource Configuration

    Datasources created from a service binding can be configured through the properties cds.dataSource.<service-instance>.<pool-type>.*. An example configuration could look like this:

    cds:
  dataSource:
    my-service-instance:
      hikari:
        maximum-pool-size: 20

    Supported pool types for single tenant scenarios are hikari, tomcat, and dbcp2. For a multitenant scenario hikari, tomcat, and atomikos are supported. The corresponding pool dependencies need to be available on the classpath.

    Datasources in Spring

    By default no datasource is marked as the primary datasource bean. If the property cds.dataSource.serviceName is set, the datasource bean created from this service-instance is marked as primary. In case, there are multiple datasources registered it’s required to define one datasource as primary. The primary datasource bean is the one that is used by the default Persistence Service.

    SQLite

    For local development, SQLite can be configured to run in-memory or in the file-based mode.

    File-Based Storage

    The database content is stored in a file, sqlite.db as in the following example. Since the schema is initialized using cds deploy command, the initialization mode is set to never:

    ---
spring:
  profiles: sqlite
  datasource:
    url: "jdbc:sqlite:sqlite.db"
    driver-class-name: org.sqlite.JDBC
    initialization-mode: never
    hikari:
      maximum-pool-size: 1

    In-Memory Storage

    The database content is stored in-memory only. The schema initialization done by Spring, executes the schema.sql script. Hence, the initialization mode is set to always. If Hikari closes the last connection from the pool, the in-memory database is automatically deleted. To prevent this situation, set max-lifetime to 0:

    ---
spring:
  profiles: default
  datasource:
    url: "jdbc:sqlite:file::memory:?cache=shared"
    driver-class-name: org.sqlite.JDBC
    initialization-mode: always
    hikari:
      maximum-pool-size: 1
      max-lifetime: 0

    H2

    H2 can be used as an alternative to SQLite for local development. In Spring, H2 is automatically initialized in-memory when present on the classpath. Refer to official H2 documentation for file-based database configuration.

    Database Support in Java

    This section describes the different databases, which are supported by CAP Java SDK and any differences between them with respect to CAP features. There’s out of the box support for SAP HANA with CAP currently as well as SQLite. However, it’s important to note that SQLite isn’t an enterprise grade database and is recommended for nonproductive use like local development or CI tests only.

    SAP HANA

    SAP HANA is supported as the CAP standard database and recommended for productive use with needs for schema evolution and multitenancy. Some salient points to note with SAP HANA are:

    • Views are supported as described in Updatable Views, else any operation on views are defaulted to SAP HANA, which has limitations as described in the documentation.

    PostgreSQL

    CAP doesn’t support PostgreSQL out of the box. However, CAP Java SDK is tested on PostgreSQL 12 and supports in general most of the features of CAP. Nevertheless, find here a list of unsupported features/differences:

    1. CAP doesn’t support PostgreSQL specific schema generation.
    2. There’s no support for Schema Evolution for PostgreSQL.
    3. Localization is supported just as in SQLite:
      • PostgreSQL doesn’t support the SESSION_CONTEXT method to dynamically determine the locale from a connection.
      • Instead, cds creates two SQL views for the languages German and French by default, to be able to determine the locale at runtime.
      • This limitation can be overcome by preserving the association localized in view definitions. Then the CDS runtime can take over and modify a query to be fully localization aware.
      • Learn more about resolution of localized data at runtime and via views.
    4. The sort order of queries behaves as configured on the database. Locale specific sorting isn’t supported.
    5. Currently, PostgreSQL only supports As-of-now queries with temporal data.
    6. Views are updatable as long as they’re supported by the CAP Java SDK, else they default to PostgreSQL, where updatable views have limitations.

    SQLite

    CAP supports SQLite out of the box. When working with Java, it’s recommended to use SQLite only for development and testing purposes. There’s no production support for SQLite from CAP.

    CAP does support most of the major features on SQLite, although there are a few shortcomings that are listed here:

    1. Localization is supported for all locales. However, a system property supported_locales needs to be set with a comma-delimited string literal containing all language codes defined for the data model. 
       System.setProperty("supported_locales","en,fr,es,it");

      • This limitation can be avoided by avoiding views that have a closed/fixed select list. Once a given CQL query uses * and excluding like this SELECT from Foo {*} excluding {bar} the CDS runtime can take over and modify a query to be fully localization aware.

      • Learn more about resolution of localized data at runtime and via views.

    2. Any views generated for SQLite are read-only by default, inserting records can only happen with a one to one projection.
    3. RIGHT and FULL OUTER JOIN isn’t supported.
    4. There are some known issues with parentheses in UNION operator. The following statement is erroneous: SELECT * FROM A UNION ( SELECT * FROM B ). Instead, use: SELECT * FROM A UNION SELECT * FROM B without parentheses. This can be achieved by removing the parentheses in your CDS Model.
    5. SQLite has only limited support for concurrent database access. You’re advised to limit the connection pool to 1 as shown above (parameter maximum-pool-size: 1), which effectively serializes all database transactions.
    6. The predicate function contains is supported. However, the search for characters in the word or phrase is case-insensitive in SQLite. In the future, we might provide an option to make the case-sensitivity locale dependent.
    7. SQLite doesn’t support pessimistic locking (SELECT FOR UPDATE) on the query level. Thus, to avoid SQLException at runtime, the generated SQL statements, passed to a database, don’t contain FOR UPDATE clause. Nevertheless, the data consistency can be guaranteed by the fact, that only one process can be making changes to the database at any moment in time.
    8. Streaming of large object data isn’t supported by SQLite. Hence, when reading or writing data of type cds.LargeString and cds.LargeBinary as a stream the framework temporarily materializes the content. Thus, storing large objects on SQLite can impact the performance.
    9. Sorting of character-based columns isn’t lexicographical but if any locale is specified in the context of a query then case insensitive sorting is performed.
    10. Currently, SQLite only supports as-of-now queries with temporal data.
    11. Views in SQLite are read-only. However, the CAP Java SDK supports some views to be updatable as described here.

    H2 Database

    H2 is one of the recommended in-memory databases for local development. There’s no production support for H2 from CAP and there are the following support limitations:

    1. Localization is supported for all locales. Unlike SAP HANA, H2 doesn’t support to set the locale for a connection.
      • As in SQLite, a system property supported_locales needs to be set with a comma-separated string literal containing all language codes defined for the data model.
      • This limitation can be avoided by avoiding views that have a closed /fixed select list. Once a given CQL query uses * and excluding like this SELECT from Foo {*} excluding {bar} the CDS runtime can take over and modify a query to be fully localization aware.
      • Learn more about resolution of localized data at runtime and via views.
    2. H2 only supports database level collation. Lexicographical sorting on character-based columns isn’t supported.
    3. Views in H2 aren’t updatable but a work-around can be employed manually as described in the official documentation.
    4. Case-insensitive comparison isn’t yet supported.
    5. Currently, only as-of-now queries with temporal data are supported.
    6. By default, views aren’t updatable on H2. However, the CAP Java SDK supports some views to be updatable as described here.
    7. For correct order of views in the generated schema.sql file CDS Compiler v2 must be used.

    Spring Boot Integration

    This section describes the Spring Boot integration of the CAP Java SDK. Classic Spring isn’t supported. Running your application with Spring Boot framework offers a number of helpful benefits that simplify the development and maintenance of the application to a high extend. Spring not only provides a rich set of libraries and tools for most common challenges in development, you also profit from a huge community, which constantly contributes optimizations, bug fixes and new features.

    As Spring Boot not only is widely accepted but also most popular application framework, CAP Java SDK comes with a seamless integration of Spring Boot as described in the following sections.

    Spring Dependencies

    To make your web application ready for Spring Boot, you need to make sure that the following Spring dependencies are referenced in your pom.xml (group ID org.springframework.boot):

    • spring-boot-starter-web
    • spring-boot-starter-jdbc
    • spring-boot-starter-security (optional)

    In addition, for activating the Spring integration of CAP Java SDK, the following runtime dependency is required:

    <dependency>
	<groupId>com.sap.cds</groupId>
	<artifactId>cds-framework-spring-boot</artifactId>
	<version>${revision}</version>
	<scope>runtime</scope>
/dependency>

    It might be more convenient to make use of CDS starter bundle cds-starter-spring-boot-odata, which not only comprises the necessary Spring dependencies, but also configures the OData V4 protocol adapter:

    <dependency>
	<groupId>com.sap.cds</groupId>
	<artifactId>cds-starter-spring-boot-odata</artifactId>
	<version>${revision}</version>
</dependency>

    Beside the common Spring features such as dependency injection and a sophisticated test framework, the following features are available in Spring CAP applications in addition:

    • A various number of CAP Java SDK interfaces are exposed as Spring beans and are available in Spring application context such as model and technical services, the CdsModel or the UserInfo in current request scope.
    • CDS event handler methods within custom Spring beans are automatically registered at startup.
    • Full integration into Spring transaction management (@Transactional is supported).
    • Automatic configuration of XSUAA and Mock user authentication by means of Spring security configuration.
    • Integration of cds-property section into Spring properties. See section Externalized Configuration in the Spring Boot documentation for more details.
    • Integration of cds actuator exposing monitoring information about CDS runtime and security.
    • Integration of DB health check indicator, which also applies to tenant-aware DB connections.

    None of the listed features will be available out of the box in case you choose to pack and deploy your web application as plain Java Servlet in a war file.

    Building CAP Java Applications

    This section describes various options to create a CAP Java project from scratch, to build your application with Maven, and to modify an existing project with the CDS Maven plugin.

    The Maven Archetype

    Use the following command line to create a project from scratch with the CDS Maven archetype:

    mvn archetype:generate -DarchetypeArtifactId=cds-services-archetype -DarchetypeGroupId=com.sap.cds -DarchetypeVersion=RELEASE

    mvn archetype:generate -DarchetypeArtifactId=cds-services-archetype -DarchetypeGroupId=com.sap.cds -DarchetypeVersion=RELEASE

    mvn archetype:generate `-DarchetypeArtifactId=cds-services-archetype `-DarchetypeGroupId=com.sap.cds `-DarchetypeVersion=RELEASE

    It supports the following command line options:

    Option Description
    -DincludeModel=true Adds a minimalistic sample CDS model to the project
    -DincludeIntegrationTest=true Adds an integration test module to the project
    -DodataVersion=[v2|v4] Specify which protocol adapter is activated by default

    Maven Build Options

    You can build and run your application by means of the following Maven command:

    mvn spring-boot:run

    The following sections describe additional options you can apply during the build.

    Using a Global cds-dk

    By default, the build is configured to download a Node.js runtime and the cds-dk tools and install them locally within the project. This step makes the build self-contained, but the build also takes more time. You can omit these steps and speed up the Maven build, using the Maven profile cdsdk-global.

    Prerequisites:

    • cds-dk is globally installed.
    • Node.js installation is available in current PATH environment.

    If these prerequisites are met, you can use the profile cdsdk-global by executing:

    mvn spring-boot:run -P cdsdk-global

    Refreshing the Local cds-dk

    By default, the goal install-cdsdk of the cds-maven-plugin skips the installation of the @sap/cds-dk, if the cds-dk is already installed. Also, it doesn’t update the existing version if you specify a newer version in your pom.xml file. To update an outdated cds-dk, add property -Dcds.install-cdsdk.force=true to the Maven command line to force the installation of a @sap/cds-dk in the configured version:

    mvn spring-boot:run -Dcds.install-cdsdk.force=true

    CDS Maven Plugin

    CDS Maven plugin provides several goals to perform CDS-related build steps. It can be used in CAP Java projects to perform the following build tasks:

    • Install Node.js in the specified version
    • Install the CDS Development Kit @sap/cds-dk in a specified version
    • Perform arbitrary CDS commands on a CAP Java project
    • Generate Java classes for type-safe access
    • Clean a CAP Java project from artifacts of the previous build

    Since CAP Java 1.7.0, that CDS Maven Archetype sets up projects to leverage the CDS Maven plugin to perform the previous mentioned build tasks. On how to modify a project generated with a previous version of the CDS Maven Archetype, see this commit.

    See CDS Maven Plugin documentation for more details.

    ✉
    Show/Hide Beta Features