/cloud-cap-samples-java

A sample application that demonstrates the features of the Java SDK for the SAP Cloud Application Programming Model.

Primary LanguageJava

Welcome to CAP Samples for Java

CI status REUSE status

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.

Book Object Page

Outline

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.

Demonstrated Features

Framework and Infrastructure related Features:

Domain Model related Features:

Service Model related Features:

User Interface related Features:

CDS Maven Plugin Features:

  • Install Node.js in the default 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
  1. 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. 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 are defined for local development:

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

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 the project (module) needs to be extended with the folder containing the generated code. In order to add the generated code you need to add the 'gen' folder to the build path:

  • Open the project settings.
  • Navigate to the 'modules' section.
  • Select the srv/src/gen folder and mark it as 'sources'.
  • Save and leave the project settings.
  • Trigger a rebuild.

After the generated code is considered by IntelliJ's build the application can be handled just as any other Spring Boot application in IntelliJ.

Database Setup and Spring Profiles

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

  • The default profile specifies to use an in-memory H2 database. The in-memory database is set up automatically during startup of the application and initialized with some example data from CSV files.

  • When deploying the application to Cloud Foundry, 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 SAP HANA service bindings available in the environment.

Deploy to SAP Business Technology Platform

CAP Java applications can be deployed to the SAP Business Technology Platform either in single tenant or in multitenancy mode. See Multitenancy in CAP Java for more information.

Prerequisites:

Deploy as Single Tenant Application:

  • Rename mta-single-tenant.yaml to mta.yaml
  • Run mbt build
  • Run cf login
  • Run cf deploy mta_archives/bookshop_1.0.0.mtar

Deploy as Multitenant Application:

  • Create a SAP HANA Cloud Instance in your SAP Business Technology Platform space.
  • Rename mta-multi-tenant.yaml to mta.yaml
  • Run mbt build
  • Run cf login
  • Run cf deploy mta_archives/bookshop-mt_1.0.0.mtar
  • Go to another subaccount in your global account, under subscriptions and subscribe to the application you deployed.
  • Run cf map-route bookshop-mt-app <YOUR DOMAIN> --hostname <SUBSCRIBER TENANT>-<ORG>-<SPACE>-bookshop-mt-app or create and bind the route manually.

Code Tour

Take the guided tour in VS Code through our CAP Samples for Java and learn which CAP features are showcased by the different parts of the repository. Just install the CodeTour extension for VS Code.

Get Support

In case you have a question, find a bug, or otherwise need support, please use our community. See the documentation at https://cap.cloud.sap for more details about CAP.

License

Copyright (c) 2021 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.