Skip to content

Commit b238233

Browse files
finkmanAtSapfinkmanAtSap
authored
New maven DCL compiler plugin (#30)
* document new DCL compiler maven plugin
1 parent cf89918 commit b238233

4 files changed

Lines changed: 117 additions & 66 deletions

File tree

‎docs/.vitepress/config.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ export default defineConfig(withMermaid({
6161
{ text: 'ams-test', link: '/Libraries/java/ams-test' },
6262
{ text: 'cap-ams', link: '/Libraries/java/cap-ams' },
6363
{ text: 'spring-boot-ams', link: '/Libraries/java/spring-boot-ams' },
64+
{ text: 'dcl-compiler-plugin', link: '/Libraries/java/dcl-compiler-maven-plugin' },
6465
{
6566
text: 'Version 3.x',
6667
collapsed: true,

‎docs/Authorization/GettingStarted.md‎

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -44,23 +44,25 @@ language and framework you are using.
4444
4545
## Dependency Setup
4646
47-
::: tip
48-
In CAP applications, the [`cds add ams`](https://cap.cloud.sap/docs/tools/cds-cli#cds-add) command can be executed with
49-
the *latest version* of [`@sap/cds-dk`](https://cap.cloud.sap/docs/tools/cds-cli#cli). It automatically adds the correct
50-
dependencies.
51-
:::
52-
53-
The following tables give an overview of the required AMS module dependencies for different application setups.
47+
The following sections give an overview of the required AMS module dependencies for different application setups.
5448
5549
::: warning
5650
The recommended modules and versions have changed over time (see [Historical Setups](#historical-setups))
5751
58-
**Please begin new projects with the currently recommended modules**.
52+
**Please begin new projects with the latest version of the currently recommended modules**.
53+
:::
54+
#
55+
::: tip
56+
In CAP applications, the [`cds add ams`](https://cap.cloud.sap/docs/tools/cds-cli#cds-add) command can be executed with
57+
the *latest version* of [`@sap/cds-dk`](https://cap.cloud.sap/docs/tools/cds-cli#cli) to add the recommended
58+
dependencies. The generated AMS versions get regularly updated in newer `@sap/cds-dk` releases.
5959
:::
6060

6161
### Java
6262

63-
::: tip
63+
The latest version can always be found on [Maven Central](https://mvnrepository.com/artifact/com.sap.cloud.security.ams/ams-bom).
64+
65+
::: tip Spring Boot Support
6466
The AMS modules support both Spring Boot 3 and 4.
6567
:::
6668

@@ -192,18 +194,19 @@ alternatively `HealthIndicator` beans for Spring Boot Actuator health endpoint i
192194

193195
#### Tooling
194196

197+
::: tip DCL Compiler Maven plugin
198+
The [DCL Compiler Maven plugin](/Libraries/java/dcl-compiler-maven-plugin) allows DCL compilation for local integration [tests](/Authorization/Testing) without AMS cloud instance.
199+
:::
200+
195201
::: tip CDS Build Plugin
196202
In CAP Java projects, the (optional) Node.js module `@sap/ams` *should* be added in the `package.json` as a
197203
*devDependency* with version `^3` to provide dev-time features as [cds build plugin](/CAP/cds-Plugin).
198204
:::
199205

200-
::: tip DCL compiler plugin
201-
In the near future, there will be new maven build plugin for DCL compilation for local integration tests without AMS cloud instance.
202-
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.
203-
:::
204-
205206
### Node.js
206207

208+
The latest versions of the Node.js modules can always be found on [npmjs.org](https://www.npmjs.com/package/@sap/ams).
209+
207210
| Project Type | @sap/ams | @sap/ams-dev | Java JDK |
208211
|-------------------|:--------:|:------------:|:--------:|
209212
| Plain Node.js | ✓ ^3 | (✓)* ^2 | (✓)* 17+

‎docs/Authorization/Testing.md‎

Lines changed: 25 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -145,8 +145,8 @@ In CAP Node.js projects, this is done automatically by `@sap/ams-dev` before `cd
145145
```json [Node.js]
146146
// package.json
147147
"scripts": {
148-
"jest": "NODE_ENV=test npx jest",
149-
"pretest": "npx compile-dcl -d auth/dcl -o test/dcn", // [!code ++]
148+
"test": "NODE_ENV=test npx jest",
149+
"pretest": "npx compile-dcl -d auth/dcl -o test/dcn", // [!code ++]
150150
},
151151
"devDependencies": {
152152
"@sap/ams-dev": "^2", // [!code ++]
@@ -157,66 +157,39 @@ In CAP Node.js projects, this is done automatically by `@sap/ams-dev` before `cd
157157
<!-- srv/pom.xml -->
158158
<build>
159159
<plugins>
160-
<!-- STEPS TO BUILD CDS MODEL AND GENERATE POJOs -->
161-
<plugin>
162-
<groupId>com.sap.cds</groupId>
163-
<artifactId>cds-maven-plugin</artifactId>
164-
<executions>
165-
<!-- ... -->
166-
167-
<!-- DCL -> DCN compilation before tests --> // [!code ++:14]
168-
<execution>
169-
<id>compile-dcl</id>
170-
<goals>
171-
<goal>npx</goal>
172-
</goals>
173-
<phase>generate-test-resources</phase>
174-
<configuration>
175-
<arguments>--package=@sap/ams-dev compile-dcl
176-
-d ${project.basedir}/src/main/resources/ams
177-
-o ${project.basedir}/target/generated-test-sources/dcn
178-
</arguments>
179-
</configuration>
180-
</execution>
181-
</executions>
182-
</plugin>
160+
<!-- Plugin for DCL -> DCN compilation before tests --> <!-- [!code ++:16] -->
161+
<plugin>
162+
<groupId>com.sap.cloud.security.ams.dcl</groupId>
163+
<artifactId>dcl-compiler-plugin</artifactId>
164+
<version>${sap.cloud.security.ams.dcl-compiler.version}</version>
165+
<executions>
166+
<execution>
167+
<goals>
168+
<goal>compile</goal>
169+
</goals>
170+
<configuration>
171+
<sourceDirectory>${project.basedir}/src/main/resources/ams</sourceDirectory>
172+
</configuration>
173+
</execution>
174+
</executions>
175+
</plugin>
183176
</plugins>
184177
</build>
185178
```
186179

187180
```xml [Java]
188181
<build>
189182
<plugins>
190-
<!-- ... -->
191-
192-
<!-- Plugin for DCL -> DCN compilation before tests --> // [!code ++:31]
183+
<!-- Plugin for DCL -> DCN compilation before tests --> <!-- [!code ++:13] -->
193184
<plugin>
194-
<groupId>com.github.eirslett</groupId>
195-
<artifactId>frontend-maven-plugin</artifactId>
196-
<version>1.14.1</version>
185+
<groupId>com.sap.cloud.security.ams.dcl</groupId>
186+
<artifactId>dcl-compiler-plugin</artifactId>
187+
<version>${sap.cloud.security.ams.dcl-compiler.version}</version>
197188
<executions>
198189
<execution>
199-
<id>install node and npm</id>
200-
<goals>
201-
<goal>install-node-and-npm</goal>
202-
</goals>
203-
<phase>generate-test-resources</phase>
204-
<configuration>
205-
<nodeVersion>v24.11.0</nodeVersion>
206-
</configuration>
207-
</execution>
208-
<execution>
209-
<id>compile-dcl</id>
210190
<goals>
211-
<goal>npx</goal>
191+
<goal>compile</goal>
212192
</goals>
213-
<phase>generate-test-resources</phase>
214-
<configuration>
215-
<arguments>--package=@sap/ams-dev compile-dcl
216-
-d ${project.basedir}/src/main/resources/dcl
217-
-o ${project.basedir}/target/generated-test-sources/dcn
218-
</arguments>
219-
</configuration>
220193
</execution>
221194
</executions>
222195
</plugin>
@@ -251,10 +224,10 @@ try {
251224
LocalAuthorizationManagementServiceConfig amsTestConfig =
252225
new LocalAuthorizationManagementServiceConfig()
253226
.withPolicyAssignmentsPath(
254-
Path.of("src", "test", "resources", "mockPolicyAssignments.json"));
227+
Path.of("src/test/resources/mockPolicyAssignments.json"));
255228
ams = AuthorizationManagementServiceFactory
256229
.fromLocalDcn(
257-
Path.of("target", "generated-test-sources", "ams", "dcn"), amsTestConfig);
230+
Path.of("target/generated-test-resources/ams/dcn"), amsTestConfig);
258231

259232
ams.whenReady().get(3, TimeUnit.SECONDS);
260233
} catch (TimeoutException e) {

‎docs/Libraries/java/dcl-compiler-maven-plugin.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# DCL Compiler Maven Plugin
2+
3+
Maven plugin for compiling DCL (Data Control Language) files into DCN (Data Control Notation) format for local
4+
application [testing](/Authorization/Testing).
5+
6+
## Installation
7+
8+
Add the plugin to your `pom.xml` (see also the [Testing guide](/Authorization/Testing#compiling-dcl-to-dcn) for full
9+
integration examples):
10+
11+
```xml
12+
<build>
13+
<plugins>
14+
<plugin>
15+
<groupId>com.sap.cloud.security.ams.dcl</groupId>
16+
<artifactId>dcl-compiler-plugin</artifactId>
17+
<version>${sap.cloud.security.ams.dcl-compiler.version}</version>
18+
<executions>
19+
<execution>
20+
<goals>
21+
<goal>compile</goal>
22+
</goals>
23+
</execution>
24+
</executions>
25+
</plugin>
26+
</plugins>
27+
</build>
28+
```
29+
30+
The latest version can be found on [Maven Central](https://mvnrepository.com/artifact/com.sap.cloud.security.ams.dcl/dcl-compiler-plugin).
31+
32+
## Goals
33+
34+
### `dcl:compile`
35+
36+
Compiles DCL files to DCN format. Bound to the `generate-test-resources` phase by default.
37+
38+
### `dcl:validate`
39+
40+
Validates DCL files without generating output. Bound to the `validate` phase by default. Useful for CI/CD pipelines.
41+
42+
## Configuration
43+
44+
| Parameter | Default | Description |
45+
|-----------|---------|-------------|
46+
| `sourceDirectory` | `.../src/main/resources/ams/dcl` | Directory containing DCL source files |
47+
| `outputDirectory` | `.../generated-test-resources/ams/dcn` | Output directory for compiled DCN files (compile only) |
48+
| `skip` | `false` | Skip plugin execution |
49+
| `verbose` | `false` | Enable verbose output |
50+
| `failOn` | `error` | Failure threshold: `error`, `warning`, or `deprecation` |
51+
| `readDcn` | `false` | Allow reading `.dcn` files as input |
52+
| `timeout` | `60000` | CLI timeout in milliseconds |
53+
| `additionalArguments` | - | Additional CLI arguments |
54+
55+
Parameters can be set in `<configuration>` or overridden via command line with `-Ddcl.<parameter>`, e.g. `mvn compile -Ddcl.verbose=true`.
56+
57+
## Platform-Specific Binaries
58+
59+
The plugin bundles platform-specific AMS CLI binaries for:
60+
- macOS (Intel and Apple Silicon)
61+
- Linux (x86_64 and ARM64)
62+
- Windows (x86_64)
63+
64+
The relevant binaries are automatically extracted and
65+
cached in `~/.ams-cli/binaries/{version}/` on first use.
66+
67+
## Troubleshooting
68+
69+
**Timeout errors** — Increase the timeout for large projects: `<timeout>120000</timeout>`
70+
71+
**Permission denied (Unix)** — The plugin sets executable permissions automatically. If this fails:
72+
```bash
73+
chmod +x ~/.ams-cli/binaries/{version}/{os}-{arch}/ams
74+
```

0 commit comments

Comments
 (0)