# parthpatel/java-memcached-client architecture

> Architecture diagram of the GitHub repository parthpatel/java-memcached-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parthpatel/java-memcached-client
- Repository: https://github.com/parthpatel/java-memcached-client

## Overview

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: [`src/main/java/net/spy/memcached/MemcachedClient.java`](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedClient.java) (MemcachedClient), [`src/main/java/net/spy/memcached/MemcachedConnection.java`](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedConnection.java) (Connection), [`src/main/java/net/spy/memcached/ops/Operation.java`](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/ops/Operation.java) (Operations), [`src/main/java/net/spy/memcached/MemcachedNode.java`](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedNode.java) (MemcachedNode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core client"]
  node_memcached_client["MemcachedClient<br/>public API"]
  node_client_if["Client IF<br/>contract"]
  node_connection["Connection<br/>orchestrator"]
  node_node_locator["Node Locator<br/>routing<br/>[NodeLocator.java]"]
  node_connection_factory["Conn Factory<br/>config"]
  node_memcached_node["MemcachedNode<br/>node abstraction<br/>[MemcachedNode.java]"]
  node_ops["Operations<br/>request model<br/>[Operation.java]"]
  node_internal_futures["Futures<br/>async completion"]
  node_hashing["Hashing"]
end

subgraph group_protocols["Protocols"]
  node_ascii_proto["ASCII<br/>protocol impl"]
  node_binary_proto["Binary<br/>protocol impl"]
end

subgraph group_support["Support"]
  node_transcoders["Transcoders<br/>data format<br/>[Transcoder.java]"]
  node_auth["SASL Auth<br/>extension"]
  node_tap["TAP<br/>streaming extension<br/>[TapClient.java]"]
  node_metrics["Metrics<br/>runtime telemetry"]
  node_logging["Logging<br/>compat layer<br/>[Logger.java]"]
  node_spring["Spring Bean<br/>integration"]
  node_cache_map["Cache Map<br/>value cache<br/>[CacheMap.java]"]
end

node_client_if -->|"implemented by"| node_memcached_client
node_memcached_client -->|"uses"| node_connection
node_memcached_client -->|"issues"| node_ops
node_memcached_client -->|"serializes via"| node_transcoders
node_memcached_client -->|"returns"| node_internal_futures
node_connection -->|"configured by"| node_connection_factory
node_connection -->|"routes with"| node_node_locator
node_connection -->|"manages"| node_memcached_node
node_node_locator -->|"hashes keys"| node_hashing
node_ascii_proto -->|"implements"| node_ops
node_binary_proto -->|"implements"| node_ops
node_ascii_proto -->|"provides"| node_memcached_node
node_binary_proto -->|"provides"| node_memcached_node
node_ops -->|"completes through"| node_internal_futures
node_auth -->|"extends"| node_ops
node_tap -->|"streams via"| node_ops
node_metrics -->|"observes"| node_connection
node_logging -->|"supports"| node_connection
node_spring -->|"wires"| node_memcached_client
node_cache_map -->|"stores"| node_transcoders
node_cache_map -->|"supplements"| node_memcached_client

click node_memcached_client "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedClient.java"
click node_client_if "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedClientIF.java"
click node_connection "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedConnection.java"
click node_node_locator "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/NodeLocator.java"
click node_connection_factory "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/ConnectionFactory.java"
click node_memcached_node "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedNode.java"
click node_ops "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/ops/Operation.java"
click node_internal_futures "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/internal/ListenableFuture.java"
click node_hashing "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/DefaultHashAlgorithm.java"
click node_ascii_proto "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/protocol/ascii/AsciiOperationFactory.java"
click node_binary_proto "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/protocol/binary/BinaryOperationFactory.java"
click node_transcoders "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/transcoders/Transcoder.java"
click node_auth "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/auth/AuthDescriptor.java"
click node_tap "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/TapClient.java"
click node_metrics "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/metrics/MetricCollector.java"
click node_logging "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/compat/log/Logger.java"
click node_spring "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/spring/MemcachedClientFactoryBean.java"
click node_cache_map "https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/CacheMap.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_memcached_client,node_client_if,node_connection,node_node_locator,node_connection_factory,node_memcached_node,node_ops,node_internal_futures,node_hashing toneBlue
class node_ascii_proto,node_binary_proto toneAmber
class node_transcoders,node_auth,node_tap,node_metrics,node_logging,node_spring,node_cache_map toneMint
```

## Components

### Core client

Public API, connection orchestration, key routing, and asynchronous completion plumbing.

- [MemcachedClient](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedClient.java): public API · Main synchronous-looking client entry point for cache operations and advanced features. · `src/main/java/net/spy/memcached/MemcachedClient.java`
- [Client IF](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedClientIF.java): contract · Public client interface exposed to callers. · `src/main/java/net/spy/memcached/MemcachedClientIF.java`
- [Connection](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedConnection.java): orchestrator · Owns sockets, node health, dispatch, retries, and operation scheduling. · `src/main/java/net/spy/memcached/MemcachedConnection.java`
- [Node Locator](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/NodeLocator.java): routing · Selects the target server for a key using pluggable distribution strategies. · `src/main/java/net/spy/memcached/NodeLocator.java`
- [Conn Factory](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/ConnectionFactory.java): config · Builds connection behavior, node creation, and protocol choice. · `src/main/java/net/spy/memcached/ConnectionFactory.java`
- [MemcachedNode](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/MemcachedNode.java): node abstraction · Represents a server endpoint managed by the connection layer. · `src/main/java/net/spy/memcached/MemcachedNode.java`
- [Operations](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/ops/Operation.java): request model · Protocol-agnostic operation interfaces, states, callbacks, and statuses. · `src/main/java/net/spy/memcached/ops/Operation.java`
- [Futures](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/internal/ListenableFuture.java): async completion · Listenable futures and callbacks bridging network completion to return values. · `src/main/java/net/spy/memcached/internal/ListenableFuture.java`
- [Hashing](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/DefaultHashAlgorithm.java): key 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](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/protocol/ascii/AsciiOperationFactory.java): protocol impl · ASCII wire protocol implementation with its own node and operation factory. · `src/main/java/net/spy/memcached/protocol/ascii/AsciiOperationFactory.java`
- [Binary](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/protocol/binary/BinaryOperationFactory.java): protocol impl · 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](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/transcoders/Transcoder.java): data format · Converts Java objects to and from cached bytes and special numeric forms. · `src/main/java/net/spy/memcached/transcoders/Transcoder.java`
- [SASL Auth](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/auth/AuthDescriptor.java): extension · Authentication support layered onto the shared operation pipeline. · `src/main/java/net/spy/memcached/auth/AuthDescriptor.java`
- [TAP](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/TapClient.java): streaming extension · TAP request/response messages and client support for streaming feeds. · `src/main/java/net/spy/memcached/TapClient.java`
- [Metrics](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/metrics/MetricCollector.java): runtime telemetry · Metric collection hooks for client runtime behavior. · `src/main/java/net/spy/memcached/metrics/MetricCollector.java`
- [Logging](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/compat/log/Logger.java): compat layer · Backend-agnostic logging facade used by the core client. · `src/main/java/net/spy/memcached/compat/log/Logger.java`
- [Spring Bean](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/spring/MemcachedClientFactoryBean.java): integration · Spring factory bean for wiring the client into application contexts. · `src/main/java/net/spy/memcached/spring/MemcachedClientFactoryBean.java`
- [Cache Map](https://github.com/parthpatel/java-memcached-client/blob/master/src/main/java/net/spy/memcached/CacheMap.java): value cache · Local cache/map abstractions used to track cached data and loading behavior. · `src/main/java/net/spy/memcached/CacheMap.java`

## Connections

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