0
# gRPC Core
1
2
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.
3
4
## Package Information
5
6
- **Package Name**: io.grpc:grpc-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to Maven dependencies:
10
```xml
11
<dependency>
12
<groupId>io.grpc</groupId>
13
<artifactId>grpc-core</artifactId>
14
<version>1.73.0</version>
15
</dependency>
16
```
17
- **Gradle**: Add to build.gradle:
18
```gradle
19
implementation 'io.grpc:grpc-core:1.73.0'
20
```
21
22
## Core Imports
23
24
Most functionality is automatically discovered via Java SPI, but internal classes can be imported when building other gRPC modules:
25
26
```java
27
import io.grpc.internal.ManagedChannelImplBuilder;
28
import io.grpc.internal.ServerImplBuilder;
29
import io.grpc.internal.GrpcUtil;
30
import io.grpc.internal.ClientTransport;
31
import io.grpc.internal.ServerTransport;
32
```
33
34
Service providers are automatically registered:
35
```java
36
import java.util.ServiceLoader;
37
import io.grpc.LoadBalancerProvider;
38
import io.grpc.NameResolverProvider;
39
40
// Automatic discovery - no direct imports needed
41
ServiceLoader<LoadBalancerProvider> lbProviders = ServiceLoader.load(LoadBalancerProvider.class);
42
ServiceLoader<NameResolverProvider> resolverProviders = ServiceLoader.load(NameResolverProvider.class);
43
```
44
45
## Basic Usage
46
47
grPC Core is typically consumed indirectly through other gRPC modules. However, its service providers are automatically registered:
48
49
```java
50
import io.grpc.ManagedChannel;
51
import io.grpc.ManagedChannelBuilder;
52
import io.grpc.Server;
53
import io.grpc.ServerBuilder;
54
55
// DNS name resolution (provided by grpc-core) is used automatically
56
ManagedChannel channel = ManagedChannelBuilder.forAddress("example.com", 443)
57
.build();
58
59
// Pick-first load balancing (provided by grpc-core) is the default
60
Server server = ServerBuilder.forPort(8080)
61
.build();
62
```
63
64
## Architecture
65
66
gRPC Core is structured around several key architectural components:
67
68
- **Service Provider Interface (SPI)**: The primary public API surface, providing automatic registration of core functionality
69
- **Channel and Server Builders**: Internal implementations that other modules extend to create specific transport types
70
- **Transport Abstractions**: Interfaces defining client and server transport contracts
71
- **Buffer Management**: Abstract buffer interfaces for efficient memory handling
72
- **Message Framing**: Core framing and deframing logic for protocol handling
73
- **Load Balancing**: Default pick-first implementation and provider interface
74
- **Name Resolution**: DNS-based name resolution with provider interface
75
- **Utilities**: Core utility classes used throughout the gRPC ecosystem
76
77
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.
78
79
## Capabilities
80
81
### Service Provider Registration
82
83
Automatic registration of core gRPC functionality through Java SPI mechanism. These providers are discovered automatically by the gRPC framework.
84
85
```java { .api }
86
// Service providers registered in META-INF/services/
87
// io.grpc.LoadBalancerProvider -> io.grpc.internal.PickFirstLoadBalancerProvider
88
// io.grpc.NameResolverProvider -> io.grpc.internal.DnsNameResolverProvider
89
```
90
91
[Service Providers](./service-providers.md)
92
93
### Channel and Server Building
94
95
Internal builder implementations that serve as the foundation for managed channels and servers. Other transport modules extend these builders.
96
97
```java { .api }
98
class ManagedChannelImplBuilder extends ManagedChannelBuilder<ManagedChannelImplBuilder> {
99
// Internal implementation - used by other modules
100
}
101
102
class ServerImplBuilder extends ServerBuilder<ServerImplBuilder> {
103
// Internal implementation - used by other modules
104
}
105
```
106
107
[Builders and Factories](./builders-factories.md)
108
109
### Transport Abstractions
110
111
Core transport interfaces that define contracts for client and server communication. These abstractions are implemented by specific transport modules.
112
113
```java { .api }
114
interface ClientTransport {
115
ClientStream newStream(
116
MethodDescriptor<?, ?> method,
117
Metadata headers,
118
CallOptions callOptions,
119
StatsTraceContext statsTraceContext
120
);
121
void ping(PingCallback callback, Executor executor);
122
}
123
124
interface ServerTransport {
125
void start(ServerTransportListener listener);
126
void shutdown();
127
}
128
```
129
130
[Transport Layer](./transport-layer.md)
131
132
### Buffer Management
133
134
Memory-efficient buffer abstractions for handling data in gRPC streams. Provides interfaces for readable and writable buffers used across all transport implementations.
135
136
```java { .api }
137
interface ReadableBuffer {
138
int readableBytes();
139
int readUnsignedByte();
140
void readBytes(byte[] dest, int destOffset, int length);
141
ReadableBuffer readBytes(int length);
142
void close();
143
}
144
145
interface WritableBuffer {
146
void write(byte[] src, int srcOffset, int length);
147
void write(byte b);
148
int writableBytes();
149
int readableBytes();
150
}
151
```
152
153
[Buffer Management](./buffer-management.md)
154
155
### Load Balancing and Name Resolution
156
157
Default implementations for load balancing and name resolution. The pick-first load balancer is the default strategy, and DNS name resolution handles service discovery.
158
159
```java { .api }
160
class PickFirstLoadBalancerProvider extends LoadBalancerProvider {
161
public boolean isAvailable();
162
public int getPriority();
163
public String getPolicyName();
164
public LoadBalancer newLoadBalancer(LoadBalancer.Helper helper);
165
}
166
167
class DnsNameResolverProvider extends NameResolverProvider {
168
public NameResolver newNameResolver(URI targetUri, NameResolver.Args args);
169
public String getDefaultScheme();
170
}
171
```
172
173
[Load Balancing and Name Resolution](./load-balancing-name-resolution.md)
174
175
### Core Utilities
176
177
Essential utility classes providing common functionality used throughout the gRPC ecosystem. These utilities handle attributes, configuration, and common operations.
178
179
```java { .api }
180
class GrpcUtil {
181
public static final Splitter ACCEPT_ENCODING_SPLITTER;
182
public static final String CONTENT_ACCEPT_ENCODING_KEY;
183
public static final String CONTENT_ENCODING_KEY;
184
185
public static Metadata.Key<String> keyForProto(String name);
186
public static String getGrpcBuildVersion();
187
public static TimeProvider getTimeProvider();
188
}
189
```
190
191
[Core Utilities](./core-utilities.md)
192
193
## Types
194
195
### Common Interfaces and Classes
196
197
```java { .api }
198
// Stream abstractions
199
interface ClientStream {
200
void request(int numMessages);
201
void writeMessage(InputStream message);
202
void flush();
203
void cancel(Status status);
204
}
205
206
interface ServerStream {
207
void request(int numMessages);
208
void writeMessage(InputStream message);
209
void flush();
210
void close(Status status, Metadata trailers);
211
}
212
213
// Transport factories
214
interface ClientTransportFactory {
215
ClientTransport newClientTransport(
216
SocketAddress serverAddress,
217
ClientTransportOptions options
218
);
219
void close();
220
}
221
222
// Buffer allocators
223
interface WritableBufferAllocator {
224
WritableBuffer allocate(int capacityHint);
225
}
226
227
// Listener interfaces
228
interface ClientStreamListener {
229
void messagesAvailable(MessageProducer producer);
230
void onReady();
231
void closed(Status status, Metadata trailers);
232
}
233
234
interface ServerStreamListener {
235
void messagesAvailable(MessageProducer producer);
236
void halfClosed();
237
void closed(Status status);
238
}
239
```