0
# gRPC Util
1

2
gRPC Util provides advanced utilities for the gRPC Java library, including sophisticated load balancing implementations, TLS certificate management with automatic reloading, forwarding utilities for extending gRPC functionality, and server utilities for flexible service handling. These utilities are designed for developers who need more control over gRPC behavior beyond the basic core features.
3

4
## Package Information
5

6
- **Package Name**: io.grpc:grpc-util
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Add to Maven: `<dependency><groupId>io.grpc</groupId><artifactId>grpc-util</artifactId><version>1.73.0</version></dependency>`
10
- **Installation**: Add to Gradle: `implementation 'io.grpc:grpc-util:1.73.0'`
11

12
## Core Imports
13

14
```java
15
import io.grpc.util.GracefulSwitchLoadBalancer;
16
import io.grpc.util.AdvancedTlsX509TrustManager;
17
import io.grpc.util.AdvancedTlsX509KeyManager;
18
import io.grpc.util.MutableHandlerRegistry;
19
import io.grpc.util.CertificateUtils;
20
```
21

22
## Basic Usage
23

24
```java
25
import io.grpc.util.AdvancedTlsX509TrustManager;
26
import io.grpc.util.MutableHandlerRegistry;
27
import io.grpc.ServerServiceDefinition;
28

29
// Advanced TLS trust manager with system defaults
30
AdvancedTlsX509TrustManager trustManager = AdvancedTlsX509TrustManager.newBuilder()
31
    .setVerification(AdvancedTlsX509TrustManager.Verification.CERTIFICATE_AND_HOST_NAME_VERIFICATION)
32
    .build();
33
trustManager.useSystemDefaultTrustCerts();
34

35
// Mutable service registry for dynamic service management
36
MutableHandlerRegistry registry = new MutableHandlerRegistry();
37
ServerServiceDefinition service = MyServiceGrpc.bindService(new MyServiceImpl());
38
registry.addService(service);
39
```
40

41
## Architecture
42

43
gRPC Util is organized around several key components:
44

45
- **Load Balancing System**: Advanced load balancers with graceful switching, outlier detection, and multi-child management
46
- **TLS Management**: Certificate and key managers with automatic reloading and custom verification
47
- **Forwarding Framework**: Decorator pattern implementations for extending core gRPC components
48
- **Server Utilities**: Flexible service registry and status exception handling
49
- **Security Features**: Advanced certificate handling with periodic reloading and custom verification
50

51
## Capabilities
52

53
### TLS and Certificate Management
54

55
Advanced TLS certificate and key management with automatic reloading, custom verification, and flexible trust store configuration.
56

57
```java { .api }
58
public final class AdvancedTlsX509TrustManager extends X509ExtendedTrustManager {
59
  public static Builder newBuilder();
60
  public void useSystemDefaultTrustCerts() throws CertificateException, KeyStoreException, NoSuchAlgorithmException;
61
  public void updateTrustCredentials(X509Certificate[] trustCerts) throws IOException, GeneralSecurityException;
62
  public Closeable updateTrustCredentials(File trustCertFile, long period, TimeUnit unit, ScheduledExecutorService executor) throws IOException, GeneralSecurityException;
63
}
64

65
public final class AdvancedTlsX509KeyManager extends X509ExtendedKeyManager {
66
  public AdvancedTlsX509KeyManager();
67
  public void updateIdentityCredentials(X509Certificate[] certs, PrivateKey key) throws IOException, GeneralSecurityException;
68
  public Closeable updateIdentityCredentials(File certFile, File keyFile, long period, TimeUnit unit, ScheduledExecutorService executor) throws IOException, GeneralSecurityException;
69
}
70

71
public final class CertificateUtils {
72
  public static X509Certificate[] getX509Certificates(InputStream inputStream) throws IOException, GeneralSecurityException;
73
  public static PrivateKey getPrivateKey(InputStream inputStream) throws IOException, GeneralSecurityException;
74
}
75
```
76

77
[TLS and Certificate Management](./tls-management.md)
78

79
### Load Balancing
80

81
Advanced load balancing implementations including graceful policy switching, outlier detection, and multi-child load balancer patterns.
82

83
```java { .api }
84
public final class GracefulSwitchLoadBalancer extends ForwardingLoadBalancer {
85
  public GracefulSwitchLoadBalancer(Helper helper);
86
  public static ConfigOrError parseLoadBalancingPolicyConfig(List<Map<String, ?>> loadBalancingConfigs);
87
  public static Object createLoadBalancingPolicyConfig(LoadBalancer.Factory childFactory, @Nullable Object childConfig);
88
}
89

90
public abstract class MultiChildLoadBalancer extends LoadBalancer {
91
  protected MultiChildLoadBalancer(Helper helper);
92
  protected abstract void updateOverallBalancingState();
93
  protected Map<Object, ResolvedAddresses> createChildAddressesMap(ResolvedAddresses resolvedAddresses);
94
}
95

96
public final class OutlierDetectionLoadBalancer extends LoadBalancer {
97
  public OutlierDetectionLoadBalancer(Helper helper, TimeProvider timeProvider);
98
}
99
```
100

101
[Load Balancing](./load-balancing.md)
102

103
### Forwarding Utilities
104

105
Base classes for creating decorators and extensions of core gRPC components using the forwarding pattern.
106

107
```java { .api }
108
public abstract class ForwardingLoadBalancer extends LoadBalancer {
109
  protected abstract LoadBalancer delegate();
110
}
111

112
public abstract class ForwardingLoadBalancerHelper extends LoadBalancer.Helper {
113
  protected abstract Helper delegate();
114
}
115

116
public abstract class ForwardingSubchannel extends LoadBalancer.Subchannel {
117
  protected abstract Subchannel delegate();
118
}
119

120
public abstract class ForwardingClientStreamTracer extends ClientStreamTracer {
121
  protected abstract ClientStreamTracer delegate();
122
}
123
```
124

125
[Forwarding Utilities](./forwarding-utilities.md)
126

127
### Server Utilities
128

129
Utilities for server-side functionality including mutable service registries and status exception handling.
130

131
```java { .api }
132
public final class MutableHandlerRegistry extends HandlerRegistry {
133
  public ServerServiceDefinition addService(ServerServiceDefinition service);
134
  public ServerServiceDefinition addService(BindableService bindableService);
135
  public boolean removeService(ServerServiceDefinition service);
136
  public List<ServerServiceDefinition> getServices();
137
  public ServerMethodDefinition<?, ?> lookupMethod(String methodName, String authority);
138
}
139

140
public final class TransmitStatusRuntimeExceptionInterceptor implements ServerInterceptor {
141
  public static ServerInterceptor instance();
142
}
143
```
144

145
[Server Utilities](./server-utilities.md)
146

147
## API Stability
148

149
- **Stable APIs**: `AdvancedTlsX509TrustManager`, `AdvancedTlsX509KeyManager`, `MutableHandlerRegistry`
150
- **Experimental APIs** (@ExperimentalApi): `GracefulSwitchLoadBalancer`, `CertificateUtils`, Forwarding classes, `TransmitStatusRuntimeExceptionInterceptor`
151
- **Internal APIs** (@Internal): `MultiChildLoadBalancer`, `OutlierDetectionLoadBalancer`, `HealthProducerHelper`
152

153
Internal APIs are subject to change without notice and should not be used directly in production code.
154

155
## Error Handling
156

157
gRPC Util methods throw standard Java exceptions:
158

159
- `CertificateException` - Certificate validation and processing errors
160
- `IOException` - File system operations and network I/O errors  
161
- `GeneralSecurityException` - Cryptographic operations and security context errors
162
- `KeyStoreException` - Key store access and manipulation errors
163
- `NoSuchAlgorithmException` - Unsupported cryptographic algorithms
164

165
gRPC-specific errors are communicated through `Status` objects and `StatusRuntimeException` instances.