Couchbase JVM Clients
This repository contains the third generation of the Couchbase SDKs on the JVM ("SDK 3").
This repository contains the following projects:
core-io: the foundational library for all language bindings
java-client: the Java language binding
scala-client: the Scala language binding
tracing-opentracing: module to integrate with OpenTracing
tracing-opentelemetry: module to integrate with OpenTelemetry tracing
metrics-opentelemetry: module to integrate with OpenTelemetry metrics
metrics-micrometer: module to integratr with Micrometer metrics
Other toplevel modules might be present which contain examples, experimental code or internal tooling and test infrastructure.
Stable releases are published on maven central.
<dependencies> <dependency> <groupId>com.couchbase.client</groupId> <artifactId>java-client</artifactId> <version>3.2.4</version> </dependency> </dependencies>
<dependencies> <dependency> <groupId>com.couchbase.client</groupId> <artifactId>scala-client_2.12</artifactId> <version>1.2.4</version> </dependency> </dependencies>
or if you use sbt:
libraryDependencies += "com.couchbase.client" %% "scala-client" % "1.2.4"
You can always also just build it from source:
$ git clone https://github.com/couchbase/couchbase-jvm-clients.git $ cd couchbase-jvm-clients $ make
Yes, we need
make because maven doesn't support the setup we need and neither does gradle. If you
want to build for different Scala versions, after the first
make you can do this through:
$ ./mvnw -D"scala.compat.version=2.13" -D"scala.compat.library.version=2.13.7" clean install $ ./mvnw -D"scala.compat.version=2.11" -D"scala.compat.library.version=2.11.12" clean install
- The two
mvnruns are to cross-compile the Scala SDK for Scala 2.11, and 2.13
- Couchbase only officially provides, tests and supports a Scala 2.12 build. Our community kindly added the capability to create builds for Scala 2.11 and 2.13, and users are of course welcome to create such builds; but Couchbase cannot provide support for them.
- When building for Scala 2.11, JDK 8 should be used. If JDK 11 is used then goal scala:doc-jar will fail
scala.compat.X properties are defined in file [.mvn/maven.config]
- You can always go into one of the sub-directories like
core-ioto only build or test an individual project:
cd scala-client ../mvnw -DskipTests clean install
-DskipTeststo skip testing.
You can test like this:
$ ./mvnw clean test -fae
Branches & Release Trains
Since this monorepo houses different versions of different artifacts, release train names have been chosen to identify a collection of releases that belong to the same train.
These trains are named after historic computers for your delight.
Tags in each branch are named
branchname-ga for the initial GA release, and then subsequently
each service release. See the tag information for specifics of what's in there.
- Colossus (Initial Release 2020-01-10)
- Pegasus (Initial Release 2020-12-02)
- Hopper (Initial Release 2021-07-20)
To cover all tests, the suite needs to be run against the following topologies, but by default it runs against the mock. Recommended topologies:
- 1 node, no replica
- 2 nodes, 1 replica
- 2 nodes, 2 replicas
Also to have maximum service coverage use a cluster which has all services enabled (can be MDS setup).
Documentation will be built automatically by the
mvn install command above.
According to the Maven standard, the file is named artifact-version-javadoc.jar (i.e. java-client-3.0.4-javadoc.jar).
This file can be extracted (jars are like zip files) with the following command:
jar xvf java-client-3.0.4-javadoc.jar
This will extract the contents of the javadoc file into the current directory. After the original jar is removed it can be uploaded to s3.
The location of the javadoc files depends on where you get it from. The easiest is, once published, from Maven central. For example, look it up on Maven central: https://search.maven.org/artifact/com.couchbase.client/java-client/3.0.4/jar and download the javadoc jar: https://search.maven.org/remotecontent?filepath=com/couchbase/client/java-client/3.0.4/java-client-3.0.4-javadoc.jar
The exact same approach can be used for any artifact, including Scala. The Scala documentation can also be built with this command:
cd scala-client && mvn scala:doc
Scala code is automatically formatted on compile with the tool
scalafmt. To make IntelliJ use the same settings:
Editor -> Code Style -> Scala, change formatter to scalafmt and check Reformat on file save
mvn validate can be used from command-line to force reformat)