public interface ChannelEndpointCacheCache for server connections used in location-aware routing.
Implementations are expected to cache ChannelEndpoint instances such that repeated calls with the same address return the same instance. This allows routing components to efficiently manage server references.
Implementations must be thread-safe. Multiple threads may concurrently call #get(String) with different addresses.
Methods
defaultChannel()
public abstract ChannelEndpoint defaultChannel()Returns the default channel endpoint.
The default channel is the original endpoint configured in com.google.cloud.spanner.SpannerOptions. It is used as a fallback when the location cache does not have routing information for a request.
| Returns | |
|---|---|
| Type | Description |
ChannelEndpoint |
the default channel, never null |
evict(String address)
public abstract void evict(String address)Evicts a server connection from the cache and gracefully shuts down its channel.
This method should be called when a server becomes unhealthy or is no longer needed. The channel shutdown is graceful: existing RPCs are allowed to complete, but new RPCs will not be accepted on this channel.
If the address is not in the cache, this method does nothing.
| Parameter | |
|---|---|
| Name | Description |
address |
Stringthe server address to evict |
get(String address)
public abstract ChannelEndpoint get(String address)Returns a cached channel for the given address, creating it if needed.
If a channel for this address already exists in the cache, the cached instance is returned. Otherwise, a new server connection is created and cached.
| Parameter | |
|---|---|
| Name | Description |
address |
Stringthe server address in "host:port" format |
| Returns | |
|---|---|
| Type | Description |
ChannelEndpoint |
a channel instance for the address, never null |
getIfPresent(String address)
public abstract ChannelEndpoint getIfPresent(String address)Returns a cached channel for the given address without creating it.
Unlike #get(String), this method does not create a new endpoint if one does not already exist in the cache. This is used by location-aware routing to avoid foreground endpoint creation on the request path.
| Parameter | |
|---|---|
| Name | Description |
address |
Stringthe server address in "host:port" format |
| Returns | |
|---|---|
| Type | Description |
ChannelEndpoint |
the cached channel instance, or null if no endpoint exists for this address |
shutdown()
public abstract void shutdown()Shuts down all cached server connections.
This method should be called when the Spanner client is closed to release all resources. Each channel is shut down gracefully, allowing in-flight RPCs to complete.
After calling this method, the cache should not be used to create new connections.