How parthpatel/java-memcached-client works
1. This repository is a Java client library for Memcached, not a server. The core runtime is the net.spy.memcached package, which exposes a synchronous-looking API backed by asynchronous network operations over TCP.
2. The main entry point is MemcachedClient, with MemcachedClientIF defining the public contract. Callers use this layer for cache operations such as get, set, delete, CAS, touch, stats, and more advanced replica/observe/TAP functions.
3. Under the client API is the connection orchestration layer: MemcachedConnection, MemcachedNode, NodeLocator, and ConnectionFactory. This layer owns socket lifecycle, node health, operation dispatch, and how requests are scheduled onto individual memcached servers.
4. Key distribution is handled by pluggable node locators and hash algorithms. The repo includes both classic modulo-based routing (ArrayModNodeLocator) and consistent-hashing/Ketama routing (KetamaNodeLocator, KetamaIterator, DefaultHashAlgorithm, HashAlgorithmRegistry). This is the boundary that decides which server owns a key.
5. The protocol layer is split cleanly between ASCII and binary implementations. protocol/ascii and protocol/binary each provide their own OperationFactory, node implementation, and concrete operation classes, while the shared ops package defines protocol-agnostic operation interfaces and statuses.
6. Operations are the central internal abstraction. Each request type—get, set, CAS, mutation, flush, stats, SASL auth, observe, TAP, etc.—is represented as an Operation with callback-driven completion. The protocol-specific implementations encode/decode wire messages and transition through OperationState until completion or error.
7. Results are delivered asynchronously through the internal future/callback stack. The internal package contains ListenableFuture, OperationFuture, GetFuture, BulkGetFuture, and listener types that bridge low-level socket completion into user-facing return values and timeouts.
8. Value serialization is separated from transport. The transcoders package handles conversion between Java objects and CachedData, including SerializingTranscoder, integer/long special cases, and compatibility transcoders like Whalin. This is the main data-format boundary between application objects and cache bytes.
9. Resilience and runtime behavior are first-class concerns. FailureMode, OperationTimeoutException, cancellation-related tests, retry/reconnect logic, and node observers shape how the client behaves when servers disappear, time out, or reconnect. Metrics support is also built in via metrics/MetricCollector implementations.
10. The library includes support for several Memcached ecosystem extensions: SASL authentication (auth, SASL operations), TAP streaming (TapClient, tapmessage), observe/replica reads, and Membase/Couchbase-specific behaviors. These features sit on top of the same connection and operation pipeline rather than separate subsystems.
11. There are integration points for application frameworks and logging. spring/MemcachedClientFactoryBean provides Spring wiring, while compat/log abstracts over logging backends such as SLF4J, Log4J, or the JDK logger so the core client does not depend on one logging stack.
12. Build and verification are centered around Java build tooling and server-backed tests. The project uses Ant as the primary build (build.xml), with Ivy and Maven descriptors present, and the tests are designed to run against configurable Memcached or Membase/Couchbase servers on IPv4/IPv6 addresses and custom ports.
Main entry points: MemcachedClient.java MemcachedClient · MemcachedConnection.java Connection · Operation.java Operations · MemcachedNode.java MemcachedNode
Components 18
Core client
Public API, connection orchestration, key routing, and asynchronous completion plumbing.
- MemcachedClient · Main synchronous-looking client entry point for cache operations and advanced features.
src/main/java/net/spy/memcached/MemcachedClient.java - Client IF · Public client interface exposed to callers.
src/main/java/net/spy/memcached/MemcachedClientIF.java - Connection · Owns sockets, node health, dispatch, retries, and operation scheduling.
src/main/java/net/spy/memcached/MemcachedConnection.java - Node Locator · Selects the target server for a key using pluggable distribution strategies.
src/main/java/net/spy/memcached/NodeLocator.java - Conn Factory · Builds connection behavior, node creation, and protocol choice.
src/main/java/net/spy/memcached/ConnectionFactory.java - MemcachedNode · Represents a server endpoint managed by the connection layer.
src/main/java/net/spy/memcached/MemcachedNode.java - Operations · Protocol-agnostic operation interfaces, states, callbacks, and statuses.
src/main/java/net/spy/memcached/ops/Operation.java - Futures · Listenable futures and callbacks bridging network completion to return values.
src/main/java/net/spy/memcached/internal/ListenableFuture.java - Hashing · Hash algorithms and Ketama support used by node routing.
src/main/java/net/spy/memcached/DefaultHashAlgorithm.java
Protocols
ASCII and binary protocol implementations layered over shared operations.
- ASCII · ASCII wire protocol implementation with its own node and operation factory.
src/main/java/net/spy/memcached/protocol/ascii/AsciiOperationFactory.java - Binary · Binary wire protocol implementation with its own node and operation factory.
src/main/java/net/spy/memcached/protocol/binary/BinaryOperationFactory.java
Support
Serialization, extensions, metrics, logging, and framework integration.
- Transcoders · Converts Java objects to and from cached bytes and special numeric forms.
src/main/java/net/spy/memcached/transcoders/Transcoder.java - SASL Auth · Authentication support layered onto the shared operation pipeline.
src/main/java/net/spy/memcached/auth/AuthDescriptor.java - TAP · TAP request/response messages and client support for streaming feeds.
src/main/java/net/spy/memcached/TapClient.java - Metrics · Metric collection hooks for client runtime behavior.
src/main/java/net/spy/memcached/metrics/MetricCollector.java - Logging · Backend-agnostic logging facade used by the core client.
src/main/java/net/spy/memcached/compat/log/Logger.java - Spring Bean · Spring factory bean for wiring the client into application contexts.
src/main/java/net/spy/memcached/spring/MemcachedClientFactoryBean.java - Cache Map · Local cache/map abstractions used to track cached data and loading behavior.
src/main/java/net/spy/memcached/CacheMap.java
Connections 21
- Client IF → MemcachedClient: implemented by · The concrete client fulfills the public contract.
- MemcachedClient → Connection: uses · Client calls are translated into queued network operations.
- MemcachedClient → Operations: issues · High-level cache methods are represented as operations.
- MemcachedClient → Transcoders: serializes via · Values cross the transport boundary through transcoders.
- MemcachedClient → Futures: returns · Many APIs complete through future-based async results.
- Connection → Conn Factory: configured by · Factory selects protocol, timeouts, and node behavior.
- Connection → Node Locator: routes with · Connections ask the locator which node owns a key.
- Connection → MemcachedNode: manages · The connection owns live node sockets and health.
- Node Locator → Hashing: hashes keys · Routing depends on pluggable hash algorithms and Ketama support.
- ASCII → Operations: implements · ASCII protocol encodes and decodes shared operations.
- Binary → Operations: implements · Binary protocol encodes and decodes shared operations.
- ASCII → MemcachedNode: provides · ASCII nodes manage ASCII-specific wire behavior.
- Binary → MemcachedNode: provides · Binary nodes manage binary-specific wire behavior.
- Operations → Futures: completes through · Operation callbacks feed the future/listener layer.
- SASL Auth → Operations: extends · SASL authentication is modeled as operations on the same pipeline.
- TAP → Operations: streams via · TAP messages ride on the shared operation and connection path.
- Metrics → Connection: observes · Metric collectors measure client runtime behavior.
- Logging → Connection: supports · Logging is used across the client and transport layers.
- Spring Bean → MemcachedClient: wires · Spring integration instantiates and configures the client.
- Cache Map → Transcoders: stores · Local cache abstractions hold transcoded values.
- Cache Map → MemcachedClient: supplements · Cache map utilities support client-side data management.