Skip to content

Commit 22f5b1d

Browse files
kabirkabir
authored
feat: Introduce BOMs (a2aproject#462)
There are boms for: * the core sdk classes * the reference classes (includes core sdk) * the extras classes (includes core sdk) Fixes a2aproject#461
1 parent 937290a commit 22f5b1d

File tree

19 files changed

+1607
-0
lines changed

19 files changed

+1607
-0
lines changed

‎boms/README.md‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# A2A Java SDK - Bill of Materials (BOM)
2+
3+
This directory contains Bill of Materials (BOM) modules for the A2A Java SDK project, providing dependency management for external users.
4+
5+
## Overview
6+
7+
The A2A Java SDK provides three BOMs for different use cases:
8+
9+
1. **`a2a-java-sdk-bom`** - Core SDK BOM for general A2A agent development
10+
2. **`a2a-java-sdk-extras-bom`** - Extras BOM with server-side enhancements (task stores, queue managers)
11+
3. **`a2a-java-sdk-reference-bom`** - Reference implementations BOM with Quarkus dependencies
12+
13+
## BOM Modules
14+
15+
### SDK BOM (`boms/sdk`)
16+
17+
**Artifact:** `io.github.a2asdk:a2a-java-sdk-bom`
18+
19+
The SDK BOM includes:
20+
- All A2A SDK core modules (spec, server, client, transport)
21+
- Core third-party dependencies (Jackson, gRPC, SLF4J)
22+
- Jakarta APIs (CDI, Inject, JSON, JAX-RS)
23+
- Test utilities
24+
25+
**Use this BOM when:** Building A2A agents with any framework (Quarkus, Spring Boot, vanilla Java, etc.)
26+
27+
### Extras BOM (`boms/extras`)
28+
29+
**Artifact:** `io.github.a2asdk:a2a-java-sdk-extras-bom`
30+
31+
The Extras BOM includes:
32+
- Everything from `a2a-java-sdk-bom` (via import)
33+
- Server-side enhancement modules (database persistence, distributed queue management, etc.)
34+
35+
**Use this BOM when:** Building production A2A servers needing advanced server-side features beyond the core SDK
36+
37+
### Reference BOM (`boms/reference`)
38+
39+
**Artifact:** `io.github.a2asdk:a2a-java-sdk-reference-bom`
40+
41+
The Reference BOM includes:
42+
- Everything from `a2a-java-sdk-bom` (via import)
43+
- Quarkus BOM (complete Quarkus platform)
44+
- A2A reference implementation modules (JSON-RPC, gRPC, REST)
45+
- TCK module for testing
46+
47+
**Use this BOM when:** Building Quarkus-based A2A agents or reference implementations
48+
49+
## Usage
50+
51+
### For SDK Users (Any Framework)
52+
53+
Add to your project's `pom.xml`:
54+
55+
```xml
56+
<dependencyManagement>
57+
<dependencies>
58+
<dependency>
59+
<groupId>io.github.a2asdk</groupId>
60+
<artifactId>a2a-java-sdk-bom</artifactId>
61+
<version>${io.a2a.sdk.version}</version>
62+
<type>pom</type>
63+
<scope>import</scope>
64+
</dependency>
65+
</dependencies>
66+
</dependencyManagement>
67+
68+
<dependencies>
69+
<!-- No version needed - managed by BOM -->
70+
<dependency>
71+
<groupId>io.github.a2asdk</groupId>
72+
<artifactId>a2a-java-sdk-server-common</artifactId>
73+
</dependency>
74+
<dependency>
75+
<groupId>io.github.a2asdk</groupId>
76+
<artifactId>a2a-java-sdk-transport-jsonrpc</artifactId>
77+
</dependency>
78+
</dependencies>
79+
```
80+
81+
### For Extras Users (Database Persistence, Distributed Deployments)
82+
83+
Add to your project's `pom.xml`:
84+
85+
```xml
86+
<dependencyManagement>
87+
<dependencies>
88+
<dependency>
89+
<groupId>io.github.a2asdk</groupId>
90+
<artifactId>a2a-java-sdk-extras-bom</artifactId>
91+
<version>${io.a2a.sdk.version}</version>
92+
<type>pom</type>
93+
<scope>import</scope>
94+
</dependency>
95+
</dependencies>
96+
</dependencyManagement>
97+
98+
<dependencies>
99+
<!-- No version needed - managed by BOM -->
100+
<dependency>
101+
<groupId>io.github.a2asdk</groupId>
102+
<artifactId>a2a-java-sdk-server-common</artifactId>
103+
</dependency>
104+
<dependency>
105+
<groupId>io.github.a2asdk</groupId>
106+
<artifactId>a2a-java-extras-task-store-database-jpa</artifactId>
107+
</dependency>
108+
</dependencies>
109+
```
110+
111+
### For Quarkus Reference Implementation Users
112+
113+
Add to your project's `pom.xml`:
114+
115+
```xml
116+
<dependencyManagement>
117+
<dependencies>
118+
<dependency>
119+
<groupId>io.github.a2asdk</groupId>
120+
<artifactId>a2a-java-sdk-reference-bom</artifactId>
121+
<version>${io.a2a.sdk.version}</version>
122+
<type>pom</type>
123+
<scope>import</scope>
124+
</dependency>
125+
</dependencies>
126+
</dependencyManagement>
127+
128+
<dependencies>
129+
<!-- A2A SDK and Quarkus versions both managed -->
130+
<dependency>
131+
<groupId>io.github.a2asdk</groupId>
132+
<artifactId>a2a-java-sdk-reference-jsonrpc</artifactId>
133+
</dependency>
134+
<dependency>
135+
<groupId>io.quarkus</groupId>
136+
<artifactId>quarkus-arc</artifactId>
137+
</dependency>
138+
</dependencies>
139+
```
140+
141+
## Internal Project Usage
142+
143+
**Important:** The A2A Java SDK project itself does **NOT** import these BOMs in the parent `pom.xml`. The BOMs are
144+
for the convenience of external users.
145+
146+
### Maintenance Strategy
147+
148+
- Parent `pom.xml` `<dependencyManagement>` is the **single source of truth** for versions
149+
- BOMs are **maintained to match** parent pom versions
150+
- When updating dependencies, update **both** parent pom and relevant BOMs
151+
- BOMs are separate artifacts for **external consumption only**
152+
153+
## Automated Testing
154+
155+
All three BOMs include **maven-invoker-plugin** integration tests that automatically verify:
156+
- ✅ BOM can be imported correctly
157+
- ✅ All declared dependencies resolve
158+
- ✅ No missing versions or conflicts
159+
- ✅ Code using the BOM compiles successfully
160+
161+
### Test Structure
162+
163+
```
164+
boms/
165+
├── sdk/
166+
│ └── src/it/
167+
│ ├── settings.xml # Test repository config
168+
│ └── sdk-usage-test/ # Integration test project
169+
│ ├── pom.xml # Imports SDK BOM
170+
│ └── src/main/java/ # Test code using SDK
171+
├── extras/
172+
│ └── src/it/
173+
│ └── extras-usage-test/ # Integration test project
174+
│ ├── pom.xml # Imports Extras BOM
175+
│ └── src/main/java/ # Test code using SDK + Extras
176+
└── reference/
177+
└── src/it/
178+
└── reference-usage-test/ # Integration test project
179+
├── pom.xml # Imports Reference BOM
180+
└── src/main/java/ # Test code using Quarkus + SDK
181+
```
182+
183+
### Running Tests
184+
185+
Tests run automatically during `mvn install`:
186+
187+
```bash
188+
# Test all BOMs
189+
mvn clean install -DskipTests -pl boms/sdk,boms/extras,boms/reference
190+
191+
# Test individual BOM
192+
mvn clean install -DskipTests -pl boms/sdk
193+
```
194+
195+
**What happens:**
196+
1. BOM is installed to `target/local-repo/`
197+
2. Test project builds using the BOM
198+
3. If compilation succeeds → BOM is valid ✅
199+
4. If dependencies missing → Build fails ❌
200+
201+
## Maintenance Guidelines
202+
203+
When updating dependencies in the project:
204+
205+
1. **Update parent `pom.xml`** - Change version properties and dependencyManagement
206+
2. **Update SDK BOM** (`boms/sdk/pom.xml`) - Sync core dependency versions
207+
3. **Update Extras BOM** (`boms/extras/pom.xml`) - Sync if extras modules changed
208+
4. **Update Reference BOM** (`boms/reference/pom.xml`) - Sync if Quarkus or reference modules changed
209+
5. **Run automated tests** - Integration tests will catch any missing dependencies:
210+
```bash
211+
mvn clean install -DskipTests -pl boms/sdk,boms/extras,boms/reference
212+
```
213+
214+
### Adding New Dependencies to BOMs
215+
216+
When adding new SDK modules or dependencies:
217+
218+
1. Add to appropriate BOM's `<dependencyManagement>`
219+
2. Add usage example in `src/it/*/src/main/java/` test code
220+
3. Run tests to verify compilation
221+
4. Tests will fail if versions are missing or incorrect
222+
223+
## Version Alignment
224+
225+
The BOMs use `${project.version}` for all A2A SDK modules, ensuring:
226+
- BOMs always reference the correct SDK version
227+
- Version updates only need to change parent pom
228+
- No version drift between BOMs and SDK modules
229+
230+
Maven's reactor automatically orders them correctly based on their `<dependencies>` declarations, regardless of their position in the parent pom's `<modules>` section.

‎boms/extras/pom.xml‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0"
3+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4+
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5+
<modelVersion>4.0.0</modelVersion>
6+
7+
<parent>
8+
<groupId>io.github.a2asdk</groupId>
9+
<artifactId>a2a-java-sdk-parent</artifactId>
10+
<version>0.4.0.Alpha1-SNAPSHOT</version>
11+
<relativePath>../../pom.xml</relativePath>
12+
</parent>
13+
14+
<artifactId>a2a-java-sdk-extras-bom</artifactId>
15+
<packaging>pom</packaging>
16+
17+
<name>A2A Java SDK - Extras BOM</name>
18+
<description>Bill of Materials for A2A SDK Extras modules (task stores, queue managers, etc.)</description>
19+
20+
<dependencyManagement>
21+
<dependencies>
22+
<!-- Import SDK BOM - extras modules build on top of SDK -->
23+
<dependency>
24+
<groupId>${project.groupId}</groupId>
25+
<artifactId>a2a-java-sdk-bom</artifactId>
26+
<version>${project.version}</version>
27+
<type>pom</type>
28+
<scope>import</scope>
29+
</dependency>
30+
31+
<!-- Extras modules -->
32+
<dependency>
33+
<groupId>${project.groupId}</groupId>
34+
<artifactId>a2a-java-extras-common</artifactId>
35+
<version>${project.version}</version>
36+
</dependency>
37+
<dependency>
38+
<groupId>${project.groupId}</groupId>
39+
<artifactId>a2a-java-extras-task-store-database-jpa</artifactId>
40+
<version>${project.version}</version>
41+
</dependency>
42+
<dependency>
43+
<groupId>${project.groupId}</groupId>
44+
<artifactId>a2a-java-extras-push-notification-config-store-database-jpa</artifactId>
45+
<version>${project.version}</version>
46+
</dependency>
47+
<dependency>
48+
<groupId>${project.groupId}</groupId>
49+
<artifactId>a2a-java-queue-manager-replicated-core</artifactId>
50+
<version>${project.version}</version>
51+
</dependency>
52+
<dependency>
53+
<groupId>${project.groupId}</groupId>
54+
<artifactId>a2a-java-queue-manager-replication-mp-reactive</artifactId>
55+
<version>${project.version}</version>
56+
</dependency>
57+
</dependencies>
58+
</dependencyManagement>
59+
60+
<!-- Declare actual dependency on SDK BOM so Maven reactor understands build order -->
61+
<dependencies>
62+
<dependency>
63+
<groupId>${project.groupId}</groupId>
64+
<artifactId>a2a-java-sdk-bom</artifactId>
65+
<version>${project.version}</version>
66+
<type>pom</type>
67+
</dependency>
68+
</dependencies>
69+
70+
<build>
71+
<plugins>
72+
<plugin>
73+
<groupId>org.apache.maven.plugins</groupId>
74+
<artifactId>maven-invoker-plugin</artifactId>
75+
<version>3.8.0</version>
76+
<configuration>
77+
<cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
78+
<localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>
79+
<settingsFile>src/it/settings.xml</settingsFile>
80+
<goals>
81+
<goal>clean</goal>
82+
<goal>verify</goal>
83+
</goals>
84+
<streamLogs>false</streamLogs>
85+
<streamLogsOnFailures>true</streamLogsOnFailures>
86+
<invokerPropertiesFile>invoker.properties</invokerPropertiesFile>
87+
<!-- Install test-utils module before running integration tests -->
88+
<extraArtifacts>
89+
<extraArtifact>io.github.a2asdk:a2a-java-bom-test-utils:${project.version}:jar</extraArtifact>
90+
</extraArtifacts>
91+
</configuration>
92+
<executions>
93+
<execution>
94+
<id>integration-test</id>
95+
<goals>
96+
<goal>install</goal>
97+
<goal>run</goal>
98+
</goals>
99+
</execution>
100+
</executions>
101+
</plugin>
102+
</plugins>
103+
</build>
104+
105+
</project>

‎boms/extras/src/it/extras-usage-test/invoker.properties‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
invoker.goals=clean verify
2+
invoker.buildResult=success

0 commit comments

Comments
 (0)