README.md

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 Eclipse
    • Building and Running
  • Database Setup and Spring Profiles
  • Using a File-Based SQLite Database
• Get Support
• License

Overview

This sample application shows how to conveniently create business applications based on CDS domain models, persisting data with SQLite, 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 or optionally a file-based SQLite database is used for data persistency. Once productively deployed to SAP Cloud 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 Fiori UI is added using predefined SAP Fiori elements templates. Fiori annotations add information to the service definitions, on how to render the data.

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)

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

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

User Interface related Features:

• Support for SAP Fiori Elements
• Fiori Draft based Editing for Books and Authors
• Fiori annotations specific for Browse Books, Manage Books, Manage Orders and common annotations, which apply to all UI's
• UI Annotations for custom actions in the 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

CDS Maven Plugin Features:

• Install Node.js in the specified version
• Install the latest 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, and Apache Maven) as described here.

Clone Build & Run

1. Clone the project:

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

2. Build and run the application:

  mvn spring-boot:run

Using Eclipse

Optionally, 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}

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

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

   http://localhost:8080/: This should show the automatically generated index page of served paths. http://localhost:8080/fiori.html: This is the actual bookshop application UI

   You'll start with an empty stock of books as this procedure starts the bookshop application with an empty in-memory sqlite database.

   Two mock users are defined for local development:

   • User: user, password: user to browse books
   • User: admin, password: admin to manage books and orders

Database Setup and Spring Profiles

The application comes with three predefined profiles: default, sqlite, and cloud (see src/main/resources/application.yaml).

• The default profile specifies to use an in-memory SQLite database. The in-memory database is set up automatically during startup of the application. However, example data from CSV files aren’t yet automatically imported, therefore some content needs to be created via OData V4 API requests.

• The sqlite profile specifies to use a persistent SQLite database from root directory of the project. This database needs to be created first, to ensure it’s initialized with the correct schema and with the CSV-based example data. To initialize the database, simply run cds deploy --to sql:sqlite.db --no-save from the project's root directory. Repeat this step, once you make changes to the CDS model.

• When deploying the application to the CloudFoundry, the CF Java Buildpack automatically configures the cloud Spring profile. This profile doesn’t specify any datasource location. In that case CAP Java can automatically detect HANA service bindings available in the environment.

Using a File-Based SQLite Database

To switch from the default in-memory SQLite database to a file-based SQLite database in this sample application perform the following steps:

1. Deploy the example data stored in .csv files in the folder db/data to a file-based SQLite database by executing the command-line utility

   cds deploy --to sql:sqlite.db --no-save

   from your project root folder.

2. Edit your Run Configuration via Run > Run Configurations... and select enter the Profile sqlite on tab Spring and click Run.

Get Support

Check out the documentation at https://cap.cloud.sap. In case you have a question, find a bug, or otherwise need support, please use our community.

License

Copyright (c) 2020 SAP SE or an SAP affiliate company. All rights reserved. This file is licensed under the Apache Software License, version 2.0 except as noted otherwise in the LICENSE file.