0
# gRPC BOM
1

2
The gRPC BOM (Bill of Materials) provides centralized dependency management for all gRPC Java libraries. It uses Gradle's java-platform plugin and Maven's dependency management to ensure version consistency across the entire gRPC Java ecosystem, eliminating version conflicts and simplifying dependency declarations.
3

4
## Package Information
5

6
- **Package Name**: grpc-bom
7
- **Package Type**: maven (Java platform BOM)
8
- **Language**: Java (build configuration)
9
- **Installation**: Import as platform dependency in build configuration
10

11
## Core Imports
12

13
### Maven
14
```xml
15
<dependencyManagement>
16
    <dependencies>
17
        <dependency>
18
            <groupId>io.grpc</groupId>
19
            <artifactId>grpc-bom</artifactId>
20
            <version>1.73.0</version>
21
            <type>pom</type>
22
            <scope>import</scope>
23
        </dependency>
24
    </dependencies>
25
</dependencyManagement>
26
```
27

28
### Gradle (Kotlin DSL)
29
```kotlin
30
dependencies {
31
    implementation(platform("io.grpc:grpc-bom:1.73.0"))
32
}
33
```
34

35
### Gradle (Groovy DSL)
36
```gradle
37
dependencies {
38
    implementation platform('io.grpc:grpc-bom:1.73.0')
39
}
40
```
41

42
## Basic Usage
43

44
After importing the BOM, declare gRPC dependencies without version numbers:
45

46
### Maven
47
```xml
48
<dependencies>
49
    <dependency>
50
        <groupId>io.grpc</groupId>
51
        <artifactId>grpc-netty-shaded</artifactId>
52
    </dependency>
53
    <dependency>
54
        <groupId>io.grpc</groupId>
55
        <artifactId>grpc-protobuf</artifactId>
56
    </dependency>
57
    <dependency>
58
        <groupId>io.grpc</groupId>
59
        <artifactId>grpc-stub</artifactId>
60
    </dependency>
61
</dependencies>
62
```
63

64
### Gradle
65
```kotlin
66
dependencies {
67
    implementation("io.grpc:grpc-netty-shaded")
68
    implementation("io.grpc:grpc-protobuf")
69
    implementation("io.grpc:grpc-stub")
70
}
71
```
72

73
## Architecture
74

75
The gRPC BOM operates as a platform specification that provides:
76

77
- **Version Constraints**: Centralized version management for all gRPC components
78
- **Consistency Guarantees**: Ensures compatible versions across all gRPC dependencies
79
- **Simplified Declarations**: Eliminates need to specify versions for individual gRPC artifacts
80
- **Conflict Resolution**: Prevents version conflicts between different gRPC libraries
81

82
## Capabilities
83

84
### Dependency Management
85

86
The BOM provides version constraints for all published gRPC Java libraries, automatically managing compatibility between components.
87

88
```xml { .api }
89
<!-- Platform BOM import (Maven) -->
90
<dependency>
91
    <groupId>io.grpc</groupId>
92
    <artifactId>grpc-bom</artifactId>
93
    <version>1.73.0</version>
94
    <type>pom</type>
95
    <scope>import</scope>
96
</dependency>
97
```
98

99
```gradle { .api }
100
// Platform BOM import (Gradle)
101
implementation platform('io.grpc:grpc-bom:1.73.0')
102
```
103

104
### Managed Dependencies
105

106
The BOM manages version constraints for exactly **30 gRPC Java modules** plus the protocol compiler plugin. All dependencies are managed at version 1.73.0:
107

108
#### Core Libraries
109
- **grpc-all**: Meta-package containing all common gRPC dependencies
110
- **grpc-api**: Core gRPC API interfaces and contracts
111
- **grpc-core**: Core gRPC implementation with client and server functionality
112
- **grpc-context**: Context propagation utilities for request scoping
113
- **grpc-stub**: Client and server stub generation support
114

115
#### Transport Implementations
116
- **grpc-netty**: Netty-based transport implementation
117
- **grpc-netty-shaded**: Shaded Netty transport preventing dependency conflicts
118
- **grpc-okhttp**: OkHttp-based transport implementation for mobile/constrained environments
119
- **grpc-inprocess**: In-process transport for testing and microservice communication
120

121
#### Protocol and Serialization
122
- **grpc-protobuf**: Protocol Buffers message serialization support
123
- **grpc-protobuf-lite**: Lightweight Protocol Buffers support for mobile
124
- **grpc-googleapis**: Google API support libraries and common protocols
125

126
#### Authentication and Security
127
- **grpc-auth**: Authentication support with OAuth2 and JWT integration
128
- **grpc-alts**: Application Layer Transport Security for Google Cloud
129
- **grpc-s2a**: Secure Service-to-Service Authentication
130

131
#### Service Discovery and Load Balancing
132
- **grpc-xds**: xDS-based service discovery and load balancing
133
- **grpc-grpclb**: gRPC load balancer support
134
- **grpc-rls**: Rate Limiting Service support
135

136
#### Observability and Monitoring
137
- **grpc-census**: Census-based monitoring (deprecated, use OpenTelemetry)
138
- **grpc-opentelemetry**: OpenTelemetry integration for tracing and metrics
139
- **grpc-context-override-opentelemetry**: OpenTelemetry context override utilities
140
- **grpc-gcp-observability**: Google Cloud Platform observability integration
141
- **grpc-gcp-csm-observability**: GCP Client Side Monitoring
142

143
#### Testing and Development
144
- **grpc-testing**: Testing utilities and helpers for unit and integration tests
145
- **grpc-testing-proto**: Protocol definitions for interoperability testing
146
- **grpc-interop-testing**: Interoperability testing support
147
- **grpc-benchmarks**: Performance benchmarking tools and utilities
148

149
#### Extended Functionality
150
- **grpc-services**: Additional gRPC services (health checking, reflection, channelz)
151
- **grpc-servlet**: Java Servlet container integration
152
- **grpc-servlet-jakarta**: Jakarta EE servlet integration
153
- **grpc-util**: Utility classes and helper functions
154

155
#### Code Generation
156
- **protoc-gen-grpc-java**: Protocol compiler plugin for Java code generation (POM-type dependency)
157

158
### Version Consistency
159

160
```java { .api }
161
/**
162
 * All managed dependencies inherit the BOM version (1.73.0)
163
 * ensuring compatibility across the entire gRPC ecosystem.
164
 * No explicit version numbers needed in dependency declarations.
165
 */
166
```
167

168
## Implementation Details
169

170
### Build Configuration
171

172
The BOM is implemented using Gradle's `java-platform` plugin with automatic module discovery:
173

174
```gradle { .api }
175
plugins {
176
    id 'java-platform'
177
    id 'maven-publish'
178
}
179

180
// Automatically includes all publishable gRPC subprojects as constraints
181
gradle.projectsEvaluated {
182
    def projectsToInclude = rootProject.subprojects.findAll {
183
        return it.name != 'grpc-compiler'  // Explicitly excluded
184
            && it.plugins.hasPlugin('java')
185
            && it.plugins.hasPlugin('maven-publish')
186
            && it.tasks.findByName('publishMavenPublicationToMavenRepository')?.enabled
187
    }
188
    dependencies {
189
        constraints {
190
            projectsToInclude.each { api it }
191
        }
192
    }
193
}
194

195
// Manually add protoc-gen-grpc-java as POM-type dependency
196
publishing {
197
    publications {
198
        maven(MavenPublication) {
199
            from components.javaPlatform
200
            pom {
201
                withXml {
202
                    def dependencyManagement = asNode().dependencyManagement[0]
203
                    def dependencies = dependencyManagement.dependencies[0]
204
                    dependencies.appendNode('dependency').with {
205
                        appendNode('groupId', 'io.grpc')
206
                        appendNode('artifactId', 'protoc-gen-grpc-java')
207
                        appendNode('version', version)
208
                        appendNode('type', 'pom')
209
                    }
210
                }
211
            }
212
        }
213
    }
214
}
215
```
216

217
### Platform Compatibility
218

219
- **Java Versions**: Compatible with all Java versions supported by individual gRPC components (Java 8+)
220
- **Build Tools**: Maven 3.x+, Gradle 6.x+
221
- **Artifact Type**: Java platform BOM (uses `<type>pom</type>` in Maven, `java-platform` in Gradle)
222
- **Publishing**: Published to Maven Central as a platform artifact
223

224
### Usage Patterns
225

226
**Standard gRPC Application:**
227
```gradle
228
dependencies {
229
    implementation platform('io.grpc:grpc-bom:1.73.0')
230
    implementation 'io.grpc:grpc-netty-shaded'
231
    implementation 'io.grpc:grpc-protobuf'
232
    implementation 'io.grpc:grpc-stub'
233
}
234
```
235

236
**Testing with gRPC:**
237
```gradle
238
dependencies {
239
    implementation platform('io.grpc:grpc-bom:1.73.0')
240
    implementation 'io.grpc:grpc-netty-shaded'
241
    testImplementation 'io.grpc:grpc-testing'
242
    testImplementation 'io.grpc:grpc-inprocess'
243
}
244
```
245

246
**Full-featured gRPC Service:**
247
```gradle
248
dependencies {
249
    implementation platform('io.grpc:grpc-bom:1.73.0')
250
    implementation 'io.grpc:grpc-netty-shaded'
251
    implementation 'io.grpc:grpc-protobuf'
252
    implementation 'io.grpc:grpc-stub'
253
    implementation 'io.grpc:grpc-services'
254
    implementation 'io.grpc:grpc-auth'
255
    implementation 'io.grpc:grpc-opentelemetry'
256
}
257
```