Skip to content
Java client for working with etcd's v2 REST API
Java
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
config
gradle
src
.editorconfig
.gitattributes
.gitignore
.travis.yml
CONTRIBUTING.md
LICENSE.txt
README.md
RELEASE_NOTES.md
build.gradle
gradle.properties
gradlew
gradlew.bat
settings.gradle

README.md

** As of 12/20/2016 this project is in legacy mode. Version 1.0.0 is intended to be the final release unless any bugs are reported. There are currently no plans in-flight to support the v3 api though I might pick up that work at sometime in the future, time permitting of course. If anyone wants to take on the work to support the v3 api I would be more than happy to help and mentor.

Build Status Download

etcd-rest

alt tag

java client, based on jclouds, to interact with Etcd's v2 REST API.

Setup and How to use

Client's can be built like so:

  EtcdClient client = EtcdClient.builder()
  .endPoint("http://127.0.0.1:2379") // Optional. Defaults to http://127.0.0.1:2379
  .credentials("admin:password") // Optional.
  .build();

  Key createdKey = client.api().keysApi().createKey("keyName", "keyValue");

Latest release

Can be sourced from jcenter like so:

<dependency>
  <groupId>com.cdancy</groupId>
  <artifactId>etcd-rest</artifactId>
  <version>1.0.0</version>
  <classifier>sources|javadoc|all</classifier> (Optional)
</dependency>

Documentation

javadocs can be found via github pages here

Property based setup

Client's do NOT need supply the endPoint or credentials as part of instantiating the EtcdClient object. Instead one can supply them through system properties, environment variables, or a combination of the 2. System properties will be searched first and if not found we will attempt to query the environment.

Setting the endpoint can be done with any of the following (searched in order):

  • etcd.rest.endpoint
  • etcdRestEndpoint
  • ETCD_REST_ENDPOINT
  • ETCD_LISTEN_CLIENT_URLS (first in list that is reachable will be used)
  • ETCD_ADVERTISE_CLIENT_URLS (first in list that is reachable will be used)

Setting the credentials can be done with any of the following (searched in order):

  • etcd.rest.credentials
  • etcdRestCredentials
  • ETCD_REST_CREDENTIALS

Credentials

etcd-rest credentials can take 1 of 2 forms:

  • Colon delimited username and password: admin:password
  • Base64 encoded username and password: YWRtaW46cGFzc3dvcmQ=

Understanding ErrorMessage

Instead of throwing an exception most objects will have an attached ErrorMessage. It is up to the user to check the handed back object to see if the ErrorMessage is non-null before proceeding.

The message attribute of ErrorMessage is what etcd hands back to us when something fails. In some cases the message may be expected (e.g. Key already exists) and in others not (e.g. User HelloWorld already exists). Using the example above one might proceed like this:

  Key createdKey = client.api().keysApi().createKey("keyName", "keyValue");
  if (createdKey.errorMessage() != null) {
  
      // at this point we know something popped on the server-side.
      // now decide whether we care or not.
      if (createdKey.errorMessage().message().contains("Key already exists")) {
          // ignore 
      } else {
          throw new Exception("Unexpected error: " + createdKey.errorMessage().message());
      }
  }

Examples

The mock and live tests provide many examples that you can use in your own code.

Components

  • jclouds - used as the backend for communicating with Etcd's REST API
  • AutoValue - used to create immutable value types both to and from the etcd program

Testing

Running mock tests can be done like so:

./gradlew clean build mockTest

Running integration tests can be done like so (requires docker):

./gradlew clean build integTest

Running integration tests without invoking docker can be done like so:

./gradlew clean build integTest -PbootstrapDocker=false -PtestEtcdEndpoint=http://127.0.0.1:2379 

Projects leveraging this library

Additional Resources

You can’t perform that action at this time.