Welcome to CAP Samples for Java

Welcome to the bookshop-java project. It demonstrates how to build business applications using the CAP Java SDK providing a book shop web application as an example. The application in this project enables browsing books, managing books, and managing orders.

Outline

• Overview
• Demonstrated Features
• Getting Started
• Prerequisites
• Clone Build & Run
• Using VS Code
• Using Eclipse
  • Building and Running
• Using IntelliJ Idea (Community and Ultimate)
• Database Setup and Spring Profiles
• API_BUSINESS_PARTNER Remote Service and Spring Profiles
• Deploy to SAP Business Technology Platform, Cloud Foundry
• Deploy to SAP Business Technology Platform, Kyma Runtime
• Setup Authorizations in SAP Business Technology Platform
• Code Tour
• Get Support
• License

Overview

This sample application shows how to conveniently create business applications based on CDS domain models, persisting data with H2, or SAP HANA, and exposing an OData V4 frontend with an SAP Fiori frontend on top.

This sample uses Spring Boot as an application framework. Although a CAP Java application isn’t required to build on Spring Boot, it’s the first choice of framework, as it’s seamlessly integrated.

The domain models are defined using CDS entity definitions.

By default, an in-memory H2 database is used for data persistency. Once productively deployed to SAP Business Technology Platform, SAP HANA can be used.

Services are defined using CDS Service Models. The OData V4 Protocol Adapter translates the CDS service models into corresponding OData schemas and maps the incoming OData requests to the corresponding CDS services.

Although CAP provides generic event handlers to serve most CRUD requests out-of-the-box, it’s possible to add business logic through Custom Event Handlers.

A SAP Fiori UI is added using predefined SAP Fiori elements templates. SAP Fiori annotations add information to the service definitions, on how to render the data.

CAP provides built-in multitenancy support with out-of-the box tenant isolation. The sample application demonstrates usage of MTX sidecar based on streamlined MTX and can be deployed as multitenant application. The deprecated classic MTX setup is shown in the mtx-classic branch for reference.

Demonstrated Features

Framework and Infrastructure related Features:

• Application configuration for Spring and CDS using application.yaml
• Mocking users for local development
• Authentication & Authorization (including user-specific restrictions with @restrict in the Admin Service)
• Cloud Foundry Deployment using MTA with XSUAA Service Bindings
• Application Router configuration including authentication via the XSUAA Service. See package.json, xs-app.json and xs-security.json
• Multitenancy configuration via mta-multi-tenant.yaml, .cdsrc.json, sidecar module
• Feature toggles. In CF, features can be toggled by assigning the roles expert or premium-customer to the user.
• Messaging configuration and handlers with local messaging and message brokers.
• Consumption of Remote services in [srv/external.cds] and [srv/notes-mashup.cds]

Domain Model related Features:

• CDS Query Language with a Static CDS Model in the Admin Service
• Use of Aspects in the Model Definition such as the managed or cuid Aspect in Books
• Input validation using model annotation @assert.format
• Data Localization for Books
• Use of Media Data in Books and AdminService

Service Model related Features:

• Custom event handlers such as the Custom business logic for the Admin Service
• Custom actions such as addToOrder in the Admin Service. The Action implementation is in the Admin Service Event Handler
• Add annotations for searchable elements in the Admin Service
• Localized Messages in the Admin Service Event Handler
• role- and instance-based restrictions in AdminService and ReviewService
• Use of @cds.persistence.skip in AdminService
• Media Data processing in the Admin Service Event Handler

User Interface related Features:

• Support for SAP Fiori Elements
• SAP Fiori Draft based Editing for Books, Orders and Reviews
• SAP Fiori annotations specific for Browse Books, Manage Books, Manage Orders, Manage Reviews and common annotations, which apply to all UI's
• UI Annotations for custom actions in the Browse Books and Manage Books UI, including annotations for a button and a popup
• Value Help for Books and Authors
• Model Localization for English and German language for static texts
• Custom File Upload extension which provides a button for uploading CSV files
• A simple Swagger UI for the CatalogService API at http://localhost:8080/swagger/index.html
• UI5 Tree Table with CRUD requests and Value Help for GenreHierarchy. Please note, that Tree Tables must be used with HANA (for productive usage) or H2 (for local development and testing).
• Custom actions such as moveSibling in the Admin Service. This action demonstrates experimental UI feature ChangeNextSiblingAction. The Action implementation is in the Hierarchy Sibling Action Handler

CDS Maven Plugin Features:

• Install Node.js in the default version.
• Install a configured version of @sap/cds-dk.
• Execute arbitrary CDS commands.
• Generate Java POJOs for type-safe access to the CDS model.
• Clean project from artifacts of the previous build.

Getting Started

The following sections describe how to set up, build, and run the project.

Prerequisites

Make sure you have set up a development environment (that means, you’ve installed the CDS Compiler, Java 21, and Apache Maven) as described here. This sample application requires a Java 21 compatible JDK. We recommend using SapMachine 21.

Clone Build & Run

1. Clone the project:

bash git clone https://github.com/SAP-samples/cloud-cap-samples-java.git

1. Build and run the application:

mvn spring-boot:run

[!NOTE] Please note that some IDEs may interfere with their autobuild when launching the application from the CLI using Maven. Therefore, please ensure that no IDEs are running in parallel or launch the application natively from your preferred IDE as described below.

1. Use the following links in the browser to check if everything works fine:

2. http://localhost:8080: This should show the automatically generated index page of served paths.

3. http://localhost:8080/fiori.html: This is the actual bookshop application UI.
4. http://localhost:8080/swagger/index.html: This is providing a Swagger UI for the CatalogService API.

You'll start with a predefined stock of books as this procedure starts the bookshop application with a CSV-initialized in-memory H2 database.

Two mock users in addition to the default mock users are defined for local development: - User: user, password: user to browse books - User: admin, password: admin to manage books and orders

Testing in hybrid mode

You can test the GenreHierarchyTest on H2 using the profile default as well as on HANA using the profile cloud

cds bind --exec -- mvn clean install -Dspring.profiles.active=cloud

Using VS Code

VS Code supports the project out-of-the-box, when using the Extension Pack for Java. To launch the application in VS Code navigate to the Application class and click on Run or Debug.

Using Eclipse

Use the following steps to import the project to Eclipse:

1. Import the project using File > Import > Existing Maven Projects.

   Now, you should see the projects bookshop and bookshop-parent in the project/package explorer view.

2. In Project Explorer, change the property "Package Presentation" from "Flat" to "Hierarchical" for better understanding.

Building and Running

1. To compile the project, right-click the file pom.xml in the bookshop-parent project root folder and select Run as > Maven build.

   In the following dialog, enter the string clean install into the field labeled with "Goals" and click "Run".

   Note: This step also compiles the CDS artifacts, thus repeat this once you made changes to the CDS model. This step also generates source files, therefore refresh the "bookshop" project in your IDE.

2. To run the application, right-click the bookshop project root in the Package Explorer and select Run as > Spring Boot App (make sure you have Spring Tools 4 installed).

   This step creates a default Run Configuration named Bookshop - Application and starts the application afterwards. To go on with the next step, stop the application again.

3. Then, set the default working directory by editing your Run Configuration via Run > Run Configurations > Bookshop - Application. On the tab Arguments change the default Working Directory to:

   ${workspace_loc:bookshop-parent}

   Afterward, click Run. This step starts the applications main method located in src/main/java/my/bookshop/Application.java.

Using IntelliJ Idea (Community and Ultimate)

IntelliJ can handle the project more or less out-of-the-box. Since some of the event handlers in the project rely on the code generated from the CDS model the build path of