Package com.google.cloud.spanner.spi.v1

Interface ChannelEndpointCache

@InternalApi public interface ChannelEndpointCache
Cache 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.

  • Method Summary

    Modifier and Type
    Method
    Description
    ChannelEndpoint
    defaultChannel()
    Returns the default channel endpoint.
    void
    evict(String address)
    Evicts a server connection from the cache and gracefully shuts down its channel.
    ChannelEndpoint
    get(String address)
    Returns a cached channel for the given address, creating it if needed.
    ChannelEndpoint
    getIfPresent(String address)
    Returns a cached channel for the given address without creating it.
    void
    shutdown()
    Shuts down all cached server connections.

  • Method Details

    • defaultChannel

      ChannelEndpoint defaultChannel()
      Returns the default channel endpoint.

      The default channel is the original endpoint configured in SpannerOptions. It is used as a fallback when the location cache does not have routing information for a request.

      Returns:
      the default channel, never null

    • get

      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.

      Parameters:
      address - the server address in "host:port" format
      Returns:
      a channel instance for the address, never null
      Throws:
      SpannerException - if the channel cannot be created

    • getIfPresent

      @Nullable 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.

      Parameters:
      address - the server address in "host:port" format
      Returns:
      the cached channel instance, or null if no endpoint exists for this address

    • evict

      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.

      Parameters:
      address - the server address to evict

    • shutdown

      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.