Skip to content

Commit 05de6ec

Browse files
kabirkabir
committed
feat: Introduce BOMs
There are boms for: * the core sdk classes * the reference classes (includes core sdk) * the extras classes (includes core sdk)
1 parent 4c71032 commit 05de6ec

File tree

19 files changed

+1522
-0
lines changed

19 files changed

+1522
-0
lines changed

‎boms/README.md‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
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 two 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-reference-bom`** - Reference implementations BOM with Quarkus dependencies
11+
12+
## BOM Modules
13+
14+
### SDK BOM (`boms/sdk`)
15+
16+
**Artifact:** `io.github.a2asdk:a2a-java-sdk-bom`
17+
18+
The SDK BOM includes:
19+
- All A2A SDK core modules (spec, server, client, transport)
20+
- Core third-party dependencies (Jackson, gRPC, SLF4J)
21+
- Jakarta APIs (CDI, Inject, JSON, JAX-RS)
22+
- Extras modules (JPA task store, replicated queue manager)
23+
- Test utilities
24+
25+
**Use this BOM when:** Building A2A agents with any framework (Quarkus, Spring Boot, vanilla Java, etc.)
26+
27+
### Reference BOM (`boms/reference`)
28+
29+
**Artifact:** `io.github.a2asdk:a2a-java-sdk-reference-bom`
30+
31+
The Reference BOM includes:
32+
- Everything from `a2a-java-sdk-bom` (via import)
33+
- Quarkus BOM (complete Quarkus platform)
34+
- A2A reference implementation modules (JSON-RPC, gRPC, REST)
35+
- TCK module for testing
36+
37+
**Use this BOM when:** Building Quarkus-based A2A agents or reference implementations
38+
39+
## Usage
40+
41+
### For SDK Users (Any Framework)
42+
43+
Add to your project's `pom.xml`:
44+
45+
```xml
46+
<dependencyManagement>
47+
<dependencies>
48+
<dependency>
49+
<groupId>io.github.a2asdk</groupId>
50+
<artifactId>a2a-java-sdk-bom</artifactId>
51+
<version>0.4.0.Alpha1-SNAPSHOT</version>
52+
<type>pom</type>
53+
<scope>import</scope>
54+
</dependency>
55+
</dependencies>
56+
</dependencyManagement>
57+
58+
<dependencies>
59+
<!-- No version needed - managed by BOM -->
60+
<dependency>
61+
<groupId>io.github.a2asdk</groupId>
62+
<artifactId>a2a-java-sdk-server-common</artifactId>
63+
</dependency>
64+
<dependency>
65+
<groupId>io.github.a2asdk</groupId>
66+
<artifactId>a2a-java-sdk-transport-jsonrpc</artifactId>
67+
</dependency>
68+
</dependencies>
69+
```
70+
71+
### For Quarkus Reference Implementation Users
72+
73+
Add to your project's `pom.xml`:
74+
75+
```xml
76+
<dependencyManagement>
77+
<dependencies>
78+
<dependency>
79+
<groupId>io.github.a2asdk</groupId>
80+
<artifactId>a2a-java-sdk-reference-bom</artifactId>
81+
<version>0.4.0.Alpha1-SNAPSHOT</version>
82+
<type>pom</type>
83+
<scope>import</scope>
84+
</dependency>
85+
</dependencies>
86+
</dependencyManagement>
87+
88+
<dependencies>
89+
<!-- A2A SDK and Quarkus versions both managed -->
90+
<dependency>
91+
<groupId>io.github.a2asdk</groupId>
92+
<artifactId>a2a-java-sdk-reference-jsonrpc</artifactId>
93+
</dependency>
94+
<dependency>
95+
<groupId>io.quarkus</groupId>
96+
<artifactId>quarkus-arc</artifactId>
97+
</dependency>
98+
</dependencies>
99+
```
100+
101+
## Internal Project Usage
102+
103+
**Important:** The A2A Java SDK project itself does **NOT** import these BOMs in the parent `pom.xml`.
104+
105+
### Why Not Use BOMs Internally?
106+
107+
Following the WildFly pattern, we keep BOMs separate from internal dependency management for several reasons:
108+
109+
1. **Build Order Complexity**: BOMs must be built before other modules, adding reactor ordering constraints
110+
2. **Flexibility**: Parent pom may need different scopes/configurations than external users
111+
3. **Simplicity**: Avoids potential circular dependencies and build complexity
112+
4. **Single Source of Truth**: Parent `pom.xml` remains authoritative for internal builds
113+
114+
### Maintenance Strategy
115+
116+
- Parent `pom.xml` `<dependencyManagement>` is the **single source of truth** for versions
117+
- BOMs are **maintained to match** parent pom versions
118+
- When updating dependencies, update **both** parent pom and relevant BOMs
119+
- BOMs are separate artifacts for **external consumption only**
120+
121+
## Automated Testing
122+
123+
Both BOMs include **maven-invoker-plugin** integration tests that automatically verify:
124+
- ✅ BOM can be imported correctly
125+
- ✅ All declared dependencies resolve
126+
- ✅ No missing versions or conflicts
127+
- ✅ Code using the BOM compiles successfully
128+
129+
### Test Structure
130+
131+
```
132+
boms/
133+
├── sdk/
134+
│ └── src/it/
135+
│ ├── settings.xml # Test repository config
136+
│ └── sdk-usage-test/ # Integration test project
137+
│ ├── pom.xml # Imports SDK BOM
138+
│ └── src/main/java/ # Test code using SDK
139+
└── reference/
140+
└── src/it/
141+
└── reference-usage-test/ # Integration test project
142+
├── pom.xml # Imports Reference BOM
143+
└── src/main/java/ # Test code using Quarkus + SDK
144+
```
145+
146+
### Running Tests
147+
148+
Tests run automatically during `mvn install`:
149+
150+
```bash
151+
# Test both BOMs
152+
mvn clean install -DskipTests -pl boms/sdk,boms/reference
153+
154+
# Test individual BOM
155+
mvn clean install -DskipTests -pl boms/sdk
156+
```
157+
158+
**What happens:**
159+
1. BOM is installed to `target/local-repo/`
160+
2. Test project builds using the BOM
161+
3. If compilation succeeds → BOM is valid ✅
162+
4. If dependencies missing → Build fails ❌
163+
164+
## Maintenance Guidelines
165+
166+
When updating dependencies in the project:
167+
168+
1. **Update parent `pom.xml`** - Change version properties and dependencyManagement
169+
2. **Update SDK BOM** (`boms/sdk/pom.xml`) - Sync core dependency versions
170+
3. **Update Reference BOM** (`boms/reference/pom.xml`) - Sync if Quarkus or reference modules changed
171+
4. **Run automated tests** - Integration tests will catch any missing dependencies:
172+
```bash
173+
mvn clean install -DskipTests -pl boms/sdk,boms/reference
174+
```
175+
176+
### Adding New Dependencies to BOMs
177+
178+
When adding new SDK modules or dependencies:
179+
180+
1. Add to appropriate BOM's `<dependencyManagement>`
181+
2. Add usage example in `src/it/*/src/main/java/` test code
182+
3. Run tests to verify compilation
183+
4. Tests will fail if versions are missing or incorrect
184+
185+
## Version Alignment
186+
187+
The BOMs use `${project.version}` for all A2A SDK modules, ensuring:
188+
- BOMs always reference the correct SDK version
189+
- Version updates only need to change parent pom
190+
- No version drift between BOMs and SDK modules
191+
192+
## Build Order
193+
194+
BOMs are listed first in the parent pom's `<modules>` section:
195+
```xml
196+
<modules>
197+
<module>boms/sdk</module>
198+
<module>boms/reference</module>
199+
<!-- ... other modules ... -->
200+
</modules>
201+
```
202+
203+
This ensures BOMs are built early, making them available for any future internal use if needed.
204+
205+
## Examples
206+
207+
See the `examples/` directory for sample projects using these BOMs:
208+
- `examples/helloworld/` - Basic agent using SDK BOM
209+
- `examples/cloud-deployment/` - Quarkus-based agent using Reference BOM
210+
211+
## Release Process
212+
213+
When releasing the A2A Java SDK:
214+
215+
1. Both BOMs are released as separate Maven artifacts
216+
2. External users can depend on them via Maven Central
217+
3. BOMs follow the same version scheme as the SDK (e.g., `0.4.0.Alpha1`, `0.4.0`)
218+
219+
## Questions?
220+
221+
- **Which BOM should I use?**
222+
- Quarkus project → Reference BOM
223+
- Other framework → SDK BOM
224+
225+
- **Can I use Reference BOM with Spring Boot?**
226+
- Yes, but you'll get unnecessary Quarkus dependencies. Use SDK BOM instead.
227+
228+
- **Do I need both BOMs?**
229+
- No, choose one. Reference BOM already imports SDK BOM.
230+
231+
- **Why are test dependencies in SDK BOM?**
232+
- Test scope dependencies don't pollute runtime, but allow users to easily import test utilities.

‎boms/extras/pom.xml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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+
<build>
61+
<plugins>
62+
<plugin>
63+
<groupId>org.apache.maven.plugins</groupId>
64+
<artifactId>maven-invoker-plugin</artifactId>
65+
<version>3.8.0</version>
66+
<configuration>
67+
<cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
68+
<localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>
69+
<settingsFile>src/it/settings.xml</settingsFile>
70+
<goals>
71+
<goal>clean</goal>
72+
<goal>verify</goal>
73+
</goals>
74+
<streamLogs>false</streamLogs>
75+
<streamLogsOnFailures>true</streamLogsOnFailures>
76+
<invokerPropertiesFile>invoker.properties</invokerPropertiesFile>
77+
<!-- Install test-utils module before running integration tests -->
78+
<extraArtifacts>
79+
<extraArtifact>io.github.a2asdk:a2a-java-bom-test-utils:${project.version}:jar</extraArtifact>
80+
</extraArtifacts>
81+
</configuration>
82+
<executions>
83+
<execution>
84+
<id>integration-test</id>
85+
<goals>
86+
<goal>install</goal>
87+
<goal>run</goal>
88+
</goals>
89+
</execution>
90+
</executions>
91+
</plugin>
92+
</plugins>
93+
</build>
94+
95+
</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)