Package io.vertx.ext.consul

Interface ConsulClient

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

    • Method Detail

      • 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:
        /v1/agent/self endpoint

      • 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:
        /v1/coordinate/nodes endpoint

      • 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:
        /v1/coordinate/datacenters endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/kv/:key endpoint

      • 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:
        /v1/txn endpoint

      • 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:
        /acl/policy

      • 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:
        PUT /acl/policy/:id

      • 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:
        DELETE /acl/policy/:id

      • 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:
        GET /acl/policies

      • 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:
        /v1/acl/token/:AccessorID endpoint

      • 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:
        /v1/event/fire/:name endpoint

      • 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:
        /v1/event/fire/:name endpoint

      • listEvents

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

      • 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:
        /v1/event/list endpoint

      • 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:
        /v1/agent/service/deregister/:service_id endpoint

      • 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:
        /v1/catalog/service/:service endpoint

      • 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:
        /v1/catalog/service/:service endpoint

      • 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:
        /v1/catalog/datacenters endpoint

      • catalogNodes

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

      • 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:
        /v1/catalog/nodes endpoint

      • 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:
        /v1/health/checks/:service endpoint

      • 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:
        /v1/health/checks/:service endpoint

      • 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:
        /v1/health/state/:state endpoint

      • 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:
        /v1/health/state/:state endpoint

      • healthServiceNodes

        Future<ServiceEntryList> healthServiceNodes​(String service,
                                            boolean passing)
        Returns the nodes providing the service. This endpoint is very similar to the catalogServiceNodes(java.lang.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:
        /v1/health/service/:service endpoint

      • 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:
        /v1/health/node/:node endpoint

      • catalogServices

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

      • 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:
        /v1/catalog/node/:node endpoint

      • localServices

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

      • 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:
        /v1/agent/checks endpoint

      • 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:
        /v1/agent/check/register endpoint

      • 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:
        /v1/agent/check/deregister/:check_id endpoint

      • 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:
        /v1/agent/check/pass/:check_id endpoint, CheckStatus

      • 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:
        /v1/agent/check/pass/:check_id endpoint, CheckStatus

      • 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:
        /v1/agent/check/warn/:check_id endpoint, CheckStatus

      • 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:
        /v1/agent/check/warn/:check_id endpoint, CheckStatus

      • 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:
        /v1/agent/check/fail/:check_id endpoint, CheckStatus

      • 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:
        /v1/agent/check/fail/:check_id endpoint, CheckStatus

      • 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:
        /v1/agent/check/update/:check_id endpoint

      • 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:
        /v1/agent/check/update/:check_id endpoint

      • 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:
        /v1/status/leader endpoint

      • 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:
        /v1/status/peers endpoint

      • createSession

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

      • 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:
        /v1/session/create endpoint

      • 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:
        /v1/session/info/:uuid endpoint

      • 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:
        /v1/session/renew/:uuid endpoint

      • 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:
        /v1/session/node/:node endpoint

      • destroySession

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

      • 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:
        /v1/query endpoint

      • 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:
        /v1/query/:uuid endpoint

      • 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:
        /v1/query endpoint

      • 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:
        /v1/query/:uuid endpoint

      • 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:
        /v1/query/:uuid/execute endpoint

      • 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:
        /v1/query/:uuid/execute endpoint

      • 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:
        /v1/catalog/register endpoint

      • 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:
        /v1/catalog/deregister endpoint

      • close

        void close()
        Close the client and release its resources