Package com.couchbase.client.core

Couchbase Core IO - Domain Model and Architecture

See: Description

Interface Summary

Interface	Description
ClusterFacade	Represents a Couchbase Cluster.
OriginalMutationResult	Represents mutation metadata which can be inspected after a mutation and during/after is respective observe poll cycles.

Class Summary

Class	Description
CoreContext	The CoreContext contains required assets which are shared on a per-core basis.
CouchbaseCore	The general implementation of a ClusterFacade.
RequestEvent	A pre allocated event which carries a CouchbaseRequest and associated information.
RequestEventFactory	A factory to preallocate RequestEvents.
RequestHandler	The RequestHandler is responsible for adding and removing Nodes as well as dispatching Service management operations.
ResponseEvent	A pre allocated event which carries a CouchbaseResponse and associated information.
ResponseEventFactory	A factory to preallocate ResponseEvents.
ResponseHandler

Exception Summary

Exception	Description
BackpressureException	Identifies the need to back off on the supplier side when using a service, because the consumer is overloaded.
BucketClosedException	A RuntimeException being thrown whenever an operation on a bucket that has been closed is attempted.
CouchbaseException	Common parent exception to build a proper exception hierachy inside the driver.
DocumentConcurrentlyModifiedException	Exception indicating that the document which is observed has been modified in the meantime.
DocumentMutationLostException	The observed document was lost during a hard failover, because the document did not reach the replica in time.
ReplicaNotAvailableException	This exception is thrown when the given operation targeting a specific replica is not fulfillable because the replica is not available (the node has been failed over or is marked as down).
ReplicaNotConfiguredException	This exception is thrown when the given operation targeting a specific replica is not fulfillable because the replica is not configured (for example replica 2 is asked for, but only 1 is configured).
RequestCancelledException	This exception is thrown when there is a problem in the underlying network I/O.
ServiceNotAvailableException	Exception which states that the service is not available for the bucket.

Package com.couchbase.client.core Description

Couchbase Core IO - Domain Model and Architecture

This documentation describes the domain model of the core package, covers important architecture and design decisions and provides a solid introduction on the inner workings. For more detailed descriptions on the individual components, see the package documentation for the corresponding package.

Domain Model

The domain model of the application is inspired by DDD (Domain Driven Design) and is intended to clearly reflect the domain language of a database client library. There are a few crucial components which need proper definition, so here they are. Afterwards, they are discussed in context:

• Channel: A Channel is the socket abstraction provided by the Netty framework. It handles all the underlying raw input and output communication.
• Endpoint: A Endpoint wraps a Channel and is, as far as the upper layers are concerned the most atomic receiver of a request. It eventually pushes the request into the channel if it is connected and able to serve it properly. Endpoints always serve a special purpose, for example they only handle view requests, query requests or binary requests.
• Service: A Service contains 1 to N Endpoints. Its state is always a culmination of all owned Endpoint states. When it receives a request, it dispatches it - based on a strategy - into one Endpoint. As an endpoint, a Service only handles a special type of requests (view, query, binary,…).
• Node: A Node is the logical equivalent of a Node in a Couchbase Server cluster. It has many Services attached to it, but not every node needs to have all the same Services.

Here is a simplified diagram that shows the tree-like relations:

Request/Response flow

The actual implementation is a little more complicated since some parts have been left out in the simplified illustration. Especially the RingBuffers play an important role in the architecture. The following diagram shows a more complete picture, explanation afterwards.

Dependencies

Two dependencies are most crucial contributors to the current architecture:

• Netty: Netty by far is currently the most scalable and performing IO library available on the JVM. We are utilizing for all IO traffic and by doing that we can use a central event loop pool and manage resources very efficiently. It also provides built-in support for functionality like SSL, compression and others, so we do not need to reinvent the wheel all the time.
• RxJava: Since the earliest days, the Java SDK did provide asynchronous interfaces, but the Future shipped with the JDK is broken and does not provide enough flexibility. The reactive extensions (where RxJava is the canonical JVM implementation) provide a very feature rich set of asynchronous programming flow. Since it also provides blocking fallback semantics, we can ship the best of both worlds, both internally and externally facing to the SDK user.

Other runtime dependencies are:

• LMAX Disruptor: The Disruptor is the fastest RingBuffer implementation available on the JVM and used in many latency-sensitive applications. Internally, it is used to shed load and provide backpressure on both the request and response side, helping with implicit batching and proper release valves in case the system is overloaded.
• Typesafe Config: A very versatile config library, with no dependencies on its own. It has a well-thought dependency management system and easily accessible syntax both across system properties and config files.
• Jackson: One of the most versatile and fast JSON frameworks out there, widely used.

Finally, we use the following dependencies for unit, integration and performance tests:

• JUnit: Classic unit testing framework.
• OpenJDK JMH: The one and only sane choice when it comes to performance testing for predictable and JVM compliant results.
• Logback: Powerful logging framework used for tests together with SLF4J.
• Mockito: A flexible mocking framework.

Since:

1.0

Author:

Michael Nitschinger