Class/Object

com.eiipii.etcd.client

EtcdClient

Related Docs: object EtcdClient | package client

Permalink

class EtcdClient extends AnyRef

Asynchronously sends HTTP requests to etcd servers and handles outcome responses.

EtcdClient

EtcdClient uses AsyncHttpClient in order to build and send HTTP requests. Its methods were developed to suit the etcd documentation. All methods use Scala Futures and Promises in order to provide an asynchronous implementation.

Depending on the request, either an error will be thrown or a response will be returned. In both cases, there is a case class extending a trait in package model with a name ending in Result, which will be returned containing either the response or information about the error.

For example, when performing an EtcdClient.setKey operation, an EtcdSetKeyResult is expected. The outcome of the operation, either an error or a response, can be accessed considering both cases. An easy way to retrieve a response could be with a match statement:

etcdcli.setKey(key, value) onSuccess  {
case EtcdSetKeyResponse(headers, body) =>
 ???
}
Key-Value Methods

The implementation of key-value methods follows the specification given in the etcd Client API. Their purpose is to set, retrieve, modify or delete keys, values and directories in etcd. It is also possible to wait (set a watch) on etcd keys, so as to monitor changes in the server in real time and conditionally set operations depending on the response obtained once a change in the data is registered.

Key-Value methods take as inputs case classes defined in package model. The recommended way of getting input data (EtcdKeys, EtcdDirectorys, hidden nodes and EtcdValues) for key-value methods is using the EtcdModel object.

Statistics

The implementation of methods for retrieving etcd cluster statistics also follows the specification given in the etcd Client API and etcd Admin API.

Authentication Methods

The implementation of authentication methods follows the specification given in the etcd authentication and security API. With the help of these methods, a system administrator can enable authentication and create users and roles with different levels of access to etcd. etcd only allows authentication on authentication methods and key-value methods.

Member Methods

The implementation for member methods follows the specification given in the etcd Members API. They allow an administrator to configure a cluster, by changing the members of a cluster.

Linear Supertypes
AnyRef, Any
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. EtcdClient
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Instance Constructors

  1. new EtcdClient(etcdConfig: EtcdConfiguration)

    Permalink

    etcdConfig

    EtcdConfiguration with information about an endpoint to which requests will be sent and optional authorization data.

Value Members

  1. final def !=(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int

    Permalink
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  4. def addMember(peerURLs: EtcdMemberForm): Future[EtcdAddMemberResult]

    Permalink

    Adds a member to an etcd cluster.

    Adds a member to an etcd cluster.

    Member methods

    Implemented according to etcd Members API: "Add a member".

    peerURLs

    EtcdMemberForm containing a list of strings representing the peer URLs of the new member.

    returns

    A Future wrapped around either EtcdAddMemberResponse or EtcdStandardError extending EtcdAddMemberResult.

  5. def addUpdateRole(role: EtcdRole): Future[EtcdAddUpdateRoleResult]

    Permalink

    Adds new roles and modifies role details.

    Adds new roles and modifies role details.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    role

    EtcdRole with details of the role to be created or updated.

    returns

    A Future wrapped around either EtcdAddUpdateRoleResponse or EtcdStandardError. extending EtcdAddUpdateRoleResult.

  6. def addUpdateUser(user: EtcdUserRequestForm): Future[EtcdAddUpdateUserResult]

    Permalink

    Adds new users and modifies user details.

    Adds new users and modifies user details.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    user

    EtcdUserRequestForm containing the details (login, password, granted and revoked permissions, and roles) to be updated for a given user.

    returns

    A Future wrapped around either EtcdAddUpdateUserResponse or EtcdStandardError. extending EtcdAddUpdateUserResult.

  7. final def asInstanceOf[T0]: T0

    Permalink
    Definition Classes
    Any
  8. def changePeerURLs(peerID: String, peerURLs: EtcdMemberForm): Future[EtcdConfirmationResult]

    Permalink

    Changes the peer urls of a member of an etcd cluster.

    Changes the peer urls of a member of an etcd cluster.

    Member methods

    Implemented according to etcd Members API: "Change the peer urls of a member".

    peerID

    A string identifying another member of the etcd cluster.

    peerURLs

    EtcdMemberForm containing a list of strings representing the new peer URLs that will replace the old ones.

    returns

    A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError extending EtcdConfirmationResult.

  9. def clone(): AnyRef

    Permalink
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  10. def close(): Unit

    Permalink

    Close the internal resources.

  11. def createDir(dir: EtcdDirectory, ttlOp: Option[EtcdTTL] = None): Future[EtcdCreateDirResult]

    Permalink

    Creates an empty directory in the specified path.

    Creates an empty directory in the specified path.

    Key-Value Method

    Implemented according to etcd Client API: "Creating Directories". See also "Using a directory TTL".

    One can also choose to create a directory by setting a key in it using EtcdClient.setKey.

    Optionally one can choose a TTL (time to live), which is a lifespan in seconds for the directory. When it expires, the directory is deleted. To update the TTL, use method EtcdClient.refreshDirTTL.

    dir

    EtcdDirectory to be created.

    ttlOp

    Life span in seconds of the directory. Defaults to None.

    returns

    A Future wrapped around either EtcdCreateDirResponse or EtcdRequestError extending EtcdCreateDirResult.

  12. def createKeyFromCurrentEtcdIndex(dir: EtcdDirectory, value: EtcdValue): Future[EtcdSetKeyResult]

    Permalink

    Creates a key in a specified directory whose name is the current etcd index preceded with leading zeroes.

    Creates a key in a specified directory whose name is the current etcd index preceded with leading zeroes.

    Key-Value Method

    Implemented according to etcd Client API: "Atomically Creating In-Order Keys".

    etcd keeps a counter for each operation performed. The etcd index keeps track of this counter, that is, it is the integer associated to the last operation performed in etcd. Given a specified directory EtcdDirectory, createKeyFromCurrentEtcdIndex creates a key in that directory named after the etcd index and associates the value inputed through parameter value to it. This allows to create keys which are strictly ordered by those indexes, since etcd indexes increment monotonously.

    dir

    EtcdDirectory where the new key will be placed.

    value

    EtcdValue to be associated to key.

    returns

    A Future wrapped around either EtcdSetKeyResponse or EtcdRequestError extending EtcdSetKeyResult.

  13. def deleteDir(dir: EtcdDirectory, recursive: Boolean = false): Future[EtcdCreateDirResult]

    Permalink

    Deletes a directory from etcd.

    Deletes a directory from etcd.

    Key-Value Method

    Implemented according to etcd Client API: "Deleting a Directory".

    An empty directory can be deleted form etcd by simply specifying EtcdDirectory leading to the directory in etcd. However, for a non-empty directory one must also set the recursive parameter (which defaults to false) to true.

    dir

    EtcdDirectory to be deleted.

    recursive

    enables deletion of non-empty directories when set to true. Defaults to false.

    returns

    A Future wrapped around either EtcdCreateDirResponse or EtcdRequestError extending EtcdCreateDirResult.

  14. def deleteKey(key: EtcdKey, deleteConditionOp: Option[ConditionalDeleteCondition] = None): Future[EtcdDeleteKeyResult]

    Permalink

    Deletes a key from etcd.

    Deletes a key from etcd.

    Key-Value Method

    Implemented according to etcd Client API: "Deleting a key". See also "Atomic Compare-and-Delete".

    Optionally etcd allows to conditionally delete a key. This can be done by setting the conditionOp parameter to any of the case classes extending trait ConditionalDeleteCondition.

    key

    EtcdKey to be deleted.

    deleteConditionOp

    One of case classes KeyMustHaveIndex or KeyMustHaveValue extending ConditionalDeleteCondition. Defaults to None.

    returns

    A Future wrapped around either EtcdDeleteKeyResponse or EtcdRequestError extending EtcdDeleteKeyResult.

  15. def deleteMember(peerID: String): Future[EtcdConfirmationResult]

    Permalink

    Deletes a member form an etcd cluster.

    Deletes a member form an etcd cluster.

    Member methods

    Implemented according to etcd Members API: "Delete a member".

    peerID

    A string identifying another member of the etcd cluster.

    returns

    A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError extending EtcdConfirmationResult.

  16. def deleteRole(role: EtcdRole): Future[EtcdConfirmationResult]

    Permalink

    Deletes a role.

    Deletes a role.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    In this case, it suffices to provide the role field in the EtcdRole.

    role

    EtcdRole with details of the role to be created or updated.

    returns

    A Future wrapped around either EtcdConfirmationResponse] or EtcdStandardError. extending EtcdConfirmationResult.

  17. def deleteUser(user: EtcdUserRequestForm): Future[EtcdConfirmationResult]

    Permalink

    Deletes a user.

    Deletes a user.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    In this case, it suffices to provide the user in the EtcdUserRequestForm.

    user

    EtcdUserRequestForm containing the details of a given user.

    returns

    A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError. extending EtcdConfirmationResult.

  18. def disableAuthentication(): Future[EtcdConfirmationResult]

    Permalink

    Disables authentication.

    Disables authentication.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    returns

    A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError. extending EtcdConfirmationResult.

  19. def enableAuthentication(): Future[EtcdConfirmationResult]

    Permalink

    Enables authentication.

    Enables authentication.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    In order to enable authentication, the root user must be created first using EtcdClient.addUpdateUser. After authentication only the root user or users with root rights (for example, with the root role) can access and modify permission resources.

    returns

    A Future wrapped around either EtcdConfirmationResponse or EtcdStandardError. extending EtcdConfirmationResult.

  20. final def eq(arg0: AnyRef): Boolean

    Permalink
    Definition Classes
    AnyRef
  21. def equals(arg0: Any): Boolean

    Permalink
    Definition Classes
    AnyRef → Any
  22. def finalize(): Unit

    Permalink
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  23. def getAuthenticationStatus: Future[EtcdGetAuthenticationStatusResult]

    Permalink

    Checks if authentication is enabled.

    Checks if authentication is enabled.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    returns

    A Future wrapped around either EtcdGetAuthenticationStatusResponse or EtcdStandardError. extending EtcdGetAuthenticationStatusResult.

  24. final def getClass(): Class[_]

    Permalink
    Definition Classes
    AnyRef → Any
  25. def getHealth: Future[EtcdGetHealthResult]

    Permalink

    Verifies the health of a member of an etcd cluster.

    Verifies the health of a member of an etcd cluster.

    Statistics Method

    Implemented according to etcd Admin API: "Checking health of an etcd member node".

    returns

    A Future wrapped around EtcdGetHealthResult with an error or a response containing a boolean, which evaluates to true if the member is healthy, false otherwise.

  26. def getKey(key: EtcdKey): Future[EtcdGetKeyResult]

    Permalink

    Gets the current state of a key in etcd.

    Gets the current state of a key in etcd.

    Key-Value Method

    Implemented according to etcd Client API: "Get the value of a key".

    Note that there is no difference in a GET request for a key and a directory. An GET HTTP request made to a node used as a directory looks the same as a request to a node used as a key. However, there is a difference in terms of a response. The getKey method is intended to handle responses only for requests to nodes used as keys. If it is used to make a request to a directory, it will return an EtcdRequestError with the statusCode field set to 200. This means that etcd accepts the request and returns a response. However EtcdClient does not parse the response. In order to get a response which extracts the JSON returned in the response body into a case class, use EtcdClient.listDir.

    key

    EtcdKey whose status is queried.

    returns

    A Future wrapped around either EtcdGetKeyResponse or EtcdRequestError extending EtcdGetKeyResult

  27. def getLeaderStats: Future[EtcdGetLeaderStatsResult]

    Permalink

    Gets statistics from the leader of a cluster, which holds information of the whole cluster.

    Gets statistics from the leader of a cluster, which holds information of the whole cluster.

    Statistics Method

    Implemented according to etcd Client API: "Leader Statistics".

  28. def getMembers: Future[EtcdGetMembersResult]

    Permalink

    Gets a lsi of members of an etcd cluster.

    Gets a lsi of members of an etcd cluster.

    Member methods

    Implemented according to etcd Members API: "List members".

    returns

    A Future wrapped around either EtcdGetMembersResponse or EtcdStandardError extending EtcdGetMembersResult.

  29. def getRoleDetails(role: EtcdRole): Future[EtcdGetRoleDetailsResult]

    Permalink

    Gets a list of details of an existing role.

    Gets a list of details of an existing role.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    In this case, it suffices to provide the role field in the EtcdRole.

    role

    EtcdRole with details of the role to be created or updated.

    returns

    A Future wrapped around either EtcdGetRoleDetailsResponse] or EtcdStandardError extending EtcdGetRoleDetailsResult.

  30. def getRoles(): Future[EtcdGetRolesResult]

    Permalink

    Gets a list of existing roles.

    Gets a list of existing roles.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    returns

    A Future wrapped around either EtcdGetRolesResponse] or EtcdStandardError. extending EtcdGetRolesResult.

  31. def getSelfStats: Future[EtcdGetSelfStatsResult]

    Permalink

    Gets statistics from a member of an etcd cluster.

    Gets statistics from a member of an etcd cluster.

    Statistics Method

    Implemented according to etcd Client API: "Self Statistics".

  32. def getStoreStats: Future[EtcdGetStoreStatsResult]

    Permalink

    Gets statistics about performed operations stored by a node of an etcd cluster.

    Gets statistics about performed operations stored by a node of an etcd cluster.

    Statistics Method

    Implemented according to etcd Client API: "Store Statistics".

  33. def getUserDetails(user: EtcdUserRequestForm): Future[EtcdGetUserDetailsResult]

    Permalink

    Gets the details of an existing user including permissions granted to her and her roles

    Gets the details of an existing user including permissions granted to her and her roles

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    In this case, it suffices to provide the user field in the EtcdUserRequestForm.

    user

    EtcdUserRequestForm containing the details of a given user.

    returns

    A Future wrapped around either EtcdGetUserDetailsResponse or EtcdStandardError. extending EtcdGetUserDetailsResult.

  34. def getUsers(): Future[EtcdGetUsersResult]

    Permalink

    Gets a list of existing users.

    Gets a list of existing users.

    Authentication Method

    Implemented according to etcd Auth and Security API: "API endpoints".

    returns

    A Future wrapped around either EtcdGetUsersResponse or EtcdStandardError. extending EtcdGetUsersResult.

  35. def getVersion: Future[EtcdGetVersionResult]

    Permalink

    Gets the version of an instance of etcd.

    Gets the version of an instance of etcd.

    Statistics Method

    Implemented according to etcd Admin API: "Getting the etcd version".

  36. def hashCode(): Int

    Permalink
    Definition Classes
    AnyRef → Any
  37. final def isInstanceOf[T0]: Boolean

    Permalink
    Definition Classes
    Any
  38. def listDir(dir: EtcdDirectory, recursive: Boolean = false, sorted: Boolean = false): Future[EtcdListDirResult]

    Permalink

    Lists the elements of a directory.

    Lists the elements of a directory.

    Key-Value Method

    Implemented according to etcd Client API: "Listing a directory". See also "Atomically Creating In-Order Keys" for information on the sorted parameter.

    When the parameter recursive is set to false (as it is by default), it lists the immediate children of the given node. When it is set to true, it also recursively lists subnodes of the directory.

    When both parameters recursive and sorted are set to true, the list returned is ordered.

    dir

    EtcdDirectory to be listed.

    recursive

    recursively gets all subnodes of a directory when set to true.

    sorted

    sorts listed key when set to true in combination with the recursive parameter.

    returns

    A Future wrapped around either EtcdListDirResponse or EtcdRequestError extending EtcdListDirResult.

  39. final def ne(arg0: AnyRef): Boolean

    Permalink
    Definition Classes
    AnyRef
  40. final def notify(): Unit

    Permalink
    Definition Classes
    AnyRef
  41. final def notifyAll(): Unit

    Permalink
    Definition Classes
    AnyRef
  42. def refreshDirTTL(dir: EtcdDirectory, ttlOp: Option[EtcdTTL]): Future[EtcdCreateDirResult]

    Permalink

    Refreshes or unsets the TTL of an existing directory.

    Refreshes or unsets the TTL of an existing directory.

    Key-Value Method

    Implemented according to etcd Client API: "Using a directory TTL".

    Sets a lifespan in seconds for an existing directory. Once it expires, the directory is deleted. Setting ttlOp parameter to None allows to unset TTL.

    dir

    EtcdDirectory whose TTL is to be updated.

    ttlOp

    Life span in seconds of the directory. Defaults to None.

    returns

    A Future wrapped around either EtcdCreateDirResponse or EtcdRequestError extending EtcdCreateDirResult.

  43. def refreshTTL(key: EtcdKey, ttlOp: EtcdTTL, conditionOp: Option[CompareAndSwapCondition] = None): Future[EtcdSetKeyResult]

    Permalink

    Updates the TTL of a key without notifying watchers.

    Updates the TTL of a key without notifying watchers.

    Key-Value Method

    Implemented according to etcd Client API: "Refreshing key TTL".

    When a watch is set, and a key is updated using EtcdClient.setKey, watchers are notified, triggering any operation conditionally set to follow given a particular response. This includes updates to its TTL. etcd allows updating TTL without notifying watches set on a key, thus not causing such side effects. EtcdClient implements this feature in the refreshTTL method. When a TTL is refreshed, its value cannot be updated.

    key

    EtcdKey that is to be updated.

    ttlOp

    Life span in seconds of key-value . Defaults to None.

    conditionOp

    One of case classes KeyMustExist, KeyMustHaveIndex or KeyMustHaveValue extending CompareAndSwapCondition. Defaults to None.

    returns

    A Future wrapped around either EtcdSetKeyResponse or EtcdRequestError extending EtcdSetKeyResult.

  44. def setKey(key: EtcdKey, value: EtcdValue, ttlOp: Option[EtcdTTL] = None, conditionOp: Option[CompareAndSwapCondition] = None): Future[EtcdSetKeyResult]

    Permalink

    Sets or updates a key in a specific etcd node; also, sets and unsets TTL.

    Sets or updates a key in a specific etcd node; also, sets and unsets TTL.

    Key-Value Method

    Implemented according to etcd Client API: "Setting the value of a key". See also "Using key TTL", "Creating a hidden node" and "Atomic Compare-and-Swap".

    The value of a key can be updated by choosing the same key, but a different value.

    Optionally one can choose a TTL (time to live), which is a lifespan in seconds for the key-value. When it expires, the key is deleted.

    It is also possible to update the TTL of a key by specifying a new value for the ttlOp parameter with the same key. A similar effect can be achieved using EtcdClient.refreshTTL, except that this last operation does not notify watchers.

    The TTL can be unset by updating the key with the parameter ttlOp set to None and with condition KeyMustExist set to true.

    Additionally, etcd allows to conditionally compare and swap values. This can be done by setting the conditionOp parameter to any of the case classes extending trait CompareAndSwapCondition.

    key

    EtcdKey that is to be set or updated.

    value

    EtcdValue to be associated to key.

    ttlOp

    Life span in seconds of key-value. Defaults to None.

    conditionOp

    One of case classes KeyMustExist, KeyMustHaveIndex or KeyMustHaveValue extending CompareAndSwapCondition. Defaults to None.

    returns

    A Future wrapped around either EtcdSetKeyResponse or EtcdRequestError extending EtcdSetKeyResult.

  45. final def synchronized[T0](arg0: ⇒ T0): T0

    Permalink
    Definition Classes
    AnyRef
  46. def toString(): String

    Permalink
    Definition Classes
    AnyRef → Any
  47. final def wait(): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  48. final def wait(arg0: Long, arg1: Int): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  49. final def wait(arg0: Long): Unit

    Permalink
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  50. def waitForKey(key: EtcdKey, callback: EtcdWaitCallback, modifiedIndexForWait: Option[EtcdIndex] = None, recursive: Boolean = false): Future[EtcdWaitForKeyResult]

    Permalink

    Sets a watch, which returns a get response if there is a change in a key in etcd.

    Sets a watch, which returns a get response if there is a change in a key in etcd.

    Key-Value Method

    Implemented according to etcd Client API: "Waiting for a change".

    Use case of the waitForKey method:

    Optionally, one can choose an etcd modified index for which the watch is being set. An etcd modified index is the integer associated to the operation modifying the state of a key in etcd. If an index i is chosen, such that there were subsequent changes in the state of the key after the operation associated to i, etcd returns an EtcdGetKeyResponse with the state of the key after the first change registered with indexe greater than i.

    For an index j greater than the etcd index associated to the last operation performed, the watch will not return a response until a change with an index greater than j is made.

    Also, one can choose to wait for changes in any of the subnodes of a given node. This can be achieved by setting the parameter recursive to true. This parameter defaults to false.

    key

    EtcdKey on watch.

    callback

    EtcdWaitCallback which will return a EtcdGetKeyResponse or a throwable once it is called upon.

    modifiedIndexForWait

    EtcdIndex associated to an operation performed on a given key.

    recursive

    waits on changes of subnoded of the specified key, when it is set to true. Defaults to false.

    returns

    A Future wrapped around either com.eiipii.etcd.client.model.EtcdWaitForKeyAccepted containing the headers of the response or EtcdRequestError.

  51. def withAuthorization(auth: EtcdUserAuthenticationData): EtcdClient

    Permalink

    Create a new EtcdClient instance with authorization configuration.

    Create a new EtcdClient instance with authorization configuration.

    Be aware that each EtcdClient instance must be closed after it is no longer used.

    For an example of a set up of an EtcdClient with authentication see this example in our user's guide.

    auth

    Case class providing a login and a password used for authorization.

  52. def withTLS(nettySslContext: SslContext): EtcdClient

    Permalink

    Create a new EtcdClient instance with support for TLS.

    Create a new EtcdClient instance with support for TLS.

    See the V2 Security Model documentation in order to learn about the possible use cases of etcd with TLS.

    The following is an example of a possible configuration with TLS taken from out tests:

    val clientCert = this.getClass.getResourceAsStream("/ssl/client.crt")
    val keyFile = this.getClass.getResourceAsStream("/ssl/client_nopass.PKCS8")
    val caCert = this.getClass.getResourceAsStream("/ssl/dev-ca.crt")
    val sslContext = SslContextBuilder.forClient()
    .trustManager(caCert)
    .keyManager(clientCert, keyFile)
    .build()
    
    val endpoint: String = s"https://localhost:4001"
    val etcdCli = new EtcdClient(EtcdDSL.config(endpoint))
    val secureCli: EtcdClient = etcdCli.withTLS(sslContext)

    Make sure to fill in the details for properly configuring the TLS protocol according to your needs.

    nettySslContext

    Look for io.netty.handler.ssl.SslContext in the Netty Javadoc.

Inherited from AnyRef

Inherited from Any

Ungrouped