# naver/arcus-java-client architecture

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

- Interactive diagram: https://gitdiagram.com/naver/arcus-java-client
- Repository: https://github.com/naver/arcus-java-client

## Overview

##### Project type and purpose
- This is an open-source Java client library (“arcus-java-client”) for interacting with an Arcus memcached cloud.
- It extends spymemcached with collection data types (List, Set, Map, B+Tree) and ZooKeeper-based clustering and service discovery.

##### File structure
- Top-level:
- src/main/java/net/spy/memcached – core client implementation, broken into logical subsystems (auth, collection, compat, internal, ops, protocol, plugin, transcoders, util).
- src/test/java / src/test/manual – unit and manual integration tests.
- docs, xdocs – user guide and reference.
- pom.xml, buildfile, devtools – build & CI.
- No frontend; it’s a library.
- Configuration: ZooKeeper (external), Memcached servers (external), connection factory builders, logging.

##### Key insights from README
- Supports JDK 1.6+ (runtime), 1.8+ (build).
- Maven artifact, user guide references.
- Uses ZooKeeper for cluster config under /arcus znode hierarchy.
- Requires local Arcus memcached + ZooKeeper for tests.

a. User Application
b. Arcus Java Client Library
– API layer (ArcusClientIF, ArcusClient, ArcusClientPool)
– ConnectionFactory & Builder (DefaultConnectionFactory, KetamaConnectionFactory, BinaryConnectionFactory)
– NodeLocator strategies (KetamaNodeLocator, ArrayModNodeLocator)
– Operation subsystem (OperationFactory, Operation, OperationCallback, OperationFuture)
– Protocol encoders/decoders (ascii & binary packages, TCPMemcachedNodeImpl)
– Transcoders (SerializingTranscoder, IntegerTranscoder, CollectionTranscoder, …)
– Collection data-type modules (list, set, map, btree under collection/)
– Plugin: FrontCache (optional local cache layer)
– ZooKeeper client integration (ArcusMBeanServer, ZooKeeper watchers in util or internal)
c. External Services
– ZooKeeper ensemble
– Arcus/Memcached cluster (one or more memcached nodes)
d. (Optional) JMX/MBean server for monitoring

##### Relationships & interactions
- User App calls API layer → ArcusClient
- ArcusClient uses ZooKeeper client to fetch cluster topology → NodeLocator
- API calls translated to Operation objects via OperationFactory
- Protocol layer serializes operations → sends over TCP to Memcached servers
- Responses parsed into OperationFuture / GetFuture, etc., then returned to application
- Transcoders handle object → byte[] conversion in both directions
- Plugin front-cache intercepts get/put if enabled, falls back to network
- All components coordinate via ConnectionFactory (create/monitor connections)

##### Architectural patterns & design principles
- Layered architecture: API → core logic → protocol → transport
- Strategy Pattern: pluggable NodeLocator, Transcoder, AuthDescriptor
- Builder Pattern: ConnectionFactoryBuilder for custom configurations
- Asynchronous programming: OperationFuture, callbacks, internal futures
- Adapter & Factory: protocol implementation factories for ascii/binary
- Observer/Listener: ConnectionObserver, AuthThreadMonitor, ZooKeeper watchers
- Plugin: FrontCacheMemcachedClient extends base client

##### Technologies & frameworks
- Java 1.6+ / 1.8+
- ZooKeeper for service discovery
- TCP sockets for Memcached binary/ASCII protocol
- Maven for build/test
- JUnit/TestNG for unit & integration tests
- Checkstyle for code quality
- JMX (ArcusMBeanServer) for management

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    UA["User Application"]:::external

    %% API Layer
    subgraph "API Layer"
        AIF["ArcusClientIF"]:::core
        AC["ArcusClient"]:::core
        ACP["ArcusClientPool"]:::core
    end

    %% Connection & Node Locator
    subgraph "Connection & Node Locator"
        CFB["ConnectionFactoryBuilder"]:::core
        DCF["DefaultConnectionFactory"]:::core
        KCF["KetamaConnectionFactory"]:::core
        BCF["BinaryConnectionFactory"]:::core

        subgraph "NodeLocator Strategies"
            KNL["KetamaNodeLocator"]:::core
            AML["ArrayModNodeLocator"]:::core
            AKL["ArcusKetamaNodeLocator"]:::core
        end
    end

    %% Operation Subsystem
    subgraph "Operation Subsystem"
        OF["OperationFactory"]:::core
        OI["Operation"]:::core
        OC["OperationCallback"]:::core
        OFut["OperationFuture"]:::core
        GFut["GetFuture"]:::core
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        TCPN["TCPMemcachedNodeImpl"]:::core
        subgraph "ASCII Protocol"
            ASN["AsciiMemcachedNodeImpl"]:::core
            ASOF["AsciiOperationFactory"]:::core
        end
        subgraph "Binary Protocol"
            BNM["BinaryMemcachedNodeImpl"]:::core
            BNOF["BinaryOperationFactory"]:::core
        end
    end

    %% Transcoders
    subgraph "Transcoders"
        ST["SerializingTranscoder"]:::core
        IT["IntegerTranscoder"]:::core
        CT["CollectionTranscoder"]:::core
        BST["BaseSerializingTranscoder"]:::core
    end

    %% Collection Modules
    subgraph "Collection Data-Type Modules"
        CM["collection/"]:::core
    end

    %% Plugin
    subgraph "Plugin (FrontCache)"
        FC["FrontCacheMemcachedClient"]:::plugin
        FCG["FrontCacheGetFuture"]:::plugin
        FCBG["FrontCacheBulkGetFuture"]:::plugin
        LCM["LocalCacheManager"]:::plugin
    end

    %% Utils & Monitoring
    subgraph "Utilities & Monitoring"
        MB["ArcusMBeanServer"]:::util
        AKC["ArcusKetamaNodeLocatorConfiguration"]:::util
        ARKC["ArcusReplKetamaNodeLocatorConfiguration"]:::util
        BTU["BTreeUtil"]:::util
        CL["CacheLoader"]:::util
        AU["AddrUtil"]:::util
        CO["ConnectionObserver"]:::util
    end

    %% External Services
    ZK["ZooKeeper Ensemble"]:::external
    MC["Arcus/Memcached Cluster"]:::external

    %% Flow
    UA -->|calls API| AIF
    AIF -->|implemented by| AC
    UA -->|calls| AC
    AC -->|uses builder| CFB
    CFB -->|builds| DCF
    CFB -->|builds| KCF
    CFB -->|builds| BCF
    AC -->|uses locator| AKL
    ZK -->|"ZK Watchers"| AKL
    AKL -->|locator strategy| KNL
    AKL -->|locator strategy| AML

    AC -->|createOperation| OF
    OF -->|produces| OI
    OI -->|with callback| OC
    OI -->|returns future| OFut
    OFut --> GFut

    %% Protocol flow
    OFut -->|serialize/deserialize| ST
    ST -->|uses| BST
    ST --> IT
    ST --> CT

    OF -->|translate to protocol ops| ASOF
    ASOF --> ASN
    OF -->|translate to protocol ops| BNOF
    BNOF --> BNM
    ASN --> TCPN
    BNM --> TCPN
    TCPN -->|TCP| MC
    MC -->|response| TCPN
    TCPN -->|parse| OFut

    %% Plugin flow
    UA -->|optional plugin| FC
    FC -->|on miss/fallback| AC
    FC --> FCG
    FC --> FCBG
    FC --> LCM

    %% Utilities
    CO --> AC
    CL --> CT
    AU --> DCF
    BTU --> CM
    AKC --> AKL
    ARKC --> AKL
    AC --> MB

    %% Click Events
    click AIF "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ArcusClientIF.java"
    click AC "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ArcusClient.java"
    click ACP "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ArcusClientPool.java"
    click CFB "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ConnectionFactoryBuilder.java"
    click DCF "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/DefaultConnectionFactory.java"
    click KCF "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/KetamaConnectionFactory.java"
    click BCF "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/BinaryConnectionFactory.java"
    click KNL "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/KetamaNodeLocator.java"
    click AML "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ArrayModNodeLocator.java"
    click AKL "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ArcusKetamaNodeLocator.java"
    click OF "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/OperationFactory.java"
    click OI "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ops/Operation.java"
    click OC "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ops/OperationCallback.java"
    click OFut "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/internal/OperationFuture.java"
    click GFut "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/internal/GetFuture.java"
    click TCPN "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/protocol/TCPMemcachedNodeImpl.java"
    click ASN "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/protocol/ascii/AsciiMemcachedNodeImpl.java"
    click ASOF "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/protocol/ascii/AsciiOperationFactory.java"
    click BNM "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/protocol/binary/BinaryMemcachedNodeImpl.java"
    click BNOF "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/protocol/binary/BinaryOperationFactory.java"
    click ST "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/transcoders/SerializingTranscoder.java"
    click IT "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/transcoders/IntegerTranscoder.java"
    click CT "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/transcoders/CollectionTranscoder.java"
    click BST "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/transcoders/BaseSerializingTranscoder.java"
    click CM "https://github.com/naver/arcus-java-client/tree/master/src/main/java/net/spy/memcached/collection"
    click FC "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/plugin/FrontCacheMemcachedClient.java"
    click FCG "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/plugin/FrontCacheGetFuture.java"
    click FCBG "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/plugin/FrontCacheBulkGetFuture.java"
    click LCM "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/plugin/LocalCacheManager.java"
    click MB "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ArcusMBeanServer.java"
    click AKC "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/util/ArcusKetamaNodeLocatorConfiguration.java"
    click ARKC "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/util/ArcusReplKetamaNodeLocatorConfiguration.java"
    click BTU "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/util/BTreeUtil.java"
    click CL "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/util/CacheLoader.java"
    click AU "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/util/AddrUtil.java"
    click CO "https://github.com/naver/arcus-java-client/blob/master/src/main/java/net/spy/memcached/ConnectionObserver.java"

    %% Styles
    classDef core fill:#D6E8FF,stroke:#00529B
    classDef external fill:#DFF2BF,stroke:#4F8A10
    classDef plugin fill:#FFF4BD,stroke:#9F6000
    classDef util fill:#F0F0F0,stroke:#888888
```
