Skip to content

Commit 92a0cb7

Browse files
kabirkabir
committed
Test and review fixes
1 parent 530a215 commit 92a0cb7

File tree

6 files changed

+159
-74
lines changed

6 files changed

+159
-74
lines changed

‎boms/README.md‎

Lines changed: 69 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,11 @@ This directory contains Bill of Materials (BOM) modules for the A2A Java SDK pro
44

55
## Overview
66

7-
The A2A Java SDK provides two BOMs for different use cases:
7+
The A2A Java SDK provides three BOMs for different use cases:
88

99
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
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
1112

1213
## BOM Modules
1314

@@ -19,11 +20,20 @@ The SDK BOM includes:
1920
- All A2A SDK core modules (spec, server, client, transport)
2021
- Core third-party dependencies (Jackson, gRPC, SLF4J)
2122
- Jakarta APIs (CDI, Inject, JSON, JAX-RS)
22-
- Extras modules (JPA task store, replicated queue manager)
2323
- Test utilities
2424

2525
**Use this BOM when:** Building A2A agents with any framework (Quarkus, Spring Boot, vanilla Java, etc.)
2626

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+
2737
### Reference BOM (`boms/reference`)
2838

2939
**Artifact:** `io.github.a2asdk:a2a-java-sdk-reference-bom`
@@ -68,6 +78,36 @@ Add to your project's `pom.xml`:
6878
</dependencies>
6979
```
7080

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>0.4.0.Alpha1-SNAPSHOT</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+
71111
### For Quarkus Reference Implementation Users
72112

73113
Add to your project's `pom.xml`:
@@ -120,7 +160,7 @@ Following the WildFly pattern, we keep BOMs separate from internal dependency ma
120160

121161
## Automated Testing
122162

123-
Both BOMs include **maven-invoker-plugin** integration tests that automatically verify:
163+
All three BOMs include **maven-invoker-plugin** integration tests that automatically verify:
124164
- ✅ BOM can be imported correctly
125165
- ✅ All declared dependencies resolve
126166
- ✅ No missing versions or conflicts
@@ -136,6 +176,11 @@ boms/
136176
│ └── sdk-usage-test/ # Integration test project
137177
│ ├── pom.xml # Imports SDK BOM
138178
│ └── src/main/java/ # Test code using SDK
179+
├── extras/
180+
│ └── src/it/
181+
│ └── extras-usage-test/ # Integration test project
182+
│ ├── pom.xml # Imports Extras BOM
183+
│ └── src/main/java/ # Test code using SDK + Extras
139184
└── reference/
140185
└── src/it/
141186
└── reference-usage-test/ # Integration test project
@@ -148,8 +193,8 @@ boms/
148193
Tests run automatically during `mvn install`:
149194

150195
```bash
151-
# Test both BOMs
152-
mvn clean install -DskipTests -pl boms/sdk,boms/reference
196+
# Test all BOMs
197+
mvn clean install -DskipTests -pl boms/sdk,boms/extras,boms/reference
153198

154199
# Test individual BOM
155200
mvn clean install -DskipTests -pl boms/sdk
@@ -167,10 +212,11 @@ When updating dependencies in the project:
167212

168213
1. **Update parent `pom.xml`** - Change version properties and dependencyManagement
169214
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:
215+
3. **Update Extras BOM** (`boms/extras/pom.xml`) - Sync if extras modules changed
216+
4. **Update Reference BOM** (`boms/reference/pom.xml`) - Sync if Quarkus or reference modules changed
217+
5. **Run automated tests** - Integration tests will catch any missing dependencies:
172218
```bash
173-
mvn clean install -DskipTests -pl boms/sdk,boms/reference
219+
mvn clean install -DskipTests -pl boms/sdk,boms/extras,boms/reference
174220
```
175221

176222
### Adding New Dependencies to BOMs
@@ -191,16 +237,12 @@ The BOMs use `${project.version}` for all A2A SDK modules, ensuring:
191237

192238
## Build Order
193239

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-
```
240+
BOMs have explicit dependencies to ensure correct reactor build order:
241+
- **SDK BOM** builds first (no BOM dependencies)
242+
- **Extras BOM** builds second (depends on SDK BOM)
243+
- **Reference BOM** builds third (depends on SDK BOM)
202244

203-
This ensures BOMs are built early, making them available for any future internal use if needed.
245+
Maven's reactor automatically orders them correctly based on their `<dependencies>` declarations, regardless of their position in the parent pom's `<modules>` section.
204246

205247
## Examples
206248

@@ -212,21 +254,25 @@ See the `examples/` directory for sample projects using these BOMs:
212254

213255
When releasing the A2A Java SDK:
214256

215-
1. Both BOMs are released as separate Maven artifacts
257+
1. All three BOMs are released as separate Maven artifacts
216258
2. External users can depend on them via Maven Central
217259
3. BOMs follow the same version scheme as the SDK (e.g., `0.4.0.Alpha1`, `0.4.0`)
218260

219261
## Questions?
220262

221263
- **Which BOM should I use?**
222264
- Quarkus project → Reference BOM
223-
- Other framework → SDK BOM
265+
- Production server with database/distributed features → Extras BOM
266+
- Other framework/basic agent → SDK BOM
267+
268+
- **Can I use Extras BOM with Spring Boot?**
269+
- Yes! Extras BOM imports SDK BOM and adds server enhancements that work with any framework.
224270

225271
- **Can I use Reference BOM with Spring Boot?**
226-
- Yes, but you'll get unnecessary Quarkus dependencies. Use SDK BOM instead.
272+
- Yes, but you'll get unnecessary Quarkus dependencies. Use SDK BOM or Extras BOM instead.
227273

228-
- **Do I need both BOMs?**
229-
- No, choose one. Reference BOM already imports SDK BOM.
274+
- **Do I need multiple BOMs?**
275+
- No, choose one. Extras BOM imports SDK BOM. Reference BOM imports SDK BOM.
230276

231277
- **Why are test dependencies in SDK BOM?**
232278
- Test scope dependencies don't pollute runtime, but allow users to easily import test utilities.

‎boms/extras/src/it/extras-usage-test/src/main/java/io/a2a/test/ExtrasBomVerifier.java‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,13 @@
66

77
/**
88
* Verifies Extras BOM completeness by attempting to load all discovered classes.
9-
* Includes SDK modules + Extras modules (task stores, queue managers, etc.).
10-
* Note: extras/ is NOT excluded - that's what we're testing!
9+
* - Includes SDK modules + Extras modules (task stores, queue managers, etc.)
10+
* - Forbids reference/ to prove BOM doesn't leak reference implementation dependencies
1111
*/
1212
public class ExtrasBomVerifier extends DynamicBomVerifier {
1313

1414
private static final Set<String> EXTRAS_EXCLUSIONS = Set.of(
1515
"boms/", // BOM test modules themselves
16-
"reference/", // Reference implementations (separate BOM)
1716
"examples/", // Example applications
1817
"tck/", // TCK test suite
1918
"tests/", // Integration tests
@@ -22,8 +21,12 @@ public class ExtrasBomVerifier extends DynamicBomVerifier {
2221
// Note: extras/ production modules are NOT in this list - we want to verify those classes load
2322
);
2423

24+
private static final Set<String> EXTRAS_FORBIDDEN = Set.of(
25+
"reference/" // Reference implementations (separate BOM) - must NOT be loadable
26+
);
27+
2528
public ExtrasBomVerifier() {
26-
super(EXTRAS_EXCLUSIONS);
29+
super(EXTRAS_EXCLUSIONS, EXTRAS_FORBIDDEN);
2730
}
2831

2932
public static void main(String[] args) throws Exception {

‎boms/reference/src/it/reference-usage-test/src/main/java/io/a2a/test/ReferenceBomVerifier.java‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,22 +6,25 @@
66

77
/**
88
* Verifies Reference BOM completeness by attempting to load all discovered classes.
9-
* Includes SDK modules + Reference implementation modules.
10-
* Note: reference/ is NOT excluded - that's what we're testing!
9+
* - Includes SDK modules + Reference implementation modules
10+
* - Forbids extras/ to prove BOM doesn't leak extras dependencies
1111
*/
1212
public class ReferenceBomVerifier extends DynamicBomVerifier {
1313

1414
private static final Set<String> REFERENCE_EXCLUSIONS = Set.of(
1515
"boms/", // BOM test modules themselves
1616
"examples/", // Example applications
17-
"extras/", // Extra modules (potential separate BOM)
1817
"tck/", // TCK test suite
1918
"tests/" // Integration tests
2019
// Note: reference/ is NOT in this list - we want to verify those classes load
2120
);
2221

22+
private static final Set<String> REFERENCE_FORBIDDEN = Set.of(
23+
"extras/" // Extras modules (separate BOM) - must NOT be loadable
24+
);
25+
2326
public ReferenceBomVerifier() {
24-
super(REFERENCE_EXCLUSIONS);
27+
super(REFERENCE_EXCLUSIONS, REFERENCE_FORBIDDEN);
2528
}
2629

2730
public static void main(String[] args) throws Exception {

‎boms/sdk/pom.xml‎

Lines changed: 0 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -96,28 +96,6 @@
9696
<version>${project.version}</version>
9797
</dependency>
9898

99-
<!-- Extras modules -->
100-
<dependency>
101-
<groupId>${project.groupId}</groupId>
102-
<artifactId>a2a-java-extras-common</artifactId>
103-
<version>${project.version}</version>
104-
</dependency>
105-
<dependency>
106-
<groupId>${project.groupId}</groupId>
107-
<artifactId>a2a-java-extras-task-store-database-jpa</artifactId>
108-
<version>${project.version}</version>
109-
</dependency>
110-
<dependency>
111-
<groupId>${project.groupId}</groupId>
112-
<artifactId>a2a-java-extras-push-notification-config-store-database-jpa</artifactId>
113-
<version>${project.version}</version>
114-
</dependency>
115-
<dependency>
116-
<groupId>${project.groupId}</groupId>
117-
<artifactId>a2a-java-extras-queue-manager-replicated</artifactId>
118-
<version>${project.version}</version>
119-
</dependency>
120-
12199
<!-- Test utilities -->
122100
<dependency>
123101
<groupId>${project.groupId}</groupId>

‎boms/sdk/src/it/sdk-usage-test/src/main/java/io/a2a/test/SdkBomVerifier.java‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,21 +6,25 @@
66

77
/**
88
* Verifies SDK BOM completeness by attempting to load all discovered classes.
9-
* Excludes paths not part of the SDK BOM scope.
9+
* - Excludes paths not tested at all (boms/, examples/, tck/, tests/)
10+
* - Forbids paths that must NOT be loadable (extras/, reference/) to prove BOM doesn't leak dependencies
1011
*/
1112
public class SdkBomVerifier extends DynamicBomVerifier {
1213

1314
private static final Set<String> SDK_EXCLUSIONS = Set.of(
1415
"boms/", // BOM test modules themselves
15-
"reference/", // Reference implementations (in separate BOM)
1616
"examples/", // Example applications
17-
"extras/", // Extra modules (potential separate BOM)
1817
"tck/", // TCK test suite
1918
"tests/" // Integration tests
2019
);
2120

21+
private static final Set<String> SDK_FORBIDDEN = Set.of(
22+
"extras/", // Extras modules (separate BOM) - must NOT be loadable
23+
"reference/" // Reference implementations (separate BOM) - must NOT be loadable
24+
);
25+
2226
public SdkBomVerifier() {
23-
super(SDK_EXCLUSIONS);
27+
super(SDK_EXCLUSIONS, SDK_FORBIDDEN);
2428
}
2529

2630
public static void main(String[] args) throws Exception {

0 commit comments

Comments
 (0)