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.