JarCastingjetcd - A Java Client for etcd
jetcd is the official java client for etcd v3.
Note: jetcd is work-in-progress and may break backward compatibility.
Java Versions
Java 8 or above is required.
Download
Maven
<dependency>
<groupId>io.etcd</groupId>
<artifactId>jetcd-core</artifactId>
<version>${jetcd-version}</version>
</dependency>
Development snapshots are available in Sonatypes's snapshot repository.
Gradle
dependencies {
compile "io.etcd:jetcd-core:$jetcd-version"
}
Usage
// create client
Client client = Client.builder().endpoints("http://localhost:2379").build();
KV kvClient = client.getKVClient();
ByteSequence key = ByteSequence.from("test_key".getBytes());
ByteSequence value = ByteSequence.from("test_value".getBytes());
// put the key-value
kvClient.put(key, value).get();
// get the CompletableFuture
CompletableFuture<GetResponse> getFuture = kvClient.get(key);
// get the value from CompletableFuture
GetResponse response = getFuture.get();
// delete the key
kvClient.delete(key).get();
For full etcd v3 API, plesase refer to the official API documentation.
Examples
The examples are standalone projects that show usage of jetcd.
Launcher
The io.etcd:jetcd-test offers a convenient utility to programmatically start & stop an isolated etcd server. This can be very useful e.g. for integration testing, like so:
import io.etcd.jetcd.Client;
import io.etcd.jetcd.launcher.EtcdCluster;
import io.etcd.jetcd.test.EtcdClusterExtension;
import org.junit.jupiter.api.extension.RegisterExtension;
@RegisterExtension static final EtcdCluster etcd = new EtcdClusterExtension("test-etcd", 1);
Client client = Client.builder().endpoints(etcd.getClientEndpoints()).build();
This launcher uses the Testcontainers framework. For more info and prerequisites visit testcontainers.org.
Versioning
The project follows Semantic Versioning.
The current major version is zero (0.y.z). Anything may change at any time. The public API should not be considered stable.
Build from source
The project can be built with Apache Maven:
mvn clean install -DskipTests
Running tests
The project is tested against a three node etcd setup started with the Launcher (above) :
$ mvn test
...
[INFO] T E S T S
[INFO] -------------------------------------------------------
[INFO] Running TestSuite
[WARNING] Tests run: 104, Failures: 0, Errors: 0, Skipped: 3, Time elapsed: 31.308 s - in TestSuite
[INFO]
[INFO] Results:
[INFO]
[WARNING] Tests run: 104, Failures: 0, Errors: 0, Skipped: 3
...
[INFO] Reactor Summary:
[INFO]
[INFO] jetcd .............................................. SUCCESS [ 0.010 s]
[INFO] jetcd-core ......................................... SUCCESS [ 55.480 s]
[INFO] jetcd-discovery-dns-srv ............................ SUCCESS [ 3.225 s]
[INFO] jetcd-watch-example ................................ SUCCESS [ 0.291 s]
[INFO] jetcd-simple-ctl ................................... SUCCESS [ 0.028 s]
[INFO] jetcd-examples ..................................... SUCCESS [ 0.000 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 59.929 s
[INFO] Finished at: 2018-02-13T12:51:13-08:00
[INFO] Final Memory: 84M/443M
Troubleshooting
It recommmonds building the project before running tests so that you have artifacts locally. It will solve some problems if the latest snapshot hasn't been uploaded or network issues.
Contact
- Mailing list: etcd-dev
- IRC: #etcd on freenode.org
Contributing
See CONTRIBUTING for details on submitting patches and the contribution workflow.
Reporting bugs
See reporting bugs for details about reporting any issues.
License
jetcd is under the Apache 2.0 license. See the LICENSE file for details.
