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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `EVENT_ID` Constant for id field of usage events.
    `static String` | `EVENT_RECORD` Constant for record field of usage events.
    `static String` | `EVENT_TYPE` Constant for type field of usage events.
    `static String` | `EVENT_TYPE_BIND` Constant for event type `Bind`.
    `static String` | `EVENT_TYPE_RELEASE` Constant for event type `Release`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `Set<ServiceReference>` | `bindings()`
    `void` | `close()` Closes the service discovery
    `static ServiceDiscovery` | `create(Vertx vertx)` Creates a new instance of `ServiceDiscovery` using the default configuration.
    `static ServiceDiscovery` | `create(Vertx vertx, ServiceDiscoveryOptions options)` Creates an instance of `ServiceDiscovery`.
    `Future<Record>` | `getRecord(java.util.function.Function<Record,Boolean> filter)` Like `getRecord(Function, Handler)` but returns a `Future` of the asynchronous result
    `Future<Record>` | `getRecord(java.util.function.Function<Record,Boolean> filter, boolean includeOutOfService)` Like `getRecords(Function, boolean, Handler)` but returns a `Future` of the asynchronous result
    `void` | `getRecord(java.util.function.Function<Record,Boolean> filter, boolean includeOutOfService, Handler<AsyncResult<Record>> resultHandler)` Lookups for a single record.
    `void` | `getRecord(java.util.function.Function<Record,Boolean> filter, Handler<AsyncResult<Record>> resultHandler)` Lookups for a single record.
    `Future<Record>` | `getRecord(JsonObject filter)` Like `getRecord(JsonObject, Handler)` but returns a `Future` of the asynchronous result
    `void` | `getRecord(JsonObject filter, Handler<AsyncResult<Record>> resultHandler)` Lookups for a single record.
    `Future<Record>` | `getRecord(String id)` Like `getRecord(String, Handler)` but returns a `Future` of the asynchronous result
    `void` | `getRecord(String id, Handler<AsyncResult<Record>> resultHandler)` Looks up for a single record by its registration `id`.
    `Future<List<Record>>` | `getRecords(java.util.function.Function<Record,Boolean> filter)` Like `getRecords(Function, Handler)` but returns a `Future` of the asynchronous result
    `Future<List<Record>>` | `getRecords(java.util.function.Function<Record,Boolean> filter, boolean includeOutOfService)` Like `getRecords(Function, boolean, Handler)` but returns a `Future` of the asynchronous result
    `void` | `getRecords(java.util.function.Function<Record,Boolean> filter, boolean includeOutOfService, Handler<AsyncResult<List<Record>>> resultHandler)` Lookups for a set of records.
    `void` | `getRecords(java.util.function.Function<Record,Boolean> filter, Handler<AsyncResult<List<Record>>> resultHandler)` Lookups for a set of records.
    `Future<List<Record>>` | `getRecords(JsonObject filter)` Like `getRecords(JsonObject, Handler)` but returns a `Future` of the asynchronous result
    `void` | `getRecords(JsonObject filter, Handler<AsyncResult<List<Record>>> resultHandler)` Lookups for a set of records.
    `ServiceReference` | `getReference(Record record)` Gets a service reference from the given record.
    `ServiceReference` | `getReferenceWithConfiguration(Record record, JsonObject configuration)` Gets a service reference from the given record, the reference is configured with the given json object.
    `ServiceDiscoveryOptions` | `options()`
    `Future<Record>` | `publish(Record record)` Like `publish(Record, Handler)` but returns a `Future` of the asynchronous result
    `void` | `publish(Record record, Handler<AsyncResult<Record>> resultHandler)` Publishes a record.
    `Future<Void>` | `registerServiceExporter(ServiceExporter exporter, JsonObject configuration)` Like `registerServiceExporter(ServiceExporter, JsonObject, Handler)` but returns a `Future` of the asynchronous result
    `ServiceDiscovery` | `registerServiceExporter(ServiceExporter exporter, JsonObject configuration, Handler<AsyncResult<Void>> completionHandler)` Registers a discovery bridge.
    `Future<Void>` | `registerServiceImporter(ServiceImporter importer, JsonObject configuration)` Like `registerServiceImporter(ServiceImporter, JsonObject, Handler)` but returns a `Future` of the asynchronous result
    `ServiceDiscovery` | `registerServiceImporter(ServiceImporter importer, JsonObject configuration, Handler<AsyncResult<Void>> completionHandler)` Registers a discovery service importer.
    `boolean` | `release(ServiceReference reference)` Releases the service reference.
    `static void` | `releaseServiceObject(ServiceDiscovery discovery, Object svcObject)` Release the service object retrieved using `get` methods from the service type interface.
    `Future<Void>` | `unpublish(String id)` Like `unpublish(String, Handler)` but returns a `Future` of the asynchronous result
    `void` | `unpublish(String id, Handler<AsyncResult<Void>> resultHandler)` Un-publishes a record.
    `Future<Record>` | `update(Record record)` Like `update(Record, Handler)` but returns a `Future` of the asynchronous result
    `void` | `update(Record record, Handler<AsyncResult<Record>> resultHandler)` Updates the given record.

- - ### Field Detail

    - #### EVENT_TYPE

          static final String EVENT_TYPE

      Constant for type field of usage events.
      See Also:
        `EVENT_TYPE_BIND`, `EVENT_TYPE_RELEASE`, Constant Field Values

    - #### EVENT_TYPE_BIND

          static final String EVENT_TYPE_BIND

      Constant for event type `Bind`.
      See Also:
        `EVENT_TYPE`, Constant Field Values

    - #### EVENT_TYPE_RELEASE

          static final String EVENT_TYPE_RELEASE

      Constant for event type `Release`.
      See Also:
        `EVENT_TYPE`, Constant Field Values

    - #### EVENT_RECORD

          static final String EVENT_RECORD

      Constant for record field of usage events.
      See Also:
        Constant Field Values

    - #### EVENT_ID

          static final String EVENT_ID

      Constant for id field of usage events.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### create

          static ServiceDiscovery create(Vertx vertx,
                                         ServiceDiscoveryOptions options)

      Creates an instance of `ServiceDiscovery`.
      Parameters:
        `vertx` - the vert.x instance
        `options` - the discovery options
      Returns:
        the created service discovery instance.

    - #### 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)

      Like `registerServiceImporter(ServiceImporter, JsonObject, Handler)` but returns a `Future` of the asynchronous result

    - #### registerServiceImporter

          ServiceDiscovery registerServiceImporter(ServiceImporter importer,
                                                   JsonObject configuration,
                                                   Handler<AsyncResult<Void>> completionHandler)

      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
        `completionHandler` - handler call when the importer has finished its initialization and initial imports
      Returns:
        the current `ServiceDiscovery`

    - #### registerServiceExporter

          Future<Void> registerServiceExporter(ServiceExporter exporter,
                                               JsonObject configuration)

      Like `registerServiceExporter(ServiceExporter, JsonObject, Handler)` but returns a `Future` of the asynchronous result

    - #### registerServiceExporter

          ServiceDiscovery registerServiceExporter(ServiceExporter exporter,
                                                   JsonObject configuration,
                                                   Handler<AsyncResult<Void>> completionHandler)

      Registers a discovery bridge. Exporters let you integrate other discovery technologies in this service discovery.
      Parameters:
        `exporter` - the service exporter
        `configuration` - the optional configuration
        `completionHandler` - handler notified when the exporter has been correctly initialized.
      Returns:
        the current `ServiceDiscovery`

    - #### close

          void close()

      Closes the service discovery

    - #### publish

          void publish(Record record,
                       Handler<AsyncResult<Record>> resultHandler)

      Publishes a record.
      Parameters:
        `record` - the record
        `resultHandler` - handler called 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.

    - #### publish

          Future<Record> publish(Record record)

      Like `publish(Record, Handler)` but returns a `Future` of the asynchronous result

    - #### unpublish

          void unpublish(String id,
                         Handler<AsyncResult<Void>> resultHandler)

      Un-publishes a record.
      Parameters:
        `id` - the registration id
        `resultHandler` - handler called when the operation has completed (successfully or not).

    - #### unpublish

          Future<Void> unpublish(String id)

      Like `unpublish(String, Handler)` but returns a `Future` of the asynchronous result

    - #### getRecord

          void getRecord(JsonObject filter,
                         Handler<AsyncResult<Record>> resultHandler)

      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.
        `resultHandler` - handler called 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(JsonObject filter)

      Like `getRecord(JsonObject, Handler)` but returns a `Future` of the asynchronous result

    - #### getRecord

          void getRecord(String id,
                         Handler<AsyncResult<Record>> resultHandler)

      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
        `resultHandler` - handler called when the lookup has been completed
      See Also:
        `Record.getRegistration()`

    - #### getRecord

          Future<Record> getRecord(String id)

      Like `getRecord(String, Handler)` but returns a `Future` of the asynchronous result

    - #### getRecord

          void getRecord(java.util.function.Function<Record,Boolean> filter,
                         Handler<AsyncResult<Record>> resultHandler)

      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
        `resultHandler` - the result handler called 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)

      Like `getRecord(Function, Handler)` but returns a `Future` of the asynchronous result

    - #### getRecord

          void getRecord(java.util.function.Function<Record,Boolean> filter,
                         boolean includeOutOfService,
                         Handler<AsyncResult<Record>> resultHandler)

      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, Handler)`, 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
        `resultHandler` - the result handler called 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)

      Like `getRecords(Function, boolean, Handler)` but returns a `Future` of the asynchronous result

    - #### getRecords

          void getRecords(JsonObject filter,
                          Handler<AsyncResult<List<Record>>> resultHandler)

      Lookups for a set of records. Unlike `getRecord(JsonObject, Handler)`, this method returns all matching records.
      Parameters:
        `filter` - the filter - see `getRecord(JsonObject, Handler)`
        `resultHandler` - handler called 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(JsonObject filter)

      Like `getRecords(JsonObject, Handler)` but returns a `Future` of the asynchronous result

    - #### getRecords

          void getRecords(java.util.function.Function<Record,Boolean> filter,
                          Handler<AsyncResult<List<Record>>> resultHandler)

      Lookups for a set of records. Unlike `getRecord(Function, Handler)`, 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
        `resultHandler` - handler called 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)

      Like `getRecords(Function, Handler)` but returns a `Future` of the asynchronous result

    - #### getRecords

          void getRecords(java.util.function.Function<Record,Boolean> filter,
                          boolean includeOutOfService,
                          Handler<AsyncResult<List<Record>>> resultHandler)

      Lookups for a set of records. Unlike `getRecord(Function, Handler)`, 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, Handler)`, 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
        `resultHandler` - handler called 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)

      Like `getRecords(Function, boolean, Handler)` but returns a `Future` of the asynchronous result

    - #### update

          void update(Record record,
                      Handler<AsyncResult<Record>> resultHandler)

      Updates the given record. The record must has been published, and has it's registration id set.
      Parameters:
        `record` - the updated record
        `resultHandler` - handler called when the lookup has been completed.

    - #### update

          Future<Record> update(Record record)

      Like `update(Record, Handler)` but returns a `Future` of the asynchronous result

    - #### 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

Copyright © 2023 Eclipse. All rights reserved.