From 6b02ca1a4fbf4ac61b1457bce009f3721a06f482 Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Mon, 20 Apr 2026 11:59:50 +0200 Subject: [PATCH 1/3] document new maven compiler plugin --- docs/Authorization/Testing.md | 73 +++++++++++------------------------ 1 file changed, 23 insertions(+), 50 deletions(-) diff --git a/docs/Authorization/Testing.md b/docs/Authorization/Testing.md index d872961..2789d60 100644 --- a/docs/Authorization/Testing.md +++ b/docs/Authorization/Testing.md @@ -145,8 +145,8 @@ In CAP Node.js projects, this is done automatically by `@sap/ams-dev` before `cd ```json [Node.js] // package.json "scripts": { - "jest": "NODE_ENV=test npx jest", - "pretest": "npx compile-dcl -d auth/dcl -o test/dcn", // [!code ++] + "test": "NODE_ENV=test npx jest", + "pretest": "npx compile-dcl -d auth/dcl -o test/dcn", // [!code ++] }, "devDependencies": { "@sap/ams-dev": "^2", // [!code ++] @@ -157,29 +157,22 @@ In CAP Node.js projects, this is done automatically by `@sap/ams-dev` before `cd - - - com.sap.cds - cds-maven-plugin - - - - // [!code ++:14] - - compile-dcl - - npx - - generate-test-resources - - --package=@sap/ams-dev compile-dcl - -d ${project.basedir}/src/main/resources/ams - -o ${project.basedir}/target/generated-test-sources/dcn - - - - - + + + com.sap.cloud.security.ams.dcl + dcl-compiler-plugin + ${sap.cloud.security.ams.dcl-compiler.version} + + + + compile + + + ${project.basedir}/src/main/resources/ams + + + + ``` @@ -187,36 +180,16 @@ In CAP Node.js projects, this is done automatically by `@sap/ams-dev` before `cd ```xml [Java] - - - // [!code ++:31] + - com.github.eirslett - frontend-maven-plugin - 1.14.1 + com.sap.cloud.security.ams.dcl + dcl-compiler-plugin + ${sap.cloud.security.ams.dcl-compiler.version} - install node and npm - - install-node-and-npm - - generate-test-resources - - v24.11.0 - - - - compile-dcl - npx + compile - generate-test-resources - - --package=@sap/ams-dev compile-dcl - -d ${project.basedir}/src/main/resources/dcl - -o ${project.basedir}/target/generated-test-sources/dcn - - From 15e4bdccdbbeee672b2b94dae3c3b8ef65902c16 Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Fri, 24 Apr 2026 11:55:16 +0200 Subject: [PATCH 2/3] add compiler plugin documentation --- docs/.vitepress/config.js | 1 + docs/Authorization/GettingStarted.md | 31 ++++---- .../java/dcl-compiler-maven-plugin.md | 74 +++++++++++++++++++ 3 files changed, 92 insertions(+), 14 deletions(-) create mode 100644 docs/Libraries/java/dcl-compiler-maven-plugin.md diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index f32dc25..598b2d0 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -61,6 +61,7 @@ export default defineConfig(withMermaid({ { text: 'ams-test', link: '/Libraries/java/ams-test' }, { text: 'cap-ams', link: '/Libraries/java/cap-ams' }, { text: 'spring-boot-ams', link: '/Libraries/java/spring-boot-ams' }, + { text: 'dcl-compiler-plugin', link: '/Libraries/java/dcl-compiler-maven-plugin' }, { text: 'Version 3.x', collapsed: true, diff --git a/docs/Authorization/GettingStarted.md b/docs/Authorization/GettingStarted.md index a804abc..48a8459 100644 --- a/docs/Authorization/GettingStarted.md +++ b/docs/Authorization/GettingStarted.md @@ -44,23 +44,25 @@ language and framework you are using. ## Dependency Setup -::: tip -In CAP applications, the [`cds add ams`](https://cap.cloud.sap/docs/tools/cds-cli#cds-add) command can be executed with -the *latest version* of [`@sap/cds-dk`](https://cap.cloud.sap/docs/tools/cds-cli#cli). It automatically adds the correct -dependencies. -::: - -The following tables give an overview of the required AMS module dependencies for different application setups. +The following sections give an overview of the required AMS module dependencies for different application setups. ::: warning The recommended modules and versions have changed over time (see [Historical Setups](#historical-setups)) -**Please begin new projects with the currently recommended modules**. +**Please begin new projects with the latest version of the currently recommended modules**. +::: +# +::: tip +In CAP applications, the [`cds add ams`](https://cap.cloud.sap/docs/tools/cds-cli#cds-add) command can be executed with +the *latest version* of [`@sap/cds-dk`](https://cap.cloud.sap/docs/tools/cds-cli#cli) to add the recommended +dependencies. The generated AMS versions get regularly updated in newer `@sap/cds-dk` releases. ::: ### Java -::: tip +The latest version can always be found on [Maven Central](https://mvnrepository.com/artifact/com.sap.cloud.security.ams/ams-bom). + +::: tip Spring Boot Support The AMS modules support both Spring Boot 3 and 4. ::: @@ -192,18 +194,19 @@ alternatively `HealthIndicator` beans for Spring Boot Actuator health endpoint i #### Tooling +::: tip DCL Compiler Maven plugin +The [DCL Compiler Maven plugin](/Libraries/java/dcl-compiler-maven-plugin) allows DCL compilation for local integration [tests](/Authorization/Testing) without AMS cloud instance. +::: + ::: tip CDS Build Plugin In CAP Java projects, the (optional) Node.js module `@sap/ams` *should* be added in the `package.json` as a *devDependency* with version `^3` to provide dev-time features as [cds build plugin](/CAP/cds-Plugin). ::: -::: tip DCL compiler plugin -In the near future, there will be new maven build plugin for DCL compilation for local integration tests without AMS cloud instance. -For the time being, refer to the samples for an interim solution based on the Node.js tooling or continue use the old maven DCL compiler plugin. -::: - ### Node.js +The latest versions of the Node.js modules can always be found on [npmjs.org](https://www.npmjs.com/package/@sap/ams). + | Project Type | @sap/ams | @sap/ams-dev | Java JDK | |-------------------|:--------:|:------------:|:--------:| | Plain Node.js | ✓ ^3 | (✓)* ^2 | (✓)* 17+ diff --git a/docs/Libraries/java/dcl-compiler-maven-plugin.md b/docs/Libraries/java/dcl-compiler-maven-plugin.md new file mode 100644 index 0000000..9e13a45 --- /dev/null +++ b/docs/Libraries/java/dcl-compiler-maven-plugin.md @@ -0,0 +1,74 @@ +# DCL Compiler Maven Plugin + +Maven plugin for compiling DCL (Data Control Language) files into DCN (Data Control Notation) format for local +application [testing](/Authorization/Testing). + +## Installation + +Add the plugin to your `pom.xml` (see also the [Testing guide](/Authorization/Testing#compiling-dcl-to-dcn) for full +integration examples): + +```xml + + + + com.sap.cloud.security.ams.dcl + dcl-compiler-plugin + ${sap.cloud.security.ams.dcl-compiler.version} + + + + compile + + + + + + +``` + +The latest version can be found on [Maven Central](https://mvnrepository.com/artifact/com.sap.cloud.security.ams.dcl/dcl-compiler-plugin). + +## Goals + +### `dcl:compile` + +Compiles DCL files to DCN format. Bound to the `generate-test-resources` phase by default. + +### `dcl:validate` + +Validates DCL files without generating output. Bound to the `validate` phase by default. Useful for CI/CD pipelines. + +## Configuration + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `sourceDirectory` | `.../src/main/resources/ams/dcl` | Directory containing DCL source files | +| `outputDirectory` | `.../generated-test-resources/ams/dcn` | Output directory for compiled DCN files (compile only) | +| `skip` | `false` | Skip plugin execution | +| `verbose` | `false` | Enable verbose output | +| `failOn` | `error` | Failure threshold: `error`, `warning`, or `deprecation` | +| `readDcn` | `false` | Allow reading `.dcn` files as input | +| `timeout` | `60000` | CLI timeout in milliseconds | +| `additionalArguments` | - | Additional CLI arguments | + +Parameters can be set in `` or overridden via command line with `-Ddcl.`, e.g. `mvn compile -Ddcl.verbose=true`. + +## Platform-Specific Binaries + +The plugin bundles platform-specific AMS CLI binaries for: +- macOS (Intel and Apple Silicon) +- Linux (x86_64 and ARM64) +- Windows (x86_64) + +The relevant binaries are automatically extracted and +cached in `~/.ams-cli/binaries/{version}/` on first use. + +## Troubleshooting + +**Timeout errors** — Increase the timeout for large projects: `120000` + +**Permission denied (Unix)** — The plugin sets executable permissions automatically. If this fails: +```bash +chmod +x ~/.ams-cli/binaries/{version}/{os}-{arch}/ams +``` From 5e98c8eb500b6ba4b9a93f796abd9950df192e7e Mon Sep 17 00:00:00 2001 From: Manuel Fink Date: Fri, 24 Apr 2026 16:21:44 +0200 Subject: [PATCH 3/3] fix paths in Testing.md --- docs/Authorization/Testing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Authorization/Testing.md b/docs/Authorization/Testing.md index 2789d60..214023e 100644 --- a/docs/Authorization/Testing.md +++ b/docs/Authorization/Testing.md @@ -224,10 +224,10 @@ try { LocalAuthorizationManagementServiceConfig amsTestConfig = new LocalAuthorizationManagementServiceConfig() .withPolicyAssignmentsPath( - Path.of("src", "test", "resources", "mockPolicyAssignments.json")); + Path.of("src/test/resources/mockPolicyAssignments.json")); ams = AuthorizationManagementServiceFactory .fromLocalDcn( - Path.of("target", "generated-test-sources", "ams", "dcn"), amsTestConfig); + Path.of("target/generated-test-resources/ams/dcn"), amsTestConfig); ams.whenReady().get(3, TimeUnit.SECONDS); } catch (TimeoutException e) {