Skip to content

Commit

Permalink
Introduced the outbox event versioning (#1535)
Browse files Browse the repository at this point in the history 
Co-authored-by: Rene Jeglinsky <[email protected]>
  • Loading branch information
@dimamost @renejeglinsky
dimamost and renejeglinsky authored Dec 19, 2024
1 parent 049c33c commit d270199
Show file tree
Hide file tree
Showing 2 changed files with 93 additions and 56 deletions.
113 changes: 57 additions & 56 deletions java/developing-applications/building.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -378,87 +378,88 @@ Use the _.cdsrc.json_ file to add project specific configuration of `@sap/cds-dk
### Using a Local cds-dk

Starting with version 3.6.0 of the `cds-services-archetype`, the default setup of a newly created CAP Java project has changed. The `@sap/cds-dk` is maintained as a `devDependency` in `package.json` and installed with an `npm ci` during the Maven build.
The `install-cdsdk` goal is no longer used to install the `@sap/cds-dk` locally and it's also marked as deprecated. The version of the `@sap/cds-dk` is no longer maintained in `pom.xml`, it's configured in the `package.json`:
The `install-cdsdk` goal is no longer used to install the `@sap/cds-dk` locally and it's also marked as deprecated. The version of the `@sap/cds-dk` is no longer maintained in _pom.xml_, it's configured in the _package.json_:
```json
{
"devDependencies" : {
"@sap/cds-dk" : "^8.5.1",
}
}
```
A `package-lock.json` is also created during project creation with the `cds-services-archetype`. The lock file is needed for `npm ci` to run successfully and pins the transitive dependencies of @sap/cds-dk to fixed versions. Fixing the versions ensures that the CDS build is fully reproducible.
A `package-lock.json` is also created during project creation with the `cds-services-archetype`. The lock file is needed for `npm ci` to run successfully and pins the transitive dependencies of `@sap/cds-dk` to fixed versions. Fixing the versions ensures that the CDS build is fully reproducible.

::: warning
For multitenant applications, ensure that the `@sap/cds-dk` version in the sidecar is in sync.
:::

#### Migrate from goal `install-cdsdk` to `npm ci` { #migration-install-cdsdk }
#### Migrate From Goal `install-cdsdk` to `npm ci`
{ #migration-install-cdsdk }

To migrate from the deprecated goal `install-cdsdk` to the new `npm ci` approach, the following steps are required:

1. Remove execution of goal `install-cdsdk` from the `cds-maven-plugin` in `srv/pom.xml`:
```xml
<plugin>
<groupId>com.sap.cds</groupId>
<artifactId>cds-maven-plugin</artifactId>
<version>${cds.services.version}</version>
<executions>
<!-- Delete from here ... -->
<execution>
<id>cds.install-cdsdk</id>
<goals>
<goal>install-cdsdk</goal>
</goals>
</execution>
<!-- ... to here -->
```

2. Then add execution of goal `npm` with arguments `ci` instead to the `cds-maven-plugion` in `srv/pom.xml`:
```xml
<execution>
<id>cds.npm-ci</id>
<goals>
<goal>npm</goal>
</goals>
<configuration>
<arguments>ci</arguments>
</configuration>
</execution>
```

3. Remove cds-dk version property `cds.install-cdsdk.version` from `pom.xml`:
```xml
<properties>
<!-- Delete from here ... -->
<cds.install-cdsdk.version>8.4.2</cds.install-cdsdk.version>
<!-- ... to here -->
</properties>
```

4. Add `@sap/cds-dk` as devDependency to `package.json`:
```json
{
"devDependencies" : {
"@sap/cds-dk" : "^8.5.0"
}
}
```

5. Perform `npm install` on the command line to get the `package-lock.json` created or updated.
1. Remove execution of goal `install-cdsdk` from the `cds-maven-plugin` in _srv/pom.xml_:
```xml
<plugin>
<groupId>com.sap.cds</groupId>
<artifactId>cds-maven-plugin</artifactId>
<version>${cds.services.version}</version>
<executions>
<!-- Delete from here ... -->
<execution>
<id>cds.install-cdsdk</id>
<goals>
<goal>install-cdsdk</goal>
</goals>
</execution>
<!-- ... to here -->
```

2. Then add execution of goal `npm` with arguments `ci` instead to the `cds-maven-plugin` in _srv/pom.xml_:
```xml
<execution>
<id>cds.npm-ci</id>
<goals>
<goal>npm</goal>
</goals>
<configuration>
<arguments>ci</arguments>
</configuration>
</execution>
```

3. Remove cds-dk version property `cds.install-cdsdk.version` from _pom.xml_:
```xml
<properties>
<!-- Delete from here ... -->
<cds.install-cdsdk.version>8.4.2</cds.install-cdsdk.version>
<!-- ... to here -->
</properties>
```

4. Add `@sap/cds-dk` as devDependency to _package.json_:
```json
{
"devDependencies" : {
"@sap/cds-dk" : "^8.5.0"
}
}
```

5. Perform `npm install` on the command line to get the _package-lock.json_ created or updated.

6. Finally, do a `mvn clean install` and verify that the installation of `@sap/cds-dk` is done with the new approach.

#### Maintaining cds-dk

1. package.json and npm ci
1. _package.json_ and `npm ci` <br>
Newly created CAP Java projects maintain the `@sap/cds-dk` with a specific version as a devDependency in `package.json`. So, when you update the version, run npm install from the command line to update the `package-lock.json`. `npm ci` will then install the updated version of `@sap/cds-dk`.

2. Goal install-cdsdk
2. Goal `install-cdsdk` <br>
Older CAP Java projects that use the `install-cdsdk` goal of the `cds-maven-plugin` don't update `@sap/cds-dk`. By default, the goal skips the installation if it's already installed.
To update the `@sap/cds-dk` version:

1. Specify a newer version of `@sap/cds-dk` in your *pom.xml* file.
2. Execute `mvn spring-boot:run` with an additional property `-Dcds.install-cdsdk.force=true`, to force the installation of a **`@sap/cds-dk`** in the configured version.
3. Specify a newer version of `@sap/cds-dk` in your *pom.xml* file.
4. Execute `mvn spring-boot:run` with an additional property `-Dcds.install-cdsdk.force=true`, to force the installation of a **`@sap/cds-dk`** in the configured version.

```sh
mvn spring-boot:run -Dcds.install-cdsdk.force=true
Expand Down
36 changes: 36 additions & 0 deletions java/outbox.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,42 @@ processed anymore.

:::

### Outbox Event Versions

In scenarios with multiple deployment versions (blue/green), situations may arise in which the outbox collectors of the older deployment cannot process the events generated by a newer deployment. In this case, the event can get stuck in the outbox, with all the resulting problems.

To avoid this problem, you can configure the outbox to use an event version that prevents the outbox collectors from using the newer events. For this purpose, you can set the parameter [<Config java keyOnly filesOnly>cds.environment.deployment.version: 2</Config>](../java/developing-applications/properties#cds-environment-deployment-version).

::: warning Ascending Versions
The configured deployment versions must be in ascending order. The messages are only processed by the outbox collector if the event version is less than or equal to the deployment version.
:::

To make things easier, you can automate versioning by using the Maven app version. This requires you to increment the version for each new deployment.

To do this, the Maven `resource.filtering` configuration in the `srv/pom.xml` must be activated as follows, so that the app version placeholder `${project.version}` can be used in [<Config java keyOnly filesOnly>cds.environment.deployment.version: ${project.version}</Config>](../java/developing-applications/properties#cds-environment-deployment-version).

::: code-group
```xml [srv/pom.xml]
<build>
...
<resources>
<resource>
<directory>src/main/resources</directory>
<filtering>true</filtering>
</resource>
</resources>
...
```
:::

To be sure that the deployment version has been set correctly, you can find a log entry at startup that shows the configured version:

```bash
2024-12-19T11:21:33.253+01:00 INFO 3420 --- [main] cds.serviceces.impl.utils.BuildInfo : application.deployment.version: 1.0.0-SNAPSHOT
```

And finally, if for some reason you don't want to use a version check for a particular outbox collector, you can switch it off via the outbox configuration [<Config java filesOnly>cds.outbox.services.MyCustomOutbox.checkVersion: false</Config>](../java/developing-applications/properties#cds-outbox-services-<key>-checkVersion).

## Outboxing CAP Service Events

Outbox services support outboxing of arbitrary CAP services. A typical use case is to outbox remote OData
Expand Down

0 comments on commit d270199

Please sign in to comment.