Getting Started β
How to start a new CAP Java projectΒ and how to run it locally.
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 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 BTP features like authentication and authorization based on XSUAA tokens. But you aren't locked in to SAP BTP 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.
Install the CDS tools (
cds-dk
) by following the steps in section Getting Started > Local Set Up.Install a Java VM. At least, Java 17 is required. For example, download and install SapMachine 17.
Install Apache Maven (at least version 3.5.0 is required).
Execute the following commands on the command line to check whether the installed tools are set up correctly:
shcds --version java --version mvn --version
cds --version java --version mvn --version
TIP
For a preconfigured environment, use SAP Business Application Studio, which comes with all of the required tools preinstalled. In older workspaces it might be necessary to explicitly set the JDK to version 17 with the command Java: Set Default JDK
.
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 set up your development environment.
Run the CAP Java Maven Archetype β
Use the CAP Java Maven archetype to bootstrap a new CAP Java project:
mvn archetype:generate -DarchetypeArtifactId="cds-services-archetype" -DarchetypeGroupId="com.sap.cds" -DarchetypeVersion="RELEASE" -DinteractiveMode=true
mvn archetype:generate -DarchetypeArtifactId="cds-services-archetype" -DarchetypeGroupId="com.sap.cds" -DarchetypeVersion="RELEASE" -DinteractiveMode=true
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.
Alternatively, you can use the CDS tools to bootstrap a Java project:
cds init <PROJECT-ROOT> --add java
cds init <PROJECT-ROOT> --add java
TIP
You can call cds help init
for more information on the available options.
Add a Sample CDS Model β
You can use the CDS Maven plugin to add a sample CDS model after creating your project. Navigate to the root folder of your CAP Java project and execute the following Maven command:
mvn com.sap.cds:cds-maven-plugin:addSample
mvn com.sap.cds:cds-maven-plugin:addSample
Add CloudFoundry target platform β
Following the "Grow As You Go" principle, the generated CAP Java project doesn't contain support for Cloud Foundry as the target platform. To enhance your project with dependencies required for Cloud Foundry, execute the goal addTargetPlatform
of the CDS Maven plugin using the following command:
mvn com.sap.cds:cds-maven-plugin:addTargetPlatform -DtargetPlatform=cloudfoundry
mvn com.sap.cds:cds-maven-plugin:addTargetPlatform -DtargetPlatform=cloudfoundry
This commands adds the following dependency to the pom.xml:
<dependency>
<groupId>com.sap.cds</groupId>
<artifactId>cds-starter-cloudfoundry</artifactId>
</dependency>
<dependency>
<groupId>com.sap.cds</groupId>
<artifactId>cds-starter-cloudfoundry</artifactId>
</dependency>
TIP
CAP Java also provides a starter bundle for SAP BTP Kyma environment. See CAP Starter Bundles for more details.
Project Layout β
The generated project has the following folder structure:
<PROJECT-ROOT>/
|-- db/
`-- data-model.cds
`-- srv/
|-- cat-service.cds
|-- src/main/java/
|-- src/gen/java/
`-- node_modules/
<PROJECT-ROOT>/
|-- db/
`-- data-model.cds
`-- srv/
|-- cat-service.cds
|-- src/main/java/
|-- src/gen/java/
`-- node_modules/
The generated folders have the following content:
Folder | Description |
---|---|
db | Contains content related to your database. A simple CDS domain model is located in the file data-model.cds. |
srv | Contains the CDS service definitions and Java back-end code and the sample service model cat-service.cds. |
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_modules | Generated when starting the build, containing the dependencies for the CDS tools (unless you specify -Dcdsdk-global when starting the build). |
Add an Integration Test Module (Optional) β
Optionally, you can use the CDS Maven plugin to 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
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/
<PROJECT-ROOT>/
`-- integration-tests/
`-- src/test/java/
Folder | Description |
---|---|
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
cd <PROJECT-ROOT>
mvn spring-boot:run
TIP
To test whether the started application is up and running, open http://localhost:8080 in your browser.
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 plugin called SAP Cloud Business Application Tools for Eclipse that supports convenient editing of CDS files.
In Eclipse open Help > Install New Software....
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.
Select SAP Cloud Business Application Tools > SAP Cloud Business Application Tools for Eclipse.
Click Next and Finish, accept the license agreement and warning about unsigned content, restart Eclipse.
Import the Project β
Select File > Import... > Existing Maven Projects.
Select your
PROJECT-ROOT
folder and click Go. Finally, select the project that was found.
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_modules
.
Compile the Project β
Right-click on the
pom.xml
file in the project root folder and select Run as > Maven build.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.Right-click on the root project and select Maven > Update Project .... Make sure Refresh workspace resources from local filesystem is selected and choose Ok.
Run and Test the Application β
Right-click on the project root in the Package Explorer and select Run as > Spring Boot App.
Call the application in your browser at http://localhost:8080/.
Sample Application β
Find here the bookshop sample application based on CAP Java.