tessl/maven-com-google-api--gax-grpc

Google API Extensions for Java providing gRPC-specific functionality for Google Cloud client libraries

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

GAX-gRPC

Name: tessl/maven-com-google-api--gax-grpc
Author: tessl

Google API Extensions for Java (gax-grpc) provides gRPC-specific functionality for Google Cloud client libraries. It builds on the core GAX library to offer transport-specific features like channel management, interceptors, and long-running operations support, enabling robust and idiomatic Google Cloud service integrations.

Package Information

Package Name: gax-grpc
Package Type: maven
Language: Java
Maven Coordinates: com.google.api:gax-grpc:2.67.0
Installation: Add to your pom.xml:

<dependency>
    <groupId>com.google.api</groupId>
    <artifactId>gax-grpc</artifactId>
    <version>2.67.0</version>
</dependency>

Core Imports

import com.google.api.gax.grpc.GrpcCallContext;
import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
import com.google.api.gax.grpc.GrpcTransportChannel;
import com.google.api.gax.grpc.GrpcCallSettings;

For Long Running Operations:

import com.google.longrunning.OperationsClient;
import com.google.longrunning.OperationsSettings;

Basic Usage

import com.google.api.gax.grpc.InstantiatingGrpcChannelProvider;
import com.google.api.gax.grpc.GrpcTransportChannel;
import com.google.api.gax.grpc.GrpcCallContext;
import com.google.auth.oauth2.GoogleCredentials;

// Create a gRPC channel provider
InstantiatingGrpcChannelProvider channelProvider = 
    InstantiatingGrpcChannelProvider.newBuilder()
        .setEndpoint("your-service-endpoint.googleapis.com:443")
        .setCredentials(GoogleCredentials.getApplicationDefault())
        .build();

// Get transport channel
GrpcTransportChannel transportChannel = 
    (GrpcTransportChannel) channelProvider.getTransportChannel();

// Create call context
GrpcCallContext callContext = GrpcCallContext.createDefault()
    .withTransportChannel(transportChannel)
    .withTimeoutDuration(Duration.ofSeconds(30));

Architecture

GAX-gRPC is built around several key components:

Channel Management: Sophisticated connection pooling and lifecycle management with DirectPath optimization
Call Context: Immutable context objects encapsulating channel, timeout, and retry configuration
Callable Factory: Generates type-safe callables for different RPC patterns (unary, streaming, paged, batching)
Interceptor System: Comprehensive interceptor support for headers, logging, and metadata handling
Long Running Operations: Complete implementation of Google's LRO pattern with polling and cancellation
Native Image Support: GraalVM compatibility with reflection configuration for grpc-netty-shaded

Capabilities

Channel Management

Comprehensive gRPC channel lifecycle management with connection pooling, load balancing, and Google Cloud optimizations including DirectPath support.

public final class InstantiatingGrpcChannelProvider implements TransportChannelProvider {
    public static Builder newBuilder();
    public TransportChannel getTransportChannel() throws IOException;
    public String getEndpoint();
    public ChannelPoolSettings getChannelPoolSettings();
}

public abstract class ChannelPoolSettings {
    public static ChannelPoolSettings staticallySized(int size);
    public static Builder builder();
    public int getMinRpcsPerChannel();
    public int getMaxRpcsPerChannel();
    public int getMinChannelCount();
    public int getMaxChannelCount();
}

Channel Management

Call Context and Configuration

Immutable context objects for configuring gRPC calls including timeouts, retries, headers, and channel affinity.

public final class GrpcCallContext implements ApiCallContext {
    public static GrpcCallContext createDefault();
    public static GrpcCallContext of(Channel channel, CallOptions callOptions);
    public GrpcCallContext withCredentials(Credentials credentials);
    public GrpcCallContext withTimeoutDuration(Duration timeout);
    public GrpcCallContext withRetrySettings(RetrySettings retrySettings);
    public GrpcCallContext withChannelAffinity(Integer affinity);
}

public class GrpcCallSettings<RequestT, ResponseT> {
    public static <RequestT, ResponseT> Builder<RequestT, ResponseT> newBuilder();
    public MethodDescriptor<RequestT, ResponseT> getMethodDescriptor();
    public RequestParamsExtractor<RequestT> getParamsExtractor();
}

Call Context

Callable Factory

Factory methods for creating different types of gRPC callables including unary, streaming, paged, batching, and operation callables.

public class GrpcCallableFactory {
    public static <RequestT, ResponseT> UnaryCallable<RequestT, ResponseT> 
        createUnaryCallable(GrpcCallSettings<RequestT, ResponseT> grpcCallSettings, 
                           UnaryCallSettings<RequestT, ResponseT> callSettings, 
                           ClientContext clientContext);
    
    public static <RequestT, ResponseT> BidiStreamingCallable<RequestT, ResponseT> 
        createBidiStreamingCallable(GrpcCallSettings<RequestT, ResponseT> grpcCallSettings, 
                                   StreamingCallSettings<RequestT, ResponseT> callSettings, 
                                   ClientContext clientContext);
    
    public static <RequestT, ResponseT, MetadataT> OperationCallable<RequestT, ResponseT, MetadataT> 
        createOperationCallable(GrpcCallSettings<RequestT, Operation> grpcCallSettings, 
                               OperationCallSettings<RequestT, ResponseT, MetadataT> operationCallSettings, 
                               ClientContext clientContext, 
                               OperationsStub operationsStub);
}

Callable Factory

Long Running Operations

Complete client support for Google's Long Running Operations API with polling, cancellation, and status management.

public class OperationsClient implements BackgroundResource {
    public static OperationsClient create(OperationsSettings settings) throws IOException;
    public Operation getOperation(String name);
    public ListOperationsPagedResponse listOperations(String name, String filter);
    public void cancelOperation(String name);
    public void deleteOperation(String name);
    public Operation waitOperation(WaitOperationRequest request);
}

public class OperationsSettings {
    public static Builder newBuilder();
    public UnaryCallSettings<GetOperationRequest, Operation> getOperationSettings();
    public PagedCallSettings<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse> 
        listOperationsSettings();
}

Long Running Operations

Transport Channel and Status

gRPC transport channel implementation and status code handling for the GAX transport abstraction layer.

public abstract class GrpcTransportChannel implements TransportChannel {
    public static String getGrpcTransportName();
    public static Builder newBuilder();
    public static GrpcTransportChannel create(ManagedChannel channel);
    public Channel getChannel();
    public boolean isDirectPath();
}

public abstract class GrpcStatusCode implements StatusCode {
    public static GrpcStatusCode of(Status.Code grpcCode);
    public StatusCode.Code getCode();
}

Transport and Status

Interceptors and Metadata

Comprehensive interceptor support for headers, logging, metadata handling, and custom request/response processing.

public interface GrpcInterceptorProvider {
    List<ClientInterceptor> getInterceptors();
}

public class GrpcResponseMetadata implements ResponseMetadata {
    public Map<String, List<String>> getMetadata();
    public List<String> getTrailersMetadata();
}

public class GrpcHeaderInterceptor implements ClientInterceptor {
    public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
        MethodDescriptor<ReqT, RespT> method, 
        CallOptions callOptions, 
        Channel next);
}

Interceptors

Types

Core Types

// Channel provider builder with comprehensive configuration options
public static final class InstantiatingGrpcChannelProvider.Builder {
    public Builder setEndpoint(String endpoint);
    public Builder setCredentials(Credentials credentials);
    public Builder setHeaderProvider(HeaderProvider headerProvider);
    public Builder setChannelConfigurator(ApiFunction<ManagedChannelBuilder, ManagedChannelBuilder> channelConfigurator);
    public Builder setKeepAliveTime(Duration keepAliveTime);
    public Builder setKeepAliveTimeout(Duration keepAliveTimeout);
    public Builder setKeepAliveWithoutCalls(Boolean keepAliveWithoutCalls);
    public Builder setMaxInboundMessageSize(Integer maxInboundMessageSize);
    public Builder setMaxInboundMetadataSize(Integer maxInboundMetadataSize);
    public Builder setChannelPoolSettings(ChannelPoolSettings channelPoolSettings);
    public Builder setDirectPathServiceConfig(Map<String, ?> serviceConfig);
    public InstantiatingGrpcChannelProvider build();
}

// Context builder for configuring call-specific settings
public static final class GrpcCallContext.Builder {
    public Builder setChannel(Channel channel);
    public Builder setCallOptions(CallOptions callOptions);
    public Builder setTimeout(Duration timeout);
    public Builder setStreamWaitTimeout(Duration streamWaitTimeout);
    public Builder setStreamIdleTimeout(Duration streamIdleTimeout);
    public GrpcCallContext build();
}

Operations Types

// Settings builder for operations client configuration
public static class OperationsSettings.Builder {
    public Builder setCredentialsProvider(CredentialsProvider credentialsProvider);
    public Builder setTransportChannelProvider(TransportChannelProvider transportChannelProvider);
    public Builder setHeaderProvider(HeaderProvider headerProvider);
    public Builder setEndpoint(String endpoint);
    public Builder setQuotaProjectId(String quotaProjectId);
    public UnaryCallSettings.Builder<GetOperationRequest, Operation> getOperationSettings();
    public PagedCallSettings.Builder<ListOperationsRequest, ListOperationsResponse, ListOperationsPagedResponse> 
        listOperationsSettings();
    public UnaryCallSettings.Builder<CancelOperationRequest, Empty> cancelOperationSettings();
    public UnaryCallSettings.Builder<DeleteOperationRequest, Empty> deleteOperationSettings();
    public OperationsSettings build() throws IOException;
}