Search

Getting Started

How to start a new CAP Java project and how to run it locally.

Content

Introduction

The CAP Java SDK enables developing CAP applications in Java. While the SAP Business Application Studio provides excellent support to develop CAP Java applications, you can also develop locally with your tool of choice, for example Eclipse or Visual Studio Code.

The CAP Java SDK supports lean application design by its modular architecture, that means you pick the required features and add them to your application dependencies on demand.

It enables local development by supporting in-memory or file-based SQLite databases. At the same time, the CAP Java SDK enables switching to a productive environment, using, for example, SAP HANA as a database, easily by simply switching the application deployment configuration.

If you use Spring Boot, you find yourself directly at home when using the CAP Java SDK, as the framework integrates nicely with Spring Boot features like transaction handling, auto-wiring and test support. While the CAP Java SDK is framework agnostic, it’s also possible to develop plain Java applications or even integrate with other frameworks.

The CAP Java SDK comes with an OData V4 protocol adapter, but it’s openly designed. You can add more protocol adapters in the future or provide even custom protocol adapters by the application.

It supports SAP Cloud Platform features like authentication and authorization based on XSUAA tokens. But you aren’t locked in to SAP Cloud Platform using a CAP Java application.

Excited? The following sections describe how to set up a development environment to get you started.

Setting Up Local Development

This section describes the prerequisites and tools to build a CAP application locally, for example with Eclipse.

Install the cds-dk

  1. Follow the steps in section Getting Started > Local Set Up to set up the CDS tools.

Install Java & Maven

  1. Install a Java VM. At least, Java 8 is required. For example, download and install SapMachine 11.
  2. Install Apache Maven.

Verify the Setup

Execute the following commands on the command line to check whether the installed tools are setup correctly:

cds --version
java --version
mvn --version

Starting a New Project

Take the following steps to set up a new CAP Java application based on Spring Boot from scratch. As a prerequisite, you’ve setup your development environment.

Quick Start

For a quick start, you can use cds init to bootstrap a CAP Java application based on Spring Boot. Run the following command:

cds init <PROJECT-ROOT> --add java

You can also specify the package name through parameter --java:package. Default for the package name is: org.<PROJECT-ROOT>.

cds init <PROJECT-ROOT> --add java --java:package <java package name>

The artifactId is set to <PROJECT-ROOT> and the groupId to customer.

Using the CAP Java Maven Archetype

Alternatively, use the CAP Java Maven archetype, that is run behind the scenes of cds init, which allows to specify additional options:

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

When prompted, specify the group ID and artifact ID of your application. The artifact ID also specifies the name of your projects root folder that is generated in your current working directory. For other values prompted, it’s enough to simply confirm the default values.

Additional command line options:

  • -DincludeModel=true: Adds a minimalistic sample CDS model to the project
  • -DincludeIntegrationTest=true: Adds an integration test module to the project

Project Layout

The generated project has the following folder structure:

<PROJECT-ROOT>/
|-- db/
`-- srv/
    |-- src/main/java/
    |-- src/gen/java/
    |-- node/
    `-- node_modules/

The generated folders have the following content:

  • db: Contains content related to your database. A simple CDS model is located in the file data-model.cds if you specified -DincludeModel when generating the project.

  • srv: Contains the CDS service definitions and Java back-end code. It also contains the sample file cat-service.cds if you specified to include a sample CDS model.

  • srv/src/main/java: Contains Java application logic.

  • srv/src/gen/java: Contains the compiled CDS model and generated accessor interfaces for typed access.

  • node and node_modules: Contain a local Node.js installation and dependencies for the CDS compiler unless you specify -Dcdsdk-global when starting the build.

    To not be distracted by CDS tools-specific folders in Eclipse, you can define resource filters. Open the context menu on the project’s root folder and select “Properties”. Go to Resource > Resource Filters” and exclude folders with the name node and node_modules.

Add Sample CDS Model

If you didn’t include a sample CDS model when creating a project, you can do this step later. Therefore, go into the root folder of your CAP Java project and execute the following Maven command:

mvn com.sap.cds:cds-maven-plugin:addSample

Add Integration Test Module

You can enhance your CAP Java application with an additional Maven module to perform integration tests. To add such a module, go into the root folder of your CAP Java project and execute the following Maven command:

mvn com.sap.cds:cds-maven-plugin:addIntegrationTest

This command also creates a new folder integration-tests/src/test/java which contains integration test classes:

<PROJECT-ROOT>/
`-- integration-tests/
    `-- src/test/java/
  • integration-tests/src/test/java: contains integration test classes

Build and Run

To build and run the generated project from the command line, execute:

cd <PROJECT-ROOT>
mvn spring-boot:run

To test whether the started application is up and running, open http://localhost:8080 in your browser.

Using 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

Using Eclipse

Install Eclipse

Install the Eclipse IDE for Enterprise Java developers.

Add Spring Tools 4

Install the Spring Tools 4 Eclipse plugin that makes development of Spring applications more convenient: From the Eclipse Marketplace (Help > Eclipse Marketplace…) search and install Spring Tools 4.

Add the SAP Cloud Business Application Tools for Eclipse

Install the Eclipse plug-in called SAP Cloud Business Application Tools for Eclipse that supports convenient editing of CDS files.

  1. In Eclipse open Help > Install New Software….

  2. From SAP Development Tools > Getting Started with the Eclipse Tools for SAP Cloud Application Programming Model add the URL of the tools update site for your Eclipse release.

  3. Select SAP Cloud Business Application Tools > SAP Cloud Business Application Tools for Eclipse.

  4. Click Next and Finish, accept the license agreement and warning about unsigned content, restart Eclipse.

Import the Project

  1. Select File > Import… > Existing Maven Projects.

  2. Select your PROJECT-ROOT folder and click Go. Finally, select the project that was found.

Compile the Project

  1. Right-click on the pom.xml file in the project root folder and select Run as > Maven build

  2. Enter the string clean install to the field labeled with Goals and click Run. This step compiles your CDS artifacts. Repeat this step once your CDS model changes.

Run and Test the Application

  1. Right-click on the project root in the Package Explorer and select Run as > Spring Boot App.

  2. Call the application in your browser at http://localhost:8080/.

Sample Application

Please find the bookshop sample application based on CAP Java here: https://github.com/SAP-samples/cloud-cap-samples-java