or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

forwarding-utilities.mdindex.mdload-balancing.mdserver-utilities.mdtls-management.md
tile.json

tessl/maven-io-grpc--grpc-util

Advanced utilities for gRPC Java providing load balancing, TLS management, and server utilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.grpc/grpc-util@1.73.x

To install, run

npx @tessl/cli install tessl/maven-io-grpc--grpc-util@1.73.0

index.mddocs/

gRPC Util

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.

Package Information

  • Package Name: io.grpc:grpc-util
  • Package Type: Maven
  • Language: Java
  • Installation: Add to Maven: <dependency><groupId>io.grpc</groupId><artifactId>grpc-util</artifactId><version>1.73.0</version></dependency>
  • Installation: Add to Gradle: implementation 'io.grpc:grpc-util:1.73.0'

Core Imports

import io.grpc.util.GracefulSwitchLoadBalancer;
import io.grpc.util.AdvancedTlsX509TrustManager;
import io.grpc.util.AdvancedTlsX509KeyManager;
import io.grpc.util.MutableHandlerRegistry;
import io.grpc.util.CertificateUtils;

Basic Usage

import io.grpc.util.AdvancedTlsX509TrustManager;
import io.grpc.util.MutableHandlerRegistry;
import io.grpc.ServerServiceDefinition;

// Advanced TLS trust manager with system defaults
AdvancedTlsX509TrustManager trustManager = AdvancedTlsX509TrustManager.newBuilder()
    .setVerification(AdvancedTlsX509TrustManager.Verification.CERTIFICATE_AND_HOST_NAME_VERIFICATION)
    .build();
trustManager.useSystemDefaultTrustCerts();

// Mutable service registry for dynamic service management
MutableHandlerRegistry registry = new MutableHandlerRegistry();
ServerServiceDefinition service = MyServiceGrpc.bindService(new MyServiceImpl());
registry.addService(service);

Architecture

gRPC Util is organized around several key components:

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

Capabilities

TLS and Certificate Management

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

public final class AdvancedTlsX509TrustManager extends X509ExtendedTrustManager {
  public static Builder newBuilder();
  public void useSystemDefaultTrustCerts() throws CertificateException, KeyStoreException, NoSuchAlgorithmException;
  public void updateTrustCredentials(X509Certificate[] trustCerts) throws IOException, GeneralSecurityException;
  public Closeable updateTrustCredentials(File trustCertFile, long period, TimeUnit unit, ScheduledExecutorService executor) throws IOException, GeneralSecurityException;
}

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

public final class CertificateUtils {
  public static X509Certificate[] getX509Certificates(InputStream inputStream) throws IOException, GeneralSecurityException;
  public static PrivateKey getPrivateKey(InputStream inputStream) throws IOException, GeneralSecurityException;
}

TLS and Certificate Management

Load Balancing

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

public final class GracefulSwitchLoadBalancer extends ForwardingLoadBalancer {
  public GracefulSwitchLoadBalancer(Helper helper);
  public static ConfigOrError parseLoadBalancingPolicyConfig(List<Map<String, ?>> loadBalancingConfigs);
  public static Object createLoadBalancingPolicyConfig(LoadBalancer.Factory childFactory, @Nullable Object childConfig);
}

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

public final class OutlierDetectionLoadBalancer extends LoadBalancer {
  public OutlierDetectionLoadBalancer(Helper helper, TimeProvider timeProvider);
}

Load Balancing

Forwarding Utilities

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

public abstract class ForwardingLoadBalancer extends LoadBalancer {
  protected abstract LoadBalancer delegate();
}

public abstract class ForwardingLoadBalancerHelper extends LoadBalancer.Helper {
  protected abstract Helper delegate();
}

public abstract class ForwardingSubchannel extends LoadBalancer.Subchannel {
  protected abstract Subchannel delegate();
}

public abstract class ForwardingClientStreamTracer extends ClientStreamTracer {
  protected abstract ClientStreamTracer delegate();
}

Forwarding Utilities

Server Utilities

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

public final class MutableHandlerRegistry extends HandlerRegistry {
  public ServerServiceDefinition addService(ServerServiceDefinition service);
  public ServerServiceDefinition addService(BindableService bindableService);
  public boolean removeService(ServerServiceDefinition service);
  public List<ServerServiceDefinition> getServices();
  public ServerMethodDefinition<?, ?> lookupMethod(String methodName, String authority);
}

public final class TransmitStatusRuntimeExceptionInterceptor implements ServerInterceptor {
  public static ServerInterceptor instance();
}

Server Utilities

API Stability

  • Stable APIs: AdvancedTlsX509TrustManager, AdvancedTlsX509KeyManager, MutableHandlerRegistry
  • Experimental APIs (@ExperimentalApi): GracefulSwitchLoadBalancer, CertificateUtils, Forwarding classes, TransmitStatusRuntimeExceptionInterceptor
  • Internal APIs (@Internal): MultiChildLoadBalancer, OutlierDetectionLoadBalancer, HealthProducerHelper

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

Error Handling

gRPC Util methods throw standard Java exceptions:

  • CertificateException - Certificate validation and processing errors
  • IOException - File system operations and network I/O errors
  • GeneralSecurityException - Cryptographic operations and security context errors
  • KeyStoreException - Key store access and manipulation errors
  • NoSuchAlgorithmException - Unsupported cryptographic algorithms

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