How naver/arcus-java-client works
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