Skip to content

Microservices: shared-db for java #2142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Microservices: shared-db for java #2142

Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
43934b7
shared-db w/ java
vl-leon Sep 24, 2025
c448fda
update
vl-leon Oct 8, 2025
13f868e
remove toggles, initial version
renejeglinsky Oct 10, 2025
6f7637e
improve remote odata with destinations
vl-leon Oct 13, 2025
bbbc2be
Merge branch 'main' into microservices/shared-db/java
renejeglinsky Nov 5, 2025
55c9ed6
Merge branch 'main' into microservices/shared-db/java
renejeglinsky Nov 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
270 changes: 266 additions & 4 deletions guides/deployment/microservices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ This guide describes a way to manage development and deployment via *[monorepos]
echo "{\"name\":\"@capire/samples\",\"workspaces\":[\"*\"]}" > package.json
```

<div class="impl node">

2. Add the previously mentioned projects as `git` submodules:

```sh
Expand All @@ -48,13 +50,35 @@ This guide describes a way to manage development and deployment via *[monorepos]
git submodule update --init
```

</div>

<div class="impl java">

2. Add the previously mentioned projects as `git` submodules:

```sh
git init
git submodule add https://github.com/capire/bookstore-java
git submodule add https://github.com/capire/reviews-java
git submodule add https://github.com/capire/orders-java
git submodule add https://github.com/capire/common-java
git submodule add https://github.com/capire/bookshop-java
git submodule add https://github.com/capire/data-viewer-java
git submodule update --init
Copy link
Contributor

@renejeglinsky renejeglinsky Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When will those be available? Asking to make sure we don't merge this PR before

```

</div>

Add a _.gitignore_ file with the following content:
```txt
node_modules
gen
```
> The outcome of this looks and behaves exactly as the monorepo layout in *[cap/samples](https://github.com/capire/samples)*, so we can exercise the subsequent steps in there...


Copy link
Contributor

@github-actions github-actions bot Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove the extra blank line to maintain consistent spacing throughout the document.

<div class="impl node">

3. Test-drive locally:
```sh
npm install
Expand All @@ -64,13 +88,24 @@ This guide describes a way to manage development and deployment via *[monorepos]
cds w bookshop
```

Each microservice can be started independently. If you start each microservice, one after the other in a different terminal, the connection is already established.

[Learn more about Automatic Bindings by `cds watch`](../extensibility/composition#bindings-via-cds-watch){.learn-more}

</div>

<div class="impl java">

3. Test-drive locally:
```sh
cds w bookstore
npm install
```

Each microservice can be started independently. If you start each microservice, one after the other in a different terminal, the connection is already established.
```sh
cd bookstore && npm start
```

[Learn more about Automatic Bindings by `cds watch`](../extensibility/composition#bindings-via-cds-watch){.learn-more}
</div>


::: details The project structure
Expand Down Expand Up @@ -208,8 +243,18 @@ This section is about how to deploy all 3+1 projects at once with a common _mta.

![component diagram with synchronous and event communication for orders](./assets/microservices/bookstore.excalidraw.svg)

<div class="impl node">

[@capire/samples](https://github.com/capire/samples#readme) already has an all-in-one deployment implemented. Similar steps are necessary to convert projects with multiple CAP applications into a shared database deployment.

</div>

<div class="impl java">

<font color=red size=+2>TODO</font> [@capire/samples-java](https://github.com/capire/samples-java#readme) already has an all-in-one deployment implemented. Similar steps are necessary to convert projects with multiple CAP applications into a shared database deployment.

</div>

### Deployment Descriptor

Add initial multitarget application configuration for deployment to Cloud Foundry:
Expand Down Expand Up @@ -258,6 +303,7 @@ build-parameters:
```
:::

<div class="impl node">

::: info `cds build --ws`
If the CDS models of every NPM workspace contained in the monorepo should be considered, then instead of creating this `shared-db` folder, you can also use:
Expand All @@ -269,8 +315,12 @@ The `--ws` aggregates all models in the NPM workspaces.
In this walkthrough, we only include a subset of the CDS models in the deployment.
:::

</div>

<div class="impl node">

::: details Configure each app for cloud readiness

The preceding steps only added configuration to the workspace root.

Additionally add database configuration to each module that we want to deploy - bookstore, orders, and reviews:
Expand All @@ -280,11 +330,25 @@ npm i @cap-js/hana --workspace bookstore
npm i @cap-js/hana --workspace orders
npm i @cap-js/hana --workspace reviews
```

:::

</div>

<div class="impl java">

::: details Configure each app for cloud readiness

For each project add the **cds-starter-cloudfoundry** [starter bundle](https://cap.cloud.sap/docs/java/developing-applications/building#starter-bundles).

:::

</div>

### Applications

<div class="impl node">

Replace the MTA module for `samples-srv` with versions for each CAP service and adjust `name`, `path`, and `provides[0].name` to match the module name. Also change the `npm-ci` builder to the `npm` builder.

::: code-group
Expand Down Expand Up @@ -347,7 +411,90 @@ modules:
```
:::

Add build commands for each module to be deployed:
</div>

<div class="impl java">

Replace the MTA module for `samples-srv` with versions for each CAP service and adjust `name`, `path`, and `provides[0].name` to match the module name. Also change the `npm-ci` builder to the `npm` builder.

::: code-group
```yaml [mta.yaml]
modules:

- name: bookstore-srv # [!code focus]
type: java
path: bookstore/srv # [!code focus]
parameters:
instances: 1
buildpack: sap_java_buildpack_jakarta
properties:
SPRING_PROFILES_ACTIVE: cloud,sandbox
JBP_CONFIG_COMPONENTS: "jres: ['com.sap.xs.java.buildpack.jre.SAPMachineJRE']"
JBP_CONFIG_SAP_MACHINE_JRE: '{ version: 21.+ }'
build-parameters:
builder: custom
commands:
- mvn clean package -DskipTests=true --batch-mode
provides: # [!code focus]
- name: bookstore-api # [!code focus]
properties:
srv-url: ${default-url}
requires:
- name: samples-db
- name: samples-auth
- name: samples-messaging
- name: samples-destination

- name: orders-srv # [!code focus]
type: java
path: orders/srv # [!code focus]
parameters:
instances: 1
buildpack: sap_java_buildpack_jakarta
build-parameters:
builder: custom
commands:
- mvn clean package -DskipTests=true --batch-mode
build-result: target/*-exec.jar
provides: # [!code focus]
- name: orders-api # [!code focus]
properties:
srv-url: ${default-url}
requires:
- name: samples-db
- name: samples-auth
- name: samples-messaging
- name: samples-destination

- name: reviews-srv # [!code focus]
type: java
path: reviews/srv # [!code focus]
parameters:
instances: 1
buildpack: sap_java_buildpack_jakarta
build-parameters:
builder: custom
commands:
- mvn clean package -DskipTests=true --batch-mode
build-result: target/*-exec.jar
provides: # [!code focus]
- name: reviews-api # [!code focus]
properties:
srv-url: ${default-url}
requires:
- name: samples-db
- name: samples-auth
- name: samples-messaging
- name: samples-destination
...
```
:::

</div>

<div class="impl node">

Add build commands for each module to be prepared for deployment:

::: code-group
```yaml [mta.yaml]
Expand All @@ -367,6 +514,8 @@ build-parameters:
Note that we use the *--ws-pack* option for some modules. It's important for node modules referencing other repository-local node modules.
:::

</div>


### Authentication

Expand Down Expand Up @@ -400,6 +549,8 @@ Add the admin role
```
:::

<div class="impl node">
Copy link
Contributor

@renejeglinsky renejeglinsky Oct 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there nothing similar for Java?


::: details Configure each app for cloud readiness
Add NPM dependency `@sap/xssec`:

Expand All @@ -410,10 +561,14 @@ npm i @sap/xssec --workspace reviews
```
:::

</div>

### Messaging

The messaging service is used to organize asynchronous communication between the CAP services.

<div class="impl node">

```shell
cds add enterprise-messaging
```
Expand Down Expand Up @@ -499,6 +654,69 @@ Enable messaging for the modules that use it:

:::

</div>

<div class="impl java">

Create a new file named event-mesh.json to store the configuration for enterprise messaging. Skip the `emname` and `namespace` properties, as these will be parameterized dynamically in the mta.yaml file:
Copy link
Contributor

@github-actions github-actions bot Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence structure is unclear and contains grammatical issues. Consider revising to:

"Create a new file named event-mesh.json to store the configuration for enterprise messaging. Skip the emname and namespace properties, as these are parameterized dynamically in the mta.yaml file:"


::: code-group
```json [event-mesh.json]
{
"version": "1.1.0",
"emname": "samples-emname", // [!code --]
"version": "1.1.0",
"namespace": "default/samples/1", // [!code --]
Comment on lines +607 to +612
Copy link
Contributor

@github-actions github-actions bot Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a duplicate line in the JSON configuration. Remove the duplicate "version": "1.1.0", line:

{
  "version": "1.1.0",
  "options": {
    "management": true,
    "messagingrest": true,
    "messaging": true
  },
  // ... rest of the configuration
}

Comment on lines +608 to +612
Copy link
Contributor

@github-actions github-actions bot Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a duplicate line in the JSON configuration. Remove the duplicate "version": "1.1.0", line:

{
  "version": "1.1.0",
  "options": {
    "management": true,
    "messagingrest": true,
    "messaging": true
  },

"options": {
"management": true,
"messagingrest": true,
"messaging": true
},
"rules": {
"topicRules": {
"publishFilter": [
"*"
],
"subscribeFilter": [
"*"
]
},
"queueRules": {
"publishFilter": [
"*"
],
"subscribeFilter": [
"*"
]
}
},
"authorities": [
"$ACCEPT_GRANTED_AUTHORITIES"
]
}
```
:::

Add messaging resource in mta.yaml with parametrized `emname` and `namespace` properties:
Copy link
Contributor

@github-actions github-actions bot Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use active voice and present tense. Change "Add messaging resource in mta.yaml" to "Add a messaging resource in mta.yaml":

"Add a messaging resource in mta.yaml with parameterized emname and namespace properties:"

Copy link
Contributor

@github-actions github-actions bot Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spelling error: "parametrized" should be "parameterized" for consistency with American English spelling used elsewhere in the document.


::: code-group
```yaml [mta.yaml]
resources:
- name: samples-messaging
type: org.cloudfoundry.managed-service
parameters:
service: enterprise-messaging
service-plan: default
path: ./event-mesh.json
config: # [!code ++]
emname: bookstore-${org}-${space} # [!code ++]
namespace: cap/samples/${space} # [!code ++]
```
:::


</div>


### Destinations

Expand Down Expand Up @@ -550,6 +768,8 @@ modules:

Use the destinations in the bookstore application:

<div class="impl node">

::: code-group
```yaml [mta.yaml]
modules:
Expand All @@ -561,6 +781,35 @@ modules:
```
:::

</div>

<div class="impl java">

::: code-group
```yaml [bookstore/srv/src/main/resources/application.yaml]
cds:
odataV4.endpoint.path: /
messaging.services:
samples-messaging:
kind: enterprise-messaging
remote.services: # [!code ++]
OrdersService: # [!code ++]
type: "odata-v4" # [!code ++]
http: # [!code ++]
suffix: "/odata/v4" # [!code ++]
destination: # [!code ++]
name: "orders-dest" # [!code ++]
ReviewsService: # [!code ++]
type: "odata-v4" # [!code ++]
destination: # [!code ++]
name: "reviews-dest" # [!code ++]
```
:::

</div>

<div class="impl node">

::: details Configure each app for cloud readiness

Add `@sap-cloud-sdk/http-client` and `@sap-cloud-sdk/resilience` for each module utilizing the destinations:
Expand All @@ -571,6 +820,19 @@ npm i @sap-cloud-sdk/resilience --workspace bookstore
```
:::

</div>


<div class="impl java">

::: details Configure each app for cloud readiness

Add dependency to the **cds-feature-remote-odata** [application plugin](https://cap.cloud.sap/docs/java/developing-applications/building#standard-modules)

:::
Copy link
Contributor

@github-actions github-actions bot Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a missing closing tag for the details section. The section appears to be incomplete without proper closure.


</div>

### Approuter

Add [approuter configuration](../deployment/to-cf#add-app-router) using the command:
Expand Down
Loading