Interface ConsulClient

public interface ConsulClient
A Vert.x service used to interact with Consul.
Author:
Ruslan Sennov

  • Method Details

    • create

      static ConsulClient create(Vertx vertx)
      Create a Consul client with default options.
      Parameters:
      vertx - the Vert.x instance
      Returns:
      the client

    • create

      static ConsulClient create(Vertx vertx, ConsulClientOptions options)
      Create a Consul client.
      Parameters:
      vertx - the Vert.x instance
      options - the options
      Returns:
      the client

    • agentInfo

      Future<JsonObject> agentInfo()
      Returns the configuration and member information of the local agent
      Returns:
      a future provided with the configuration and member information of the local agent
      See Also:

    • coordinateNodes

      Future<CoordinateList> coordinateNodes()
      Returns the LAN network coordinates for all nodes in a given DC
      Returns:
      a future provided with network coordinates of nodes in datacenter
      See Also:

    • coordinateNodesWithOptions

      Future<CoordinateList> coordinateNodesWithOptions(BlockingQueryOptions options)
      Returns the LAN network coordinates for all nodes in a given DC This is blocking query unlike coordinateNodes()
      Parameters:
      options - the blocking options
      Returns:
      a future provided with network coordinates of nodes in datacenter
      See Also:

    • coordinateDatacenters

      Future<List<DcCoordinates>> coordinateDatacenters()
      Returns the WAN network coordinates for all Consul servers, organized by DCs
      Returns:
      a future provided with network coordinates for all Consul servers
      See Also:

    • getKeys

      Future<List<String>> getKeys(String keyPrefix)
      Returns the list of keys that corresponding to the specified key prefix.
      Parameters:
      keyPrefix - the prefix
      Returns:
      a future provided with keys list
      See Also:

    • getKeysWithOptions

      Future<List<String>> getKeysWithOptions(String keyPrefix, BlockingQueryOptions options)
      Returns the list of keys that corresponding to the specified key prefix.
      Parameters:
      keyPrefix - the prefix
      options - the blocking options
      Returns:
      a future provided with keys list
      See Also:

    • getValue

      Future<KeyValue> getValue(String key)
      Returns key/value pair that corresponding to the specified key. An empty KeyValue object will be returned if no such key is found.
      Parameters:
      key - the key
      Returns:
      a future provided with key/value pair
      See Also:

    • getValueWithOptions

      Future<KeyValue> getValueWithOptions(String key, BlockingQueryOptions options)
      Returns key/value pair that corresponding to the specified key. An empty KeyValue object will be returned if no such key is found. This is blocking query unlike getValue(String)
      Parameters:
      key - the key
      options - the blocking options
      Returns:
      a future provided with key/value pair
      See Also:

    • deleteValue

      Future<Void> deleteValue(String key)
      Remove the key/value pair that corresponding to the specified key
      Parameters:
      key - the key
      Returns:
      a future notified on complete
      See Also:

    • getValues

      Future<KeyValueList> getValues(String keyPrefix)
      Returns the list of key/value pairs that corresponding to the specified key prefix. An empty KeyValueList object will be returned if no such key prefix is found.
      Parameters:
      keyPrefix - the prefix
      Returns:
      a future provided with list of key/value pairs
      See Also:

    • getValuesWithOptions

      Future<KeyValueList> getValuesWithOptions(String keyPrefix, BlockingQueryOptions options)
      Returns the list of key/value pairs that corresponding to the specified key prefix. An empty KeyValueList object will be returned if no such key prefix is found. This is blocking query unlike getValues(String)
      Parameters:
      keyPrefix - the prefix
      options - the blocking options
      Returns:
      a future provided with list of key/value pairs
      See Also:

    • deleteValues

      Future<Void> deleteValues(String keyPrefix)
      Removes all the key/value pair that corresponding to the specified key prefix
      Parameters:
      keyPrefix - the prefix
      Returns:
      a future notified on complete
      See Also:

    • putValue

      Future<Boolean> putValue(String key, String value)
      Adds specified key/value pair
      Parameters:
      key - the key
      value - the value
      Returns:
      a future provided with success of operation
      See Also:

    • putValueWithOptions

      Future<Boolean> putValueWithOptions(String key, String value, KeyValueOptions options)
      Parameters:
      key - the key
      value - the value
      options - options used to push pair
      Returns:
      a future provided with success of operation
      See Also:

    • transaction

      Future<TxnResponse> transaction(TxnRequest request)
      Manages multiple operations inside a single, atomic transaction.
      Parameters:
      request - transaction request
      Returns:
      a future provided with result of transaction
      See Also:

    • createAclPolicy

      Future<String> createAclPolicy(AclPolicy policy)
      Creates a new ACL policy
      Parameters:
      policy - properties of policy
      Returns:
      a future provided with ID of created policy
      See Also:

    • readPolicy

      Future<AclPolicy> readPolicy(String id)
      This endpoint reads an ACL policy with the given ID
      Parameters:
      id - uuid policy
      Returns:
      a future of AclPolicy
      See Also:

    • readPolicyByName

      Future<AclPolicy> readPolicyByName(String name)
      This endpoint reads an ACL policy with the given name
      Parameters:
      name - unique name of created policy
      Returns:
      a future of AclPolicy like in readPolicy(String)
      See Also:

    • updatePolicy

      Future<AclPolicy> updatePolicy(String id, AclPolicy policy)
      This endpoint updates an existing ACL policy
      Parameters:
      id - uuid of existing policy
      policy - options that will be applied to the existing policy
      Returns:
      a future of AclPolicy
      See Also:

    • deletePolicy

      Future<Boolean> deletePolicy(String id)
      This endpoint deletes an ACL policy
      Parameters:
      id - uuid of existing policy
      Returns:
      a future boolean value: true or false, indicating whether the deletion was successful
      See Also:

    • getAclPolicies

      Future<List<AclPolicy>> getAclPolicies()
      This endpoint lists all the ACL policies. Note - The policies rules are not included in the listing and must be retrieved by the policy reading endpoint
      Returns:
      a future of all acl policies
      See Also:

    • createAclToken

      Future<AclToken> createAclToken(AclToken token)
      Create an Acl token
      Parameters:
      token - properties of the token
      Returns:
      a future NewAclToken in which two fields accessorId and secretId. AclToken accessorId - required in the URL path or JSON body for getting, updating and cloning token. AclToken secretId - using in ConsulClientOptions.setAclToken(String).
      See Also:

    • updateAclToken

      Future<AclToken> updateAclToken(String accessorId, AclToken token)
      Update an existing Acl token
      Parameters:
      accessorId - uuid of the token
      token - properties of the token
      Returns:
      a future NewAclToken like in createAclToken(io.vertx.ext.consul.token.AclToken)
      See Also:

    • cloneAclToken

      Future<AclToken> cloneAclToken(String accessorId, CloneAclTokenOptions cloneAclTokenOptions)
      Clones an existing ACL token
      Parameters:
      accessorId - uuid of the token
      cloneAclTokenOptions - properties of cloned token
      Returns:
      a future NewAclToken like in createAclToken(io.vertx.ext.consul.token.AclToken)
      See Also:

    • getAclTokens

      Future<List<AclToken>> getAclTokens()
      Get list of Acl token
      Returns:
      a future provided with list of tokens
      See Also:

    • readAclToken

      Future<AclToken> readAclToken(String accessorId)
      Reads an ACL token with the given Accessor ID
      Parameters:
      accessorId - uuid of token
      Returns:
      a future provided with token
      See Also:

    • deleteAclToken

      Future<Boolean> deleteAclToken(String accessorId)
      Deletes an ACL token
      Parameters:
      accessorId - uuid of token
      Returns:
      a future boolean value: true or false, indicating whether the deletion was successful.

    • fireEvent

      Future<Event> fireEvent(String name)
      Fires a new user event
      Parameters:
      name - name of event
      Returns:
      a future provided with properties of event
      See Also:

    • fireEventWithOptions

      Future<Event> fireEventWithOptions(String name, EventOptions options)
      Fires a new user event
      Parameters:
      name - name of event
      options - options used to create event
      Returns:
      a future provided with properties of event
      See Also:

    • listEvents

      Future<EventList> listEvents()
      Returns the most recent events known by the agent
      Returns:
      a future provided with list of events
      See Also:

    • listEventsWithOptions

      Future<EventList> listEventsWithOptions(EventListOptions options)
      Returns the most recent events known by the agent. This is blocking query unlike listEvents(). However, the semantics of this endpoint are slightly different. Most blocking queries provide a monotonic index and block until a newer index is available. This can be supported as a consequence of the total ordering of the consensus protocol. With gossip, there is no ordering, and instead X-Consul-Index maps to the newest event that matches the query.

      In practice, this means the index is only useful when used against a single agent and has no meaning globally. Because Consul defines the index as being opaque, clients should not be expecting a natural ordering either.

      Parameters:
      options - the blocking options
      Returns:
      a future provided with list of events
      See Also:

    • registerService

      Future<Void> registerService(ServiceOptions serviceOptions)
      Adds a new service, with an optional health check, to the local agent.
      Parameters:
      serviceOptions - the options of new service
      Returns:
      a future notified when complete
      See Also:

    • maintenanceService

      Future<Void> maintenanceService(MaintenanceOptions maintenanceOptions)
      Places a given service into "maintenance mode"
      Parameters:
      maintenanceOptions - the maintenance options
      Returns:
      a future notified when complete
      See Also:

    • deregisterService

      Future<Void> deregisterService(String id)
      Remove a service from the local agent. The agent will take care of deregistering the service with the Catalog. If there is an associated check, that is also deregistered.
      Parameters:
      id - the ID of service
      Returns:
      a future notified when complete
      See Also:

    • catalogServiceNodes

      Future<ServiceList> catalogServiceNodes(String service)
      Returns the nodes providing a service
      Parameters:
      service - name of service
      Returns:
      a future provided with list of nodes providing given service
      See Also:

    • catalogServiceNodesWithOptions

      Future<ServiceList> catalogServiceNodesWithOptions(String service, ServiceQueryOptions options)
      Returns the nodes providing a service
      Parameters:
      service - name of service
      options - options used to request services
      Returns:
      a future provided with list of nodes providing given service
      See Also:

    • catalogDatacenters

      Future<List<String>> catalogDatacenters()
      Return all the datacenters that are known by the Consul server
      Returns:
      a future provided with list of datacenters
      See Also:

    • catalogNodes

      Future<NodeList> catalogNodes()
      Returns the nodes registered in a datacenter
      Returns:
      a future provided with list of nodes
      See Also:

    • catalogNodesWithOptions

      Future<NodeList> catalogNodesWithOptions(NodeQueryOptions options)
      Returns the nodes registered in a datacenter
      Parameters:
      options - options used to request nodes
      Returns:
      a future provided with list of nodes
      See Also:

    • healthChecks

      Future<CheckList> healthChecks(String service)
      Returns the checks associated with the service
      Parameters:
      service - the service name
      Returns:
      a future provided with list of checks
      See Also:

    • healthChecksWithOptions

      Future<CheckList> healthChecksWithOptions(String service, CheckQueryOptions options)
      Returns the checks associated with the service
      Parameters:
      service - the service name
      options - options used to request checks
      Returns:
      a future provided with list of checks
      See Also:

    • healthState

      Future<CheckList> healthState(HealthState healthState)
      Returns the checks in the specified status
      Parameters:
      healthState - the health state
      Returns:
      a future provided with list of checks
      See Also:

    • healthStateWithOptions

      Future<CheckList> healthStateWithOptions(HealthState healthState, CheckQueryOptions options)
      Returns the checks in the specified status
      Parameters:
      healthState - the health state
      options - options used to request checks
      Returns:
      a future provided with list of checks
      See Also:

    • healthServiceNodes

      Future<ServiceEntryList> healthServiceNodes(String service, boolean passing)
      Returns the nodes providing the service. This endpoint is very similar to the catalogServiceNodes(String) endpoint; however, this endpoint automatically returns the status of the associated health check as well as any system level health checks.
      Parameters:
      service - the service name
      passing - if true, filter results to only nodes with all checks in the passing state
      Returns:
      a future provided with list of services
      See Also:

    • healthServiceNodesWithOptions

      Future<ServiceEntryList> healthServiceNodesWithOptions(String service, boolean passing, ServiceQueryOptions options)
      Returns the nodes providing the service. This endpoint is very similar to the catalogServiceNodesWithOptions(String, ServiceQueryOptions) endpoint; however, this endpoint automatically returns the status of the associated health check as well as any system level health checks.
      Parameters:
      service - the service name
      passing - if true, filter results to only nodes with all checks in the passing state
      options - options used to request services
      Returns:
      a future provided with list of services
      See Also:

    • healthNodesWithOptions

      Future<CheckList> healthNodesWithOptions(String node, CheckQueryOptions options)
      Returns the checks specific to the node provided on the path.
      Parameters:
      node - the node name or ID
      options - options used to request node health checks
      Returns:
      a future provided with list of services
      See Also:

    • catalogServices

      Future<ServiceList> catalogServices()
      Returns the services registered in a datacenter
      Returns:
      a future provided with list of services
      See Also:

    • catalogServicesWithOptions

      Future<ServiceList> catalogServicesWithOptions(BlockingQueryOptions options)
      Returns the services registered in a datacenter This is blocking query unlike catalogServices()
      Parameters:
      options - the blocking options
      Returns:
      a future provided with list of services
      See Also:

    • catalogNodeServices

      Future<ServiceList> catalogNodeServices(String node)
      Returns the node's registered services
      Parameters:
      node - node name
      Returns:
      a future provided with list of services
      See Also:

    • catalogNodeServicesWithOptions

      Future<ServiceList> catalogNodeServicesWithOptions(String node, BlockingQueryOptions options)
      Returns the node's registered services This is blocking query unlike catalogNodeServices(String)
      Parameters:
      node - node name
      options - the blocking options
      Returns:
      a future provided with list of services
      See Also:

    • localServices

      Future<List<Service>> localServices()
      Returns list of services registered with the local agent.
      Returns:
      a future provided with list of services
      See Also:

    • localChecks

      Future<List<Check>> localChecks()
      Return all the checks that are registered with the local agent.
      Returns:
      a future provided with list of checks
      See Also:

    • registerCheck

      Future<Void> registerCheck(CheckOptions checkOptions)
      Add a new check to the local agent. The agent is responsible for managing the status of the check and keeping the Catalog in sync.
      Parameters:
      checkOptions - options used to register new check
      Returns:
      a future notified when complete
      See Also:

    • deregisterCheck

      Future<Void> deregisterCheck(String checkId)
      Remove a check from the local agent. The agent will take care of deregistering the check from the Catalog.
      Parameters:
      checkId - the ID of check
      Returns:
      a future notified when complete
      See Also:

    • passCheck

      Future<Void> passCheck(String checkId)
      Set status of the check to "passing". Used with a check that is of the TTL type. The TTL clock will be reset.
      Parameters:
      checkId - the ID of check
      Returns:
      a future notified when complete
      See Also:

    • passCheckWithNote

      Future<Void> passCheckWithNote(String checkId, String note)
      Set status of the check to "passing". Used with a check that is of the TTL type. The TTL clock will be reset.
      Parameters:
      checkId - the ID of check
      note - specifies a human-readable message. This will be passed through to the check's Output field.
      Returns:
      a future notified when complete
      See Also:

    • warnCheck

      Future<Void> warnCheck(String checkId)
      Set status of the check to "warning". Used with a check that is of the TTL type. The TTL clock will be reset.
      Parameters:
      checkId - the ID of check
      Returns:
      a future notified when complete
      See Also:

    • warnCheckWithNote

      Future<Void> warnCheckWithNote(String checkId, String note)
      Set status of the check to "warning". Used with a check that is of the TTL type. The TTL clock will be reset.
      Parameters:
      checkId - the ID of check
      note - specifies a human-readable message. This will be passed through to the check's Output field.
      Returns:
      a future notified when complete
      See Also:

    • failCheck

      Future<Void> failCheck(String checkId)
      Set status of the check to "critical". Used with a check that is of the TTL type. The TTL clock will be reset.
      Parameters:
      checkId - the ID of check
      Returns:
      a future notified when complete
      See Also:

    • failCheckWithNote

      Future<Void> failCheckWithNote(String checkId, String note)
      Set status of the check to "critical". Used with a check that is of the TTL type. The TTL clock will be reset.
      Parameters:
      checkId - the ID of check
      note - specifies a human-readable message. This will be passed through to the check's Output field.
      Returns:
      a future notified when complete
      See Also:

    • updateCheck

      Future<Void> updateCheck(String checkId, CheckStatus status)
      Set status of the check to given status. Used with a check that is of the TTL type. The TTL clock will be reset.
      Parameters:
      checkId - the ID of check
      status - new status of check
      Returns:
      a future notified when complete
      See Also:

    • updateCheckWithNote

      Future<Void> updateCheckWithNote(String checkId, CheckStatus status, String note)
      Set status of the check to given status. Used with a check that is of the TTL type. The TTL clock will be reset.
      Parameters:
      checkId - the ID of check
      status - new status of check
      note - specifies a human-readable message. This will be passed through to the check's Output field.
      Returns:
      a future notified when complete
      See Also:

    • leaderStatus

      Future<String> leaderStatus()
      Get the Raft leader for the datacenter in which the agent is running. It returns an address in format "10.1.10.12:8300"
      Returns:
      a future provided with address of cluster leader
      See Also:

    • peersStatus

      Future<List<String>> peersStatus()
      Retrieves the Raft peers for the datacenter in which the the agent is running. It returns a list of addresses "10.1.10.12:8300", "10.1.10.13:8300"
      Returns:
      a future provided with list of peers
      See Also:

    • createSession

      Future<String> createSession()
      Initialize a new session
      Returns:
      a future provided with ID of new session
      See Also:

    • createSessionWithOptions

      Future<String> createSessionWithOptions(SessionOptions options)
      Initialize a new session
      Parameters:
      options - options used to create session
      Returns:
      a future provided with ID of new session
      See Also:

    • infoSession

      Future<Session> infoSession(String id)
      Returns the requested session information
      Parameters:
      id - the ID of requested session
      Returns:
      a future provided with info of requested session
      See Also:

    • infoSessionWithOptions

      Future<Session> infoSessionWithOptions(String id, BlockingQueryOptions options)
      Returns the requested session information This is blocking query unlike infoSession(String)
      Parameters:
      id - the ID of requested session
      options - the blocking options
      Returns:
      a future provided with info of requested session
      See Also:

    • renewSession

      Future<Session> renewSession(String id)
      Renews the given session. This is used with sessions that have a TTL, and it extends the expiration by the TTL
      Parameters:
      id - the ID of session that should be renewed
      Returns:
      a future provided with info of renewed session
      See Also:

    • listSessions

      Future<SessionList> listSessions()
      Returns the active sessions
      Returns:
      a future provided with list of sessions
      See Also:

    • listSessionsWithOptions

      Future<SessionList> listSessionsWithOptions(BlockingQueryOptions options)
      Returns the active sessions This is blocking query unlike listSessions()
      Parameters:
      options - the blocking options
      Returns:
      a future provided with list of sessions
      See Also:

    • listNodeSessions

      Future<SessionList> listNodeSessions(String nodeId)
      Returns the active sessions for a given node
      Parameters:
      nodeId - the ID of node
      Returns:
      a future provided with list of sessions
      See Also:

    • listNodeSessionsWithOptions

      Future<SessionList> listNodeSessionsWithOptions(String nodeId, BlockingQueryOptions options)
      Returns the active sessions for a given node This is blocking query unlike listNodeSessions(String)
      Parameters:
      nodeId - the ID of node
      options - the blocking options
      Returns:
      a future provided with list of sessions
      See Also:

    • destroySession

      Future<Void> destroySession(String id)
      Destroys the given session
      Parameters:
      id - the ID of session
      Returns:
      a future notified when complete
      See Also:

    • createPreparedQuery

      Future<String> createPreparedQuery(PreparedQueryDefinition definition)
      Parameters:
      definition - definition of the prepare query
      Returns:
      a future provided with id of created prepare query
      See Also:

    • getPreparedQuery

      Future<PreparedQueryDefinition> getPreparedQuery(String id)
      Returns an existing prepared query
      Parameters:
      id - the id of the query to read
      Returns:
      a future provided with definition of the prepare query
      See Also:

    • getAllPreparedQueries

      Future<List<PreparedQueryDefinition>> getAllPreparedQueries()
      Returns a list of all prepared queries.
      Returns:
      a future provided with list of definitions of the all prepare queries
      See Also:

    • updatePreparedQuery

      Future<Void> updatePreparedQuery(PreparedQueryDefinition definition)
      Parameters:
      definition - definition of the prepare query
      Returns:
      a future notified when complete
      See Also:

    • deletePreparedQuery

      Future<Void> deletePreparedQuery(String id)
      Deletes an existing prepared query
      Parameters:
      id - the id of the query to delete
      Returns:
      a future notified when complete
      See Also:

    • executePreparedQuery

      Future<PreparedQueryExecuteResponse> executePreparedQuery(String query)
      Executes an existing prepared query.
      Parameters:
      query - the ID of the query to execute. This can also be the name of an existing prepared query, or a name that matches a prefix name for a prepared query template.
      Returns:
      a future provided with response
      See Also:

    • executePreparedQueryWithOptions

      Future<PreparedQueryExecuteResponse> executePreparedQueryWithOptions(String query, PreparedQueryExecuteOptions options)
      Executes an existing prepared query.
      Parameters:
      query - the ID of the query to execute. This can also be the name of an existing prepared query, or a name that matches a prefix name for a prepared query template.
      options - the options used to execute prepared query
      Returns:
      a future provided with response
      See Also:

    • registerCatalogService

      Future<Void> registerCatalogService(Node nodeOptions, ServiceOptions serviceOptions)
      Register node with external service
      Parameters:
      nodeOptions - the options of new node
      serviceOptions - the options of new service
      Returns:
      a future provided with response
      See Also:

    • deregisterCatalogService

      Future<Void> deregisterCatalogService(String nodeId, String serviceId)
      Deregister entities from the node or deregister the node itself.
      Parameters:
      nodeId - the ID of node
      serviceId - the ID of the service to de-registered; if it is null, the node itself will be de-registered (as well as the entities that belongs to that node)
      Returns:
      a future notified when complete
      See Also:

    • close

      void close()
      Close the client and release its resources