Skip to content

Latest commit

 

History

History
229 lines (151 loc) · 10.9 KB

getting-started.md

File metadata and controls

229 lines (151 loc) · 10.9 KB
Raw
synopsis redirect_from status
How to start a new CAP Java project and how to run it locally.
java/overview
released

Getting Started

<style scoped> h1:before { content: "Java"; display: block; font-size: 60%; margin: 0 0 .2em; } </style>

{{ $frontmatter.synopsis }}

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 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 { #local}

This section describes the prerequisites and tools to build a CAP application locally.

  1. Install the CDS tools (cds-dk) by following the steps in section Getting Started > Local Set Up.

  2. Install a Java VM. At least, Java 17 is required. For example, download and install SapMachine 17.

  3. Install Apache Maven (at least version 3.5.0 is required).

  1. Execute the following commands on the command line to check whether the installed tools are set up correctly:

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

::: tip For a preconfigured environment, use SAP Business Application Studio, which comes with all 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 { #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 Maven Archetype { #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

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

Afterwards, switch to the new project by calling cd <PROJECT-ROOT>. All following steps need to executed from this directory!

::: 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:add -Dfeature=TINY_SAMPLE

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{target="_blank"} using the following command:

mvn com.sap.cds:cds-maven-plugin:addTargetPlatform -DtargetPlatform=cloudfoundry

This command adds the following dependency to the pom.xml:

<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/

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 schema.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

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

<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:

mvn spring-boot:run

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

Supported IDEs

CAP Java projects can be edited best in a Java IDE. Leaving CDS support aside you could use any Java IDE supporting the import of Maven projects. But as CDS modeling and editing is a core part of CAP application development we strongly recommend to use an IDE with existing Java support:

  • SAP Business Application Studio is a cloud-based IDE with minimal local requirements and footprint. It comes pre packaged with all tools, libraries and extensions that are needed to develop CAP applications.
  • Visual Studio Code is a free and very wide-spread code editor and IDE which can be extended with Java and CDS support. It offers first class CDS language support and solid Java support for many development scenarios.
  • IntelliJ Idea Ultimate is one of the leading Java IDEs with very powerful debugging, refactoring and profiling support. Together with the CDS Plugin it offers the most powerful support for CAP Java application development.

Open the project in your IDE

The rest of this guide is targets IntelliJ Ultimate as your IDE. Nevertheless, the steps should be pretty similar for Visual Studio Code and SAP Business Application Studio.

You can open the project by either running idea . from the project root or use the File->Open... menu.

Source Path Configuration and CDS build

  1. Open the internal terminal with option+F12 (Windows: alt+F12) and type mvn compile to perform a full build of your project. This is needed because the IDE can build the right class path based on the dependencies of the project. But it does not trigger the CDS build or the following code generation. This is covered as part of the mvn compile call.

  2. In the project explorer, find the folder srv/src/gen/java and open the context menu with a right click on the folder. In the menu open Mark directory as and then Sources Root. If the option is not available the directory is already recognized as Sources Root. With this step you make sure that the IntelliJ build recognizes the generated sources as part of the Java ClassPath.

Run and Test the Application

  1. Push Ctrl two times and type "Application". Double click the Application Spring Boot entry to start your CAP Java application.

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

Sample Application { #sample}

Find here the bookshop sample application based on CAP Java.