or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

buffer-management.mdbuilders-factories.mdcore-utilities.mdindex.mdload-balancing-name-resolution.mdservice-providers.mdtransport-layer.md
tile.json

tessl/maven-io-grpc--grpc-core

Core gRPC library containing transport implementation, channel abstraction, load balancing, name resolution, and other fundamental gRPC functionalities for Java

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

To install, run

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

index.mddocs/

gRPC Core

gRPC Core is the foundational implementation module for gRPC-Java, providing essential transport layer functionality, channel management, load balancing, and name resolution. It serves as the backbone for all other gRPC-Java modules, offering critical infrastructure components while exposing its functionality primarily through Java Service Provider Interface (SPI) rather than traditional public APIs.

Package Information

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

Core Imports

Most functionality is automatically discovered via Java SPI, but internal classes can be imported when building other gRPC modules:

import io.grpc.internal.ManagedChannelImplBuilder;
import io.grpc.internal.ServerImplBuilder;
import io.grpc.internal.GrpcUtil;
import io.grpc.internal.ClientTransport;
import io.grpc.internal.ServerTransport;

Service providers are automatically registered:

import java.util.ServiceLoader;
import io.grpc.LoadBalancerProvider;
import io.grpc.NameResolverProvider;

// Automatic discovery - no direct imports needed
ServiceLoader<LoadBalancerProvider> lbProviders = ServiceLoader.load(LoadBalancerProvider.class);
ServiceLoader<NameResolverProvider> resolverProviders = ServiceLoader.load(NameResolverProvider.class);

Basic Usage

grPC Core is typically consumed indirectly through other gRPC modules. However, its service providers are automatically registered:

import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import io.grpc.Server;
import io.grpc.ServerBuilder;

// DNS name resolution (provided by grpc-core) is used automatically
ManagedChannel channel = ManagedChannelBuilder.forAddress("example.com", 443)
    .build();

// Pick-first load balancing (provided by grpc-core) is the default
Server server = ServerBuilder.forPort(8080)
    .build();

Architecture

gRPC Core is structured around several key architectural components:

  • Service Provider Interface (SPI): The primary public API surface, providing automatic registration of core functionality
  • Channel and Server Builders: Internal implementations that other modules extend to create specific transport types
  • Transport Abstractions: Interfaces defining client and server transport contracts
  • Buffer Management: Abstract buffer interfaces for efficient memory handling
  • Message Framing: Core framing and deframing logic for protocol handling
  • Load Balancing: Default pick-first implementation and provider interface
  • Name Resolution: DNS-based name resolution with provider interface
  • Utilities: Core utility classes used throughout the gRPC ecosystem

All implementation classes are in the io.grpc.internal package and are annotated with @Internal, indicating they're not part of the stable public API but are used by other gRPC modules.

Capabilities

Service Provider Registration

Automatic registration of core gRPC functionality through Java SPI mechanism. These providers are discovered automatically by the gRPC framework.

// Service providers registered in META-INF/services/
// io.grpc.LoadBalancerProvider -> io.grpc.internal.PickFirstLoadBalancerProvider
// io.grpc.NameResolverProvider -> io.grpc.internal.DnsNameResolverProvider

Service Providers

Channel and Server Building

Internal builder implementations that serve as the foundation for managed channels and servers. Other transport modules extend these builders.

class ManagedChannelImplBuilder extends ManagedChannelBuilder<ManagedChannelImplBuilder> {
    // Internal implementation - used by other modules
}

class ServerImplBuilder extends ServerBuilder<ServerImplBuilder> {
    // Internal implementation - used by other modules  
}

Builders and Factories

Transport Abstractions

Core transport interfaces that define contracts for client and server communication. These abstractions are implemented by specific transport modules.

interface ClientTransport {
    ClientStream newStream(
        MethodDescriptor<?, ?> method,
        Metadata headers,
        CallOptions callOptions,
        StatsTraceContext statsTraceContext
    );
    void ping(PingCallback callback, Executor executor);
}

interface ServerTransport {
    void start(ServerTransportListener listener);
    void shutdown();
}

Transport Layer

Buffer Management

Memory-efficient buffer abstractions for handling data in gRPC streams. Provides interfaces for readable and writable buffers used across all transport implementations.

interface ReadableBuffer {
    int readableBytes();
    int readUnsignedByte();
    void readBytes(byte[] dest, int destOffset, int length);
    ReadableBuffer readBytes(int length);
    void close();
}

interface WritableBuffer {
    void write(byte[] src, int srcOffset, int length);
    void write(byte b);
    int writableBytes();
    int readableBytes();
}

Buffer Management

Load Balancing and Name Resolution

Default implementations for load balancing and name resolution. The pick-first load balancer is the default strategy, and DNS name resolution handles service discovery.

class PickFirstLoadBalancerProvider extends LoadBalancerProvider {
    public boolean isAvailable();
    public int getPriority();
    public String getPolicyName();
    public LoadBalancer newLoadBalancer(LoadBalancer.Helper helper);
}

class DnsNameResolverProvider extends NameResolverProvider {
    public NameResolver newNameResolver(URI targetUri, NameResolver.Args args);
    public String getDefaultScheme();
}

Load Balancing and Name Resolution

Core Utilities

Essential utility classes providing common functionality used throughout the gRPC ecosystem. These utilities handle attributes, configuration, and common operations.

class GrpcUtil {
    public static final Splitter ACCEPT_ENCODING_SPLITTER;
    public static final String CONTENT_ACCEPT_ENCODING_KEY;
    public static final String CONTENT_ENCODING_KEY;
    
    public static Metadata.Key<String> keyForProto(String name);
    public static String getGrpcBuildVersion();
    public static TimeProvider getTimeProvider();
}

Core Utilities

Types

Common Interfaces and Classes

// Stream abstractions
interface ClientStream {
    void request(int numMessages);
    void writeMessage(InputStream message);
    void flush();
    void cancel(Status status);
}

interface ServerStream {
    void request(int numMessages);
    void writeMessage(InputStream message);
    void flush();
    void close(Status status, Metadata trailers);
}

// Transport factories
interface ClientTransportFactory {
    ClientTransport newClientTransport(
        SocketAddress serverAddress,
        ClientTransportOptions options
    );
    void close();
}

// Buffer allocators
interface WritableBufferAllocator {
    WritableBuffer allocate(int capacityHint);
}

// Listener interfaces
interface ClientStreamListener {
    void messagesAvailable(MessageProducer producer);
    void onReady();
    void closed(Status status, Metadata trailers);
}

interface ServerStreamListener {
    void messagesAvailable(MessageProducer producer);
    void halfClosed();
    void closed(Status status);
}