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

- - ### Field Summary

    Fields
    Modifier and Type | Field | 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
    Modifier and Type | Method | 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​(JsonObject filter)` | Lookups for a single record.
    `Future<Record>` | `getRecord​(String id)` | Looks up for a single record by its registration `id`.
    `Future<Record>` | `getRecord​(Function<Record,​Boolean> filter)` | Lookups for a single record.
    `Future<Record>` | `getRecord​(Function<Record,​Boolean> filter, boolean includeOutOfService)` | Lookups for a single record.
    `Future<List<Record>>` | `getRecords​(JsonObject filter)` | Lookups for a set of records.
    `Future<List<Record>>` | `getRecords​(Function<Record,​Boolean> filter)` | Lookups for a set of records.
    `Future<List<Record>>` | `getRecords​(Function<Record,​Boolean> filter, boolean includeOutOfService)` | 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)` | Publishes a record.
    `Future<Void>` | `registerServiceExporter​(ServiceExporter exporter, JsonObject configuration)` | Registers a discovery bridge.
    `Future<Void>` | `registerServiceImporter​(ServiceImporter importer, JsonObject configuration)` | 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)` | Un-publishes a record.
    `Future<Record>` | `update​(Record record)` | 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)

      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​(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​(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​(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​(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