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 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, Handler<ServiceDiscovery> completionHandler)` Creates a new instance of `ServiceDiscovery` using the default configuration.
    `static ServiceDiscovery` | `create(Vertx vertx, ServiceDiscoveryOptions options)` Creates an instance of `ServiceDiscovery`.
    `static ServiceDiscovery` | `create(Vertx vertx, ServiceDiscoveryOptions options, Handler<ServiceDiscovery> completionHandler)` Creates an instance of `ServiceDiscovery`.
    `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.
    `void` | `getRecord(JsonObject filter, Handler<AsyncResult<Record>> resultHandler)` Lookups for a single record.
    `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.
    `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()`
    `void` | `publish(Record record, Handler<AsyncResult<Record>> resultHandler)` Publishes a record.
    `ServiceDiscovery` | `registerServiceExporter(ServiceExporter exporter, JsonObject configuration)` Registers a discovery bridge.
    `ServiceDiscovery` | `registerServiceExporter(ServiceExporter exporter, JsonObject configuration, Handler<AsyncResult<Void>> completionHandler)` Registers a discovery bridge.
    `ServiceDiscovery` | `registerServiceImporter(ServiceImporter importer, JsonObject configuration)` Registers a discovery service importer.
    `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.
    `void` | `unpublish(String id, Handler<AsyncResult<Void>> resultHandler)` Un-publishes a record.
    `void` | `update(Record record, Handler<AsyncResult<Record>> resultHandler)` Updates the given record.

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

    - #### create

          static ServiceDiscovery create(Vertx vertx,
                                         ServiceDiscoveryOptions options,
                                         Handler<ServiceDiscovery> completionHandler)

      Creates an instance of `ServiceDiscovery`.
      Parameters:
        `vertx` - the vert.x instance
        `options` - the discovery options
        `completionHandler` - completion handler called when the service discovery has been initialized. This includes the initialization of the service importer registered from the SPI.
      Returns:
        the created instance, should not be used to retrieve services before the invocation of the completion handler.

    - #### create

          static ServiceDiscovery create(Vertx vertx,
                                         Handler<ServiceDiscovery> completionHandler)

      Creates a new instance of `ServiceDiscovery` using the default configuration.
      Parameters:
        `vertx` - the vert.x instance
        `completionHandler` - completion handler called when the service discovery has been initialized. This includes the initialization of the service importer registered from the SPI.
      Returns:
        the created instance, should not be used to retrieve services before the invocation of the completion handler.

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

          ServiceDiscovery 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:
        the current `ServiceDiscovery`

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

          ServiceDiscovery 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:
        the current `ServiceDiscovery`

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

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

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

          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

          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.

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

          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

          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.

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

    - #### 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 © 2017. All rights reserved.