Package io.vertx.servicediscovery

Interface ServiceDiscovery

  • public interface ServiceDiscovery
    Service Discovery main entry point.

    The service discovery is an infrastructure that let you publish and find `services`. A `service` is a discoverable functionality. It can be qualified by its type, metadata, and location. So a `service` can be a database, a service proxy, a HTTP endpoint. It does not have to be a vert.x entity, but can be anything. Each service is described by a Record.

    The service discovery implements the interactions defined in the service-oriented computing. And to some extend, also provides the dynamic service-oriented computing interaction. So, application can react to arrival and departure of services.

    A service provider can:

    * publish a service record * un-publish a published record * update the status of a published service (down, out of service...)

    A service consumer can:

    * lookup for services * bind to a selected service (it gets a ServiceReference) and use it * release the service once the consumer is done with it * listen for arrival, departure and modification of services.

    Consumer would 1) lookup for service record matching their need, 2) retrieve the ServiceReference that give access to the service, 3) get a service object to access the service, 4) release the service object once done.

    A state above, the central piece of information shared by the providers and consumers are records.

    Providers and consumers must create their own ServiceDiscovery instance. These instances are collaborating in background (distributed structure) to keep the set of services in sync.

    Author:
    Clement Escoffier

    • Method Detail

      • create

        static ServiceDiscovery create​(Vertx vertx)
        Creates a new instance of ServiceDiscovery using the default configuration.
        Parameters:
        vertx - the vert.x instance
        Returns:
        the created instance

      • getReference

        ServiceReference getReference​(Record record)
        Gets a service reference from the given record.
        Parameters:
        record - the chosen record
        Returns:
        the service reference, that allows retrieving the service object. Once called the service reference is cached, and need to be released.

      • getReferenceWithConfiguration

        ServiceReference getReferenceWithConfiguration​(Record record,
                                               JsonObject configuration)
        Gets a service reference from the given record, the reference is configured with the given json object.
        Parameters:
        record - the chosen record
        configuration - the configuration
        Returns:
        the service reference, that allows retrieving the service object. Once called the service reference is cached, and need to be released.

      • release

        boolean release​(ServiceReference reference)
        Releases the service reference.
        Parameters:
        reference - the reference to release, must not be null
        Returns:
        whether or not the reference has been released.

      • registerServiceImporter

        Future<Void> registerServiceImporter​(ServiceImporter importer,
                                     JsonObject configuration)
        Registers a discovery service importer. Importers let you integrate other discovery technologies in this service discovery.
        Parameters:
        importer - the service importer
        configuration - the optional configuration
        Returns:
        a future notified when the importer has finished its initialization and initial imports

      • registerServiceExporter

        Future<Void> registerServiceExporter​(ServiceExporter exporter,
                                     JsonObject configuration)
        Registers a discovery bridge. Exporters let you integrate other discovery technologies in this service discovery.
        Parameters:
        exporter - the service exporter
        configuration - the optional configuration
        Returns:
        a future notified when the exporter has been correctly initialized.

      • close

        void close()
        Closes the service discovery

      • publish

        Future<Record> publish​(Record record)
        Publishes a record.
        Parameters:
        record - the record
        Returns:
        a future notified when the operation has completed (successfully or not). In case of success, the passed record has a registration id required to modify and un-register the service.

      • unpublish

        Future<Void> unpublish​(String id)
        Un-publishes a record.
        Parameters:
        id - the registration id
        Returns:
        a future notified when the operation has completed (successfully or not).

      • getRecord

        Future<Record> getRecord​(JsonObject filter)
        Lookups for a single record.

        Filters are expressed using a Json object. Each entry of the given filter will be checked against the record. All entry must match exactly the record. The entry can use the special "*" value to denotes a requirement on the key, but not on the value.

        Let's take some example: 

           { "name" = "a" } => matches records with name set fo "a"
   { "color" = "*" } => matches records with "color" set
   { "color" = "red" } => only matches records with "color" set to "red"
   { "color" = "red", "name" = "a"} => only matches records with name set to "a", and color set to "red"

        If the filter is not set (null or empty), it accepts all records.

        This method returns the first matching record.

        Parameters:
        filter - the filter.
        Returns:
        a future notified when the lookup has been completed. When there are no matching record, the operation succeeds, but the async result has no result (null).

      • getRecord

        Future<Record> getRecord​(String id)
        Looks up for a single record by its registration id.

        When there are no matching record, the operation succeeds, but the async result has no result (null).

        Parameters:
        id - the registration id
        Returns:
        a future notified when the lookup has been completed
        See Also:
        Record.getRegistration()

      • getRecord

        Future<Record> getRecord​(java.util.function.Function<Record,​Boolean> filter)
        Lookups for a single record.

        The filter is a Function taking a Record as argument and returning a boolean. You should see it as an accept method of a filter. This method return a record passing the filter.

        This method only looks for records with a UP status.

        Parameters:
        filter - the filter, must not be null. To return all records, use a function accepting all records
        Returns:
        a future notified when the lookup has been completed. When there are no matching record, the operation succeed, but the async result has no result.

      • getRecord

        Future<Record> getRecord​(java.util.function.Function<Record,​Boolean> filter,
                         boolean includeOutOfService)
        Lookups for a single record.

        The filter is a Function taking a Record as argument and returning a boolean. You should see it as an accept method of a filter. This method return a record passing the filter.

        Unlike getRecord(Function), this method may accept records with a OUT OF SERVICE status, if the includeOutOfService parameter is set to true.

        Parameters:
        filter - the filter, must not be null. To return all records, use a function accepting all records
        includeOutOfService - whether or not the filter accepts OUT OF SERVICE records
        Returns:
        a future notified when the lookup has been completed. When there are no matching record, the operation succeed, but the async result has no result.

      • getRecords

        Future<List<Record>> getRecords​(JsonObject filter)
        Lookups for a set of records. Unlike getRecord(JsonObject), this method returns all matching records.
        Parameters:
        filter - the filter - see getRecord(JsonObject)
        Returns:
        a future notified when the lookup has been completed. When there are no matching record, the operation succeed, but the async result has an empty list as result.

      • getRecords

        Future<List<Record>> getRecords​(java.util.function.Function<Record,​Boolean> filter)
        Lookups for a set of records. Unlike getRecord(Function), this method returns all matching records.

        The filter is a Function taking a Record as argument and returning a boolean. You should see it as an accept method of a filter. This method return a record passing the filter.

        This method only looks for records with a UP status.

        Parameters:
        filter - the filter, must not be null. To return all records, use a function accepting all records
        Returns:
        a future notified when the lookup has been completed. When there are no matching record, the operation succeed, but the async result has an empty list as result.

      • getRecords

        Future<List<Record>> getRecords​(java.util.function.Function<Record,​Boolean> filter,
                                boolean includeOutOfService)
        Lookups for a set of records. Unlike getRecord(Function), this method returns all matching records.

        The filter is a Function taking a Record as argument and returning a boolean. You should see it as an accept method of a filter. This method return a record passing the filter.

        Unlike getRecords(Function), this method may accept records with a OUT OF SERVICE status, if the includeOutOfService parameter is set to true.

        Parameters:
        filter - the filter, must not be null. To return all records, use a function accepting all records
        includeOutOfService - whether the filter accepts OUT OF SERVICE records
        Returns:
        a future notified when the lookup has been completed. When there are no matching record, the operation succeed, but the async result has an empty list as result.

      • update

        Future<Record> update​(Record record)
        Updates the given record. The record must has been published, and has it's registration id set.
        Parameters:
        record - the updated record
        Returns:
        a future notified when the lookup has been completed.

      • bindings

        Set<ServiceReference> bindings()
        Returns:
        the set of service references retrieved by this service discovery.

      • options

        ServiceDiscoveryOptions options()
        Returns:
        the discovery options. Modifying the returned object would not update the discovery service configuration. This object should be considered as read-only.

      • releaseServiceObject

        static void releaseServiceObject​(ServiceDiscovery discovery,
                                 Object svcObject)
        Release the service object retrieved using get methods from the service type interface. It searches for the reference associated with the given object and release it.
        Parameters:
        discovery - the service discovery
        svcObject - the service object