MemcacheClientBuilder (folsom 1.7.3 API)

java.lang.Object
- com.spotify.folsom.MemcacheClientBuilder<V>

public class MemcacheClientBuilder<V>
extends java.lang.Object

Field Summary

Fields
Modifier and Type	Field and Description
`private java.util.List<HostAndPort>`	`addresses`
`private BackoffFunction`	`backoffFunction`
`private int`	`batchSize`
`private java.lang.Class<? extends io.netty.channel.Channel>`	`channelClass`
`private java.nio.charset.Charset`	`charset`
`private int`	`connections`
`private long`	`connectionTimeoutMillis`
`private static java.lang.String`	`DEFAULT_HOSTNAME`
`private static int`	`DEFAULT_MAX_OUTSTANDING`
`private static int`	`DEFAULT_MAX_SET_LENGTH`
`private static int`	`DEFAULT_PORT`
`private static java.util.function.Supplier<java.util.concurrent.Executor>`	`DEFAULT_REPLY_EXECUTOR` Lazily instantiated singleton default executor.
`private static java.util.function.Supplier<java.util.concurrent.ScheduledExecutorService>`	`DEFAULT_SCHEDULED_EXECUTOR` Lazily instantiated singleton default scheduled executor.
`private io.netty.channel.EventLoopGroup`	`eventLoopGroup`
`private java.util.function.Supplier<java.util.concurrent.Executor>`	`executor`
`private int`	`maxKeyLength`
`private int`	`maxOutstandingRequests`
`private int`	`maxSetLength`
`private Metrics`	`metrics`
`private java.util.List<PlaintextAuthenticator>`	`passwords`
`private Resolver`	`resolver`
`private long`	`resolveRefreshPeriod`
`private boolean`	`retry`
`private long`	`shutdownDelay`
`private boolean`	`skipAuth`
`private java.lang.String`	`srvRecord`
`private com.spotify.dns.DnsSrvResolver`	`srvResolver`
`private Tracer`	`tracer`
`private Transcoder<V>`	`valueTranscoder`

Constructor Summary

Constructors
Constructor and Description

MemcacheClientBuilder(Transcoder<V> valueTranscoder)
Create a client builder with the provided value transcoder.

Constructors
Constructor and Description
`MemcacheClientBuilder(Transcoder<V> valueTranscoder)` Create a client builder with the provided value transcoder.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`AsciiMemcacheClient<V>`	`connectAscii()` Create a client that uses the ascii memcache protocol.
`BinaryMemcacheClient<V>`	`connectBinary()` Create a client that uses the binary memcache protocol.
`protected RawMemcacheClient`	`connectRaw(boolean binary, Authenticator authenticator)` Connect a raw memcached client without any protocol specific methods.
`private RawMemcacheClient`	`createClient(HostAndPort address, boolean binary, Authenticator authenticator)`
`private java.util.List<RawMemcacheClient>`	`createClients(java.util.List<HostAndPort> addresses, boolean binary, Authenticator authenticator)`
`private RawMemcacheClient`	`createReconnectingClient(HostAndPort address, boolean binary, Authenticator authenticator)`
`private RawMemcacheClient`	`createResolvingClient(boolean binary, Authenticator authenticator)`
`private Authenticator`	`getAuthenticator(Authenticator defaultValue)`
`static MemcacheClientBuilder<byte[]>`	`newByteArrayClient()` Create a client builder for byte array values.
`static MemcacheClientBuilder<java.io.Serializable>`	`newSerializableObjectClient()` Create a client builder for serializable object values.
`static MemcacheClientBuilder<java.lang.String>`	`newStringClient()` Create a client builder with a basic string transcoder using the UTF-8 Charset.
`static MemcacheClientBuilder<java.lang.String>`	`newStringClient(java.nio.charset.Charset charset)` Create a client builder with a basic string transcoder using the supplied Charset.
`private void`	`updateResolver()` Used for backwards compatibility for srvRecord and srvResolver.
`MemcacheClientBuilder<V>`	`withAddress(java.lang.String hostname)` Define which memcache server to connect to.
`MemcacheClientBuilder<V>`	`withAddress(java.lang.String host, int port)` Define which memcache server to connect to.
`MemcacheClientBuilder<V>`	`withBackoff(BackoffFunction backoffFunction)` Specify how long the client should wait between reconnects.
`MemcacheClientBuilder<V>`	`withChannelClass(java.lang.Class<? extends io.netty.channel.Channel> channelClass)` Set a Netty `Channel` class for the client.
`MemcacheClientBuilder<V>`	`withConnections(int connections)` Use multiple connections to each memcache server.
`MemcacheClientBuilder<V>`	`withConnectionTimeoutMillis(long timeoutMillis)` Set the maximum time to wait before considering the connection to be dead and should be closed and recreated.
`MemcacheClientBuilder<V>`	`withEventLoopGroup(io.netty.channel.EventLoopGroup eventLoopGroup)` Set an Netty `EventLoopGroup` for the client.
`MemcacheClientBuilder<V>`	`withKeyCharset(java.nio.charset.Charset charset)` Define the charset encoding for keys.
`MemcacheClientBuilder<V>`	`withMaxKeyLength(int maxKeyLength)` Set the maximum key length of the byte representation of the input string.
`MemcacheClientBuilder<V>`	`withMaxOutstandingRequests(int maxOutstandingRequests)` Specify the maximum number of requests in the queue per server connection.
`MemcacheClientBuilder<V>`	`withMaxSetLength(int maxSetLength)` Set the maximum value size for set requests.
`MemcacheClientBuilder<V>`	`withMetrics(Metrics metrics)` Specify how to collect metrics.
`(package private) MemcacheClientBuilder<V>`	`withoutAuthenticationValidation()` Disable authentication validation - only useful for tests against jmemcached which does not support binary NOOP
`MemcacheClientBuilder<V>`	`withReplyExecutor(java.util.concurrent.Executor executor)` Specify an executor to execute all replies on.
`MemcacheClientBuilder<V>`	`withRequestBatchSize(int batchSize)` Specify the maximum number of operations that will be batched together in one network request.
`MemcacheClientBuilder<V>`	`withRequestTimeoutMillis(long timeoutMillis)` Deprecated.
`MemcacheClientBuilder<V>`	`withResolver(Resolver resolver)` Use a dynamic resolved instead of a fixed set of addresses.
`MemcacheClientBuilder<V>`	`withResolveRefreshPeriod(long periodMillis)` This is only used for the dynamic ketama client.
`MemcacheClientBuilder<V>`	`withResolveShutdownDelay(long shutdownDelay)` This is only used for the dynamic ketama client.
`MemcacheClientBuilder<V>`	`withRetry(boolean retry)` Specify if the client should retry once if the connection is closed.
`MemcacheClientBuilder<V>`	`withSRVRecord(java.lang.String srvRecord)` Deprecated. Use `withResolver(Resolver)` with `SrvResolver` instead.
`MemcacheClientBuilder<V>`	`withSRVRefreshPeriod(long periodMillis)` Deprecated. Use `withResolveRefreshPeriod(long)`
`MemcacheClientBuilder<V>`	`withSrvResolver(com.spotify.dns.DnsSrvResolver srvResolver)` Deprecated. Use `withResolver(Resolver)` with `SrvResolver` instead
`MemcacheClientBuilder<V>`	`withSRVShutdownDelay(long shutdownDelay)` Deprecated. Use `withResolveShutdownDelay(long)`
`MemcacheClientBuilder<V>`	`withTracer(Tracer tracer)` Specify how to collect tracing.
`MemcacheClientBuilder<V>`	`withUsernamePassword(java.lang.String username, java.lang.String password)` Authenticate with memcached using plaintext SASL.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DEFAULT_MAX_SET_LENGTH
```
private static final int DEFAULT_MAX_SET_LENGTH
```
    See Also:
    
    Constant Field Values
  - DEFAULT_MAX_OUTSTANDING
```
private static final int DEFAULT_MAX_OUTSTANDING
```
    See Also:
    
    Constant Field Values
  - DEFAULT_HOSTNAME
```
private static final java.lang.String DEFAULT_HOSTNAME
```
    See Also:
    
    Constant Field Values
  - DEFAULT_PORT
```
private static final int DEFAULT_PORT
```
    See Also:
    
    Constant Field Values
  - DEFAULT_REPLY_EXECUTOR
```
private static final java.util.function.Supplier<java.util.concurrent.Executor> DEFAULT_REPLY_EXECUTOR
```
    Lazily instantiated singleton default executor.
  - DEFAULT_SCHEDULED_EXECUTOR
```
private static final java.util.function.Supplier<java.util.concurrent.ScheduledExecutorService> DEFAULT_SCHEDULED_EXECUTOR
```
    Lazily instantiated singleton default scheduled executor.
  - addresses
```
private final java.util.List<HostAndPort> addresses
```
  - maxOutstandingRequests
```
private int maxOutstandingRequests
```
  - batchSize
```
private int batchSize
```
  - valueTranscoder
```
private final Transcoder<V> valueTranscoder
```
  - metrics
```
private Metrics metrics
```
  - tracer
```
private Tracer tracer
```
  - backoffFunction
```
private BackoffFunction backoffFunction
```
  - connections
```
private int connections
```
  - retry
```
private boolean retry
```
  - executor
```
private java.util.function.Supplier<java.util.concurrent.Executor> executor
```
  - charset
```
private java.nio.charset.Charset charset
```
  - resolver
```
private Resolver resolver
```
  - srvResolver
```
private com.spotify.dns.DnsSrvResolver srvResolver
```
  - srvRecord
```
private java.lang.String srvRecord
```
  - resolveRefreshPeriod
```
private long resolveRefreshPeriod
```
  - shutdownDelay
```
private long shutdownDelay
```
  - connectionTimeoutMillis
```
private long connectionTimeoutMillis
```
  - maxSetLength
```
private int maxSetLength
```
  - maxKeyLength
```
private int maxKeyLength
```
  - eventLoopGroup
```
private io.netty.channel.EventLoopGroup eventLoopGroup
```
  - channelClass
```
private java.lang.Class<? extends io.netty.channel.Channel> channelClass
```
  - passwords
```
private final java.util.List<PlaintextAuthenticator> passwords
```
  - skipAuth
```
private boolean skipAuth
```
- Constructor Detail
  - MemcacheClientBuilder
```
public MemcacheClientBuilder(Transcoder<V> valueTranscoder)
```
    Create a client builder with the provided value transcoder.
    
    Parameters:
    
    valueTranscoder - the transcoder to use to encode/decode values.
- Method Detail
  - newByteArrayClient
```
public static MemcacheClientBuilder<byte[]> newByteArrayClient()
```
    Create a client builder for byte array values.
    
    Returns:
    
    The builder
  - newStringClient
```
public static MemcacheClientBuilder<java.lang.String> newStringClient()
```
    Create a client builder with a basic string transcoder using the UTF-8 Charset.
    
    Returns:
    
    The builder
  - newStringClient
```
public static MemcacheClientBuilder<java.lang.String> newStringClient(java.nio.charset.Charset charset)
```
    Create a client builder with a basic string transcoder using the supplied Charset.
    
    Parameters:
    
    charset - the Charset to encode and decode String objects with.
    
    Returns:
    
    The builder
  - newSerializableObjectClient
```
public static MemcacheClientBuilder<java.io.Serializable> newSerializableObjectClient()
```
    Create a client builder for serializable object values.
    
    Returns:
    
    The builder
  - withKeyCharset
```
public MemcacheClientBuilder<V> withKeyCharset(java.nio.charset.Charset charset)
```
    Define the charset encoding for keys. Note that some charsets may not be compatible with the memcache protocol which requires that keys are a string of 8-bit characters with the exclusion of characters in the range [0x00, 0x20]. This is a problem in charsets such as UTF-16 which uses two bytes and one of them could easily be invalid for memcache purposes.
    UTF-8 and most single-byte charsets should be fine though.
    
    Parameters:
    
    charset - The charset encoding for keys. The default is UTF-8.
    
    Returns:
    
    itself
  - withAddress
```
public MemcacheClientBuilder<V> withAddress(java.lang.String hostname)
```
    Define which memcache server to connect to. This may be called multiple times to connect to multiple hosts. If more than one address is given, Ketama will be used to distribute requests.
    
    Parameters:
    
    hostname - a server, using the default memcached port (11211).
    
    Returns:
    
    itself
  - withAddress
```
public MemcacheClientBuilder<V> withAddress(java.lang.String host,
                                            int port)
```
    Define which memcache server to connect to. This may be called multiple times to connect to multiple hosts. If more than one address is given, Ketama will be used to distribute requests.
    
    Parameters:
    
    host - The server hostname
    
    port - The port where memcached is running
    
    Returns:
    
    itself
  - withResolver
```
public MemcacheClientBuilder<V> withResolver(Resolver resolver)
```
    Use a dynamic resolved instead of a fixed set of addresses. This means that the set of nodes can change dynamically over time.
    
    Parameters:
    
    resolver - the resolver to use.
    
    Returns:
    
    itself
  - updateResolver
```
private void updateResolver()
```
    Used for backwards compatibility for srvRecord and srvResolver.
  - withSRVRecord
```
@Deprecated
public MemcacheClientBuilder<V> withSRVRecord(java.lang.String srvRecord)
```
    Deprecated. Use withResolver(Resolver) with SrvResolver instead.
  - withResolveRefreshPeriod
```
public MemcacheClientBuilder<V> withResolveRefreshPeriod(long periodMillis)
```
    This is only used for the dynamic ketama client. This is the maximum time the resolver should be queried for updates. It can be shorter, depending the getTtl values in the resolve result
    
    Parameters:
    
    periodMillis - time in milliseonds. The default is 60 seconds.
    
    Returns:
    
    itself
  - withSRVRefreshPeriod
```
@Deprecated
public MemcacheClientBuilder<V> withSRVRefreshPeriod(long periodMillis)
```
    Deprecated. Use withResolveRefreshPeriod(long)
  - withResolveShutdownDelay
```
public MemcacheClientBuilder<V> withResolveShutdownDelay(long shutdownDelay)
```
    This is only used for the dynamic ketama client. When the resolver results has changed, the old client will be shutdown after this much time has passed, in order to complete pending requests.
    
    Parameters:
    
    shutdownDelay - time in milliseconds. The default is 60 seconds.
    
    Returns:
    
    itself
  - withSRVShutdownDelay
```
@Deprecated
public MemcacheClientBuilder<V> withSRVShutdownDelay(long shutdownDelay)
```
    Deprecated. Use withResolveShutdownDelay(long)
  - withSrvResolver
```
@Deprecated
public MemcacheClientBuilder<V> withSrvResolver(com.spotify.dns.DnsSrvResolver srvResolver)
```
    Deprecated. Use withResolver(Resolver) with SrvResolver instead
  - withMetrics
```
public MemcacheClientBuilder<V> withMetrics(Metrics metrics)
```
    Specify how to collect metrics.
    
    Parameters:
    
    metrics - Default is NoopMetrics - which doesn't collect anything.
    
    Returns:
    
    itself
  - withTracer
```
public MemcacheClientBuilder<V> withTracer(Tracer tracer)
```
    Specify how to collect tracing.
    
    Parameters:
    
    tracer - Default is NoopTracer - which doesn't collect anything.
    
    Returns:
    
    itself
  - withMaxOutstandingRequests
```
public MemcacheClientBuilder<V> withMaxOutstandingRequests(int maxOutstandingRequests)
```
    Specify the maximum number of requests in the queue per server connection. If this is set too low, requests will fail with MemcacheOverloadedException. If this is set too high, there is a risk of having high latency requests and delaying the time to notice that the system is malfunctioning.
    
    Parameters:
    
    maxOutstandingRequests - the maximum number of requests that can be in queue. Default is 1000.
    
    Returns:
    
    itself
  - withRequestBatchSize
```
public MemcacheClientBuilder<V> withRequestBatchSize(int batchSize)
```
    Specify the maximum number of operations that will be batched together in one network request.
    If the client's batch-size is larger than your memcached server's value, you may experience an increase in `conn_yields` on your memcached server's stats...which indicates your server is switching to other I/O connections during the batch request to not starve other connections.
    If this value is too low, your will make more network requests per operation, thus reducing your server's overall throughput.
    The optimal value should be matched to your workload and roughly the same value as your memcached server's `-R` argument, which defaults to 20.
    
    Parameters:
    
    batchSize - the maximum number of operations per batched client request. Default is .
    
    Returns:
    
    itself
  - withBackoff
```
public MemcacheClientBuilder<V> withBackoff(BackoffFunction backoffFunction)
```
    Specify how long the client should wait between reconnects.
    
    Parameters:
    
    backoffFunction - A custom backoff function. Default is exponential backoff.
    
    Returns:
    
    itself.
  - withRetry
```
public MemcacheClientBuilder<V> withRetry(boolean retry)
```
    Specify if the client should retry once if the connection is closed. This typically only has an effect when one of the ketama nodes disconnect while the request is sent.
    
    Parameters:
    
    retry - Default is true
    
    Returns:
    
    itself
  - withReplyExecutor
```
public MemcacheClientBuilder<V> withReplyExecutor(java.util.concurrent.Executor executor)
```
    Specify an executor to execute all replies on. Default is a shared ForkJoinPool in async mode with one thread per processor.
    If null is specified, replies will be executed on EventLoopGroup directly.
    Note: Calling non-async methods on the CompletionStages returned by MemcacheClient that have already completed will cause the supplied function to be executed directly on the calling thread.
    
    Parameters:
    
    executor - the executor to use.
    
    Returns:
    
    itself
  - withConnections
```
public MemcacheClientBuilder<V> withConnections(int connections)
```
    Use multiple connections to each memcache server. This is likely not a useful thing in practice, unless the IO connection really becomes a bottleneck.
    
    Parameters:
    
    connections - Number of connections, must be 1 or greater. The default is 1
    
    Returns:
    
    itself
  - withRequestTimeoutMillis
```
@Deprecated
public MemcacheClientBuilder<V> withRequestTimeoutMillis(long timeoutMillis)
```
    Deprecated.
    
    This has been deprecated - see {#link withConnectionTimeoutMillis}.
    Do not use this to enforce request timeouts. Instead, set a timeout on the request futures using orTimeout() or some other manual mechanism.
    
    Parameters:
    
    timeoutMillis - The timeout in milliseconds. The default is 3000 ms.
    
    Returns:
    
    itself
  - withConnectionTimeoutMillis
```
public MemcacheClientBuilder<V> withConnectionTimeoutMillis(long timeoutMillis)
```
    Set the maximum time to wait before considering the connection to be dead and should be closed and recreated.
    Do not use this to enforce request timeouts. Instead, set a timeout on the request futures using orTimeout() or some other manual mechanism.
    
    Parameters:
    
    timeoutMillis - The timeout in milliseconds. The default is 3000 ms.
    
    Returns:
    
    itself
  - withMaxSetLength
```
public MemcacheClientBuilder<V> withMaxSetLength(int maxSetLength)
```
    Set the maximum value size for set requests. If the limit is exceeded the set operation will fast-fail with a VALUE_TOO_LARGE status.
    If this limit is set higher than the actual limit in the memcache service, the memcache service may return a SERVER_ERROR which will close the connection to prevent any corrupted state.
    The default value is 1 MiB
    
    Parameters:
    
    maxSetLength - The maximum size in bytes
    
    Returns:
    
    itself
  - withEventLoopGroup
```
public MemcacheClientBuilder<V> withEventLoopGroup(io.netty.channel.EventLoopGroup eventLoopGroup)
```
    Set an Netty EventLoopGroup for the client.
    If not specified, an event loop group will be created, with default thread count.
    
    Parameters:
    
    eventLoopGroup - an event loop group instance
    
    Returns:
    
    itself
  - withChannelClass
```
public MemcacheClientBuilder<V> withChannelClass(java.lang.Class<? extends io.netty.channel.Channel> channelClass)
```
    Set a Netty Channel class for the client.
    If not specified, it'll use a Channel class, according to the EventLoopGroup in use.
    
    Parameters:
    
    channelClass - a class of channel to use.
    
    Returns:
    
    itself
  - withMaxKeyLength
```
public MemcacheClientBuilder<V> withMaxKeyLength(int maxKeyLength)
```
    Set the maximum key length of the byte representation of the input string. The default value is 250, and the valid range is [0, 250]
    
    Parameters:
    
    maxKeyLength - The maximum key length in bytes
    
    Returns:
    
    itself
  - withUsernamePassword
```
public MemcacheClientBuilder<V> withUsernamePassword(java.lang.String username,
                                                     java.lang.String password)
```
    Authenticate with memcached using plaintext SASL. This only works for binary connections, not ascii.
    You may call this multiple times, to set multiple authentication attempts. This is typically only useful during a password rotation to avoid downtime.
    
    Parameters:
    
    username -
    
    password -
    
    Returns:
    
    itself
  - withoutAuthenticationValidation
```
MemcacheClientBuilder<V> withoutAuthenticationValidation()
```
    Disable authentication validation - only useful for tests against jmemcached which does not support binary NOOP
    
    Returns:
    
    itself
  - connectBinary
```
public BinaryMemcacheClient<V> connectBinary()
```
    Create a client that uses the binary memcache protocol.
    
    Returns:
    
    a BinaryMemcacheClient
  - getAuthenticator
```
private Authenticator getAuthenticator(Authenticator defaultValue)
```
  - connectAscii
```
public AsciiMemcacheClient<V> connectAscii()
```
    Create a client that uses the ascii memcache protocol.
    
    Returns:
    
    a AsciiMemcacheClient
  - connectRaw
```
protected RawMemcacheClient connectRaw(boolean binary,
                                       Authenticator authenticator)
```
    Connect a raw memcached client without any protocol specific methods. This should rarely be needed.
    
    Parameters:
    
    binary - whether to use the binary protocol or not.
    
    Returns:
    
    A raw memcached client.
  - createClients
```
private java.util.List<RawMemcacheClient> createClients(java.util.List<HostAndPort> addresses,
                                                        boolean binary,
                                                        Authenticator authenticator)
```
  - createResolvingClient
```
private RawMemcacheClient createResolvingClient(boolean binary,
                                                Authenticator authenticator)
```
  - createClient
```
private RawMemcacheClient createClient(HostAndPort address,
                                       boolean binary,
                                       Authenticator authenticator)
```
  - createReconnectingClient
```
private RawMemcacheClient createReconnectingClient(HostAndPort address,
                                                   boolean binary,
                                                   Authenticator authenticator)
```

Class MemcacheClientBuilder<V>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_MAX_SET_LENGTH

DEFAULT_MAX_OUTSTANDING

DEFAULT_HOSTNAME

DEFAULT_PORT

DEFAULT_REPLY_EXECUTOR

DEFAULT_SCHEDULED_EXECUTOR

addresses

maxOutstandingRequests

batchSize

valueTranscoder

metrics

tracer

backoffFunction

connections

retry

executor

charset

resolver

srvResolver

srvRecord

resolveRefreshPeriod

shutdownDelay

connectionTimeoutMillis

maxSetLength

maxKeyLength

eventLoopGroup

channelClass

passwords

skipAuth

Constructor Detail

MemcacheClientBuilder

Method Detail

newByteArrayClient

newStringClient

newStringClient

newSerializableObjectClient

withKeyCharset

withAddress

withAddress

withResolver

updateResolver

withSRVRecord

withResolveRefreshPeriod

withSRVRefreshPeriod

withResolveShutdownDelay

withSRVShutdownDelay

withSrvResolver

withMetrics

withTracer

withMaxOutstandingRequests

withRequestBatchSize

withBackoff

withRetry

withReplyExecutor

withConnections

withRequestTimeoutMillis

withConnectionTimeoutMillis

withMaxSetLength

withEventLoopGroup

withChannelClass

withMaxKeyLength

withUsernamePassword

withoutAuthenticationValidation

connectBinary

getAuthenticator

connectAscii

connectRaw

createClients

createResolvingClient

createClient

createReconnectingClient