Skip to content

feat: Introduce BOMs #462

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
kabir merged 7 commits into from
Nov 18, 2025
Merged

feat: Introduce BOMs #462

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
05de6ec
feat: Introduce BOMs
kabir Nov 17, 2025
530a215
Fix bom build order
kabir Nov 18, 2025
92a0cb7
Test and review fixes
kabir Nov 18, 2025
2dfa6cf
Enhance test, and remove noise from README
kabir Nov 18, 2025
1970cfd
Final review fixes
kabir Nov 18, 2025
ec6576d
Improve project root search
kabir Nov 18, 2025
d854208
Use property rather than hardcoded version
kabir Nov 18, 2025
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
230 changes: 230 additions & 0 deletions boms/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,230 @@
# A2A Java SDK - Bill of Materials (BOM)

This directory contains Bill of Materials (BOM) modules for the A2A Java SDK project, providing dependency management for external users.

## Overview

The A2A Java SDK provides three BOMs for different use cases:

1. **`a2a-java-sdk-bom`** - Core SDK BOM for general A2A agent development
2. **`a2a-java-sdk-extras-bom`** - Extras BOM with server-side enhancements (task stores, queue managers)
3. **`a2a-java-sdk-reference-bom`** - Reference implementations BOM with Quarkus dependencies

## BOM Modules

### SDK BOM (`boms/sdk`)

**Artifact:** `io.github.a2asdk:a2a-java-sdk-bom`

The SDK BOM includes:
- All A2A SDK core modules (spec, server, client, transport)
- Core third-party dependencies (Jackson, gRPC, SLF4J)
- Jakarta APIs (CDI, Inject, JSON, JAX-RS)
- Test utilities

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

### Extras BOM (`boms/extras`)

**Artifact:** `io.github.a2asdk:a2a-java-sdk-extras-bom`

The Extras BOM includes:
- Everything from `a2a-java-sdk-bom` (via import)
- Server-side enhancement modules (database persistence, distributed queue management, etc.)

**Use this BOM when:** Building production A2A servers needing advanced server-side features beyond the core SDK

### Reference BOM (`boms/reference`)

**Artifact:** `io.github.a2asdk:a2a-java-sdk-reference-bom`

The Reference BOM includes:
- Everything from `a2a-java-sdk-bom` (via import)
- Quarkus BOM (complete Quarkus platform)
- A2A reference implementation modules (JSON-RPC, gRPC, REST)
- TCK module for testing

**Use this BOM when:** Building Quarkus-based A2A agents or reference implementations

## Usage

### For SDK Users (Any Framework)

Add to your project's `pom.xml`:

```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-bom</artifactId>
<version>${io.a2a.sdk.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<!-- No version needed - managed by BOM -->
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-server-common</artifactId>
</dependency>
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-transport-jsonrpc</artifactId>
</dependency>
</dependencies>
```

### For Extras Users (Database Persistence, Distributed Deployments)

Add to your project's `pom.xml`:

```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-extras-bom</artifactId>
<version>${io.a2a.sdk.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<!-- No version needed - managed by BOM -->
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-server-common</artifactId>
</dependency>
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-extras-task-store-database-jpa</artifactId>
</dependency>
</dependencies>
```

### For Quarkus Reference Implementation Users

Add to your project's `pom.xml`:

```xml
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-reference-bom</artifactId>
<version>${io.a2a.sdk.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>

<dependencies>
<!-- A2A SDK and Quarkus versions both managed -->
<dependency>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-reference-jsonrpc</artifactId>
</dependency>
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-arc</artifactId>
</dependency>
</dependencies>
```

## Internal Project Usage

**Important:** The A2A Java SDK project itself does **NOT** import these BOMs in the parent `pom.xml`. The BOMs are
for the convenience of external users.

### Maintenance Strategy

- Parent `pom.xml` `<dependencyManagement>` is the **single source of truth** for versions
- BOMs are **maintained to match** parent pom versions
- When updating dependencies, update **both** parent pom and relevant BOMs
- BOMs are separate artifacts for **external consumption only**

## Automated Testing

All three BOMs include **maven-invoker-plugin** integration tests that automatically verify:
- ✅ BOM can be imported correctly
- ✅ All declared dependencies resolve
- ✅ No missing versions or conflicts
- ✅ Code using the BOM compiles successfully

### Test Structure

```
boms/
├── sdk/
│ └── src/it/
│ ├── settings.xml # Test repository config
│ └── sdk-usage-test/ # Integration test project
│ ├── pom.xml # Imports SDK BOM
│ └── src/main/java/ # Test code using SDK
├── extras/
│ └── src/it/
│ └── extras-usage-test/ # Integration test project
│ ├── pom.xml # Imports Extras BOM
│ └── src/main/java/ # Test code using SDK + Extras
└── reference/
└── src/it/
└── reference-usage-test/ # Integration test project
├── pom.xml # Imports Reference BOM
└── src/main/java/ # Test code using Quarkus + SDK
```

### Running Tests

Tests run automatically during `mvn install`:

```bash
# Test all BOMs
mvn clean install -DskipTests -pl boms/sdk,boms/extras,boms/reference

# Test individual BOM
mvn clean install -DskipTests -pl boms/sdk
```

**What happens:**
1. BOM is installed to `target/local-repo/`
2. Test project builds using the BOM
3. If compilation succeeds → BOM is valid ✅
4. If dependencies missing → Build fails ❌

## Maintenance Guidelines

When updating dependencies in the project:

1. **Update parent `pom.xml`** - Change version properties and dependencyManagement
2. **Update SDK BOM** (`boms/sdk/pom.xml`) - Sync core dependency versions
3. **Update Extras BOM** (`boms/extras/pom.xml`) - Sync if extras modules changed
4. **Update Reference BOM** (`boms/reference/pom.xml`) - Sync if Quarkus or reference modules changed
5. **Run automated tests** - Integration tests will catch any missing dependencies:
```bash
mvn clean install -DskipTests -pl boms/sdk,boms/extras,boms/reference
```

### Adding New Dependencies to BOMs

When adding new SDK modules or dependencies:

1. Add to appropriate BOM's `<dependencyManagement>`
2. Add usage example in `src/it/*/src/main/java/` test code
3. Run tests to verify compilation
4. Tests will fail if versions are missing or incorrect

## Version Alignment

The BOMs use `${project.version}` for all A2A SDK modules, ensuring:
- BOMs always reference the correct SDK version
- Version updates only need to change parent pom
- No version drift between BOMs and SDK modules

Maven's reactor automatically orders them correctly based on their `<dependencies>` declarations, regardless of their position in the parent pom's `<modules>` section.
105 changes: 105 additions & 0 deletions boms/extras/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<parent>
<groupId>io.github.a2asdk</groupId>
<artifactId>a2a-java-sdk-parent</artifactId>
<version>0.4.0.Alpha1-SNAPSHOT</version>
<relativePath>../../pom.xml</relativePath>
</parent>

<artifactId>a2a-java-sdk-extras-bom</artifactId>
<packaging>pom</packaging>

<name>A2A Java SDK - Extras BOM</name>
<description>Bill of Materials for A2A SDK Extras modules (task stores, queue managers, etc.)</description>

<dependencyManagement>
<dependencies>
<!-- Import SDK BOM - extras modules build on top of SDK -->
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>a2a-java-sdk-bom</artifactId>
<version>${project.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>

<!-- Extras modules -->
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>a2a-java-extras-common</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>a2a-java-extras-task-store-database-jpa</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>a2a-java-extras-push-notification-config-store-database-jpa</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>a2a-java-queue-manager-replicated-core</artifactId>
<version>${project.version}</version>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>a2a-java-queue-manager-replication-mp-reactive</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
</dependencyManagement>

<!-- Declare actual dependency on SDK BOM so Maven reactor understands build order -->
<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>a2a-java-sdk-bom</artifactId>
<version>${project.version}</version>
<type>pom</type>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-invoker-plugin</artifactId>
<version>3.8.0</version>
<configuration>
<cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
<localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>
<settingsFile>src/it/settings.xml</settingsFile>
<goals>
<goal>clean</goal>
<goal>verify</goal>
</goals>
<streamLogs>false</streamLogs>
<streamLogsOnFailures>true</streamLogsOnFailures>
<invokerPropertiesFile>invoker.properties</invokerPropertiesFile>
<!-- Install test-utils module before running integration tests -->
<extraArtifacts>
<extraArtifact>io.github.a2asdk:a2a-java-bom-test-utils:${project.version}:jar</extraArtifact>
</extraArtifacts>
</configuration>
<executions>
<execution>
<id>integration-test</id>
<goals>
<goal>install</goal>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

</project>
2 changes: 2 additions & 0 deletions boms/extras/src/it/extras-usage-test/invoker.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
invoker.goals=clean verify
invoker.buildResult=success
Loading