Skip to content

New maven DCL compiler plugin #30

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

Merged
finkmanAtSap merged 3 commits into from
Apr 24, 2026
Merged

New maven DCL compiler plugin #30

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6b02ca1
document new maven compiler plugin
finkmanAtSap Apr 20, 2026
15e4bdc
add compiler plugin documentation
finkmanAtSap Apr 24, 2026
5e98c8e
fix paths in Testing.md
finkmanAtSap Apr 24, 2026
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
1 change: 1 addition & 0 deletions docs/.vitepress/config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
31 changes: 17 additions & 14 deletions docs/Authorization/GettingStarted.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
:::

Expand Down Expand Up @@ -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+
Expand Down
77 changes: 25 additions & 52 deletions docs/Authorization/Testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Comment thread
finkmanAtSap marked this conversation as resolved.
"pretest": "npx compile-dcl -d auth/dcl -o test/dcn", // [!code ++]
},
"devDependencies": {
"@sap/ams-dev": "^2", // [!code ++]
Expand All @@ -157,66 +157,39 @@ In CAP Node.js projects, this is done automatically by `@sap/ams-dev` before `cd
<!-- srv/pom.xml -->
<build>
<plugins>
<!-- STEPS TO BUILD CDS MODEL AND GENERATE POJOs -->
<plugin>
<groupId>com.sap.cds</groupId>
<artifactId>cds-maven-plugin</artifactId>
<executions>
<!-- ... -->

<!-- DCL -> DCN compilation before tests --> // [!code ++:14]
<execution>
<id>compile-dcl</id>
<goals>
<goal>npx</goal>
</goals>
<phase>generate-test-resources</phase>
<configuration>
<arguments>--package=@sap/ams-dev compile-dcl
-d ${project.basedir}/src/main/resources/ams
-o ${project.basedir}/target/generated-test-sources/dcn
</arguments>
</configuration>
</execution>
</executions>
</plugin>
<!-- Plugin for DCL -> DCN compilation before tests --> <!-- [!code ++:16] -->
<plugin>
<groupId>com.sap.cloud.security.ams.dcl</groupId>
<artifactId>dcl-compiler-plugin</artifactId>
<version>${sap.cloud.security.ams.dcl-compiler.version}</version>
<executions>
<execution>
<goals>
<goal>compile</goal>
</goals>
<configuration>
<sourceDirectory>${project.basedir}/src/main/resources/ams</sourceDirectory>
Comment thread
finkmanAtSap marked this conversation as resolved.
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
```

```xml [Java]
<build>
<plugins>
<!-- ... -->

<!-- Plugin for DCL -> DCN compilation before tests --> // [!code ++:31]
<!-- Plugin for DCL -> DCN compilation before tests --> <!-- [!code ++:13] -->
<plugin>
<groupId>com.github.eirslett</groupId>
<artifactId>frontend-maven-plugin</artifactId>
<version>1.14.1</version>
<groupId>com.sap.cloud.security.ams.dcl</groupId>
<artifactId>dcl-compiler-plugin</artifactId>
<version>${sap.cloud.security.ams.dcl-compiler.version}</version>
<executions>
<execution>
<id>install node and npm</id>
<goals>
<goal>install-node-and-npm</goal>
</goals>
<phase>generate-test-resources</phase>
<configuration>
<nodeVersion>v24.11.0</nodeVersion>
</configuration>
</execution>
<execution>
<id>compile-dcl</id>
<goals>
<goal>npx</goal>
<goal>compile</goal>
</goals>
<phase>generate-test-resources</phase>
<configuration>
<arguments>--package=@sap/ams-dev compile-dcl
-d ${project.basedir}/src/main/resources/dcl
-o ${project.basedir}/target/generated-test-sources/dcn
</arguments>
</configuration>
</execution>
</executions>
</plugin>
Expand Down Expand Up @@ -251,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) {
Expand Down
74 changes: 74 additions & 0 deletions docs/Libraries/java/dcl-compiler-maven-plugin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
<build>
<plugins>
<plugin>
<groupId>com.sap.cloud.security.ams.dcl</groupId>
<artifactId>dcl-compiler-plugin</artifactId>
<version>${sap.cloud.security.ams.dcl-compiler.version}</version>
<executions>
<execution>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
```

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 `<configuration>` or overridden via command line with `-Ddcl.<parameter>`, 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: `<timeout>120000</timeout>`

**Permission denied (Unix)** — The plugin sets executable permissions automatically. If this fails:
```bash
chmod +x ~/.ams-cli/binaries/{version}/{os}-{arch}/ams
```
Loading