Package: io.vertx.groovy.servicediscovery

## [Groovy] Class ServiceDiscovery

- io.vertx.groovy.servicediscovery.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 Record.

  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.

- - ### Constructor Summary

    Constructors
    Constructor and description
    `ServiceDiscovery (java.lang.Object delegate)`

  - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `java.util.Set<ServiceReference>` | `bindings()` Returns: the set of service references retrieved by this service discovery.
    `void` | `close()` Closes the service discovery
    `static ServiceDiscovery` | `create(Vertx vertx, java.util.Map<java.lang.String, java.lang.Object> options)` Creates an instance of ServiceDiscovery.
    `static ServiceDiscovery` | `create(Vertx vertx)` Creates a new instance of ServiceDiscovery using the default configuration.
    `java.lang.Object` | `getDelegate()`
    `void` | `getRecord(java.util.Map<java.lang.String, java.lang.Object> filter, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)` Lookups for a single record.
    `void` | `getRecord(java.util.function.Function<java.util.Map<java.lang.String, java.lang.Object>, java.lang.Boolean> filter, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)` Lookups for a single record.
    `void` | `getRecord(java.util.function.Function<java.util.Map<java.lang.String, java.lang.Object>, java.lang.Boolean> filter, boolean includeOutOfService, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)` Lookups for a single record.
    `void` | `getRecords(java.util.Map<java.lang.String, java.lang.Object> filter, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.List<java.util.Map<java.lang.String, java.lang.Object>>>> resultHandler)` Lookups for a set of records.
    `void` | `getRecords(java.util.function.Function<java.util.Map<java.lang.String, java.lang.Object>, java.lang.Boolean> filter, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.List<java.util.Map<java.lang.String, java.lang.Object>>>> resultHandler)` Lookups for a set of records.
    `void` | `getRecords(java.util.function.Function<java.util.Map<java.lang.String, java.lang.Object>, java.lang.Boolean> filter, boolean includeOutOfService, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.List<java.util.Map<java.lang.String, java.lang.Object>>>> resultHandler)` Lookups for a set of records.
    `ServiceReference` | `getReference(java.util.Map<java.lang.String, java.lang.Object> record = [:])` Gets a service reference from the given record.
    `ServiceReference` | `getReferenceWithConfiguration(java.util.Map<java.lang.String, java.lang.Object> record = [:], java.util.Map<java.lang.String, java.lang.Object> configuration)` Gets a service reference from the given record, the reference is configured with the given json object.
    `void` | `publish(java.util.Map<java.lang.String, java.lang.Object> record = [:], io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)` Publishes a record.
    `ServiceDiscovery` | `registerServiceExporter(ServiceExporter exporter, java.util.Map<java.lang.String, java.lang.Object> configuration)` Registers a discovery bridge.
    `ServiceDiscovery` | `registerServiceImporter(ServiceImporter importer, java.util.Map<java.lang.String, java.lang.Object> configuration)` Registers a discovery service importer.
    `boolean` | `release(ServiceReference reference)` Releases the service reference.
    `static void` | `releaseServiceObject(ServiceDiscovery discovery, java.lang.Object svcObject)` Release the service object retrieved using `get` methods from the service type interface.
    `void` | `unpublish(java.lang.String id, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>> resultHandler)` Un-publishes a record.
    `void` | `update(java.util.Map<java.lang.String, java.lang.Object> record = [:], io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)` Updates the given record.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class java.lang.Object` | `java.lang.Object#wait(long, int), java.lang.Object#wait(long), java.lang.Object#wait(), java.lang.Object#equals(java.lang.Object), java.lang.Object#toString(), java.lang.Object#hashCode(), java.lang.Object#getClass(), java.lang.Object#notify(), java.lang.Object#notifyAll()`

- - ### Constructor Detail

    - #### ServiceDiscovery(java.lang.Object delegate)

  - ### Method Detail

    - #### java.util.Set<ServiceReference> bindings()

      Returns:
        the set of service references retrieved by this service discovery.

    - #### void close()

      Closes the service discovery

    - #### static ServiceDiscovery create(Vertx vertx, java.util.Map<java.lang.String, java.lang.Object> options)

      Creates an instance of ServiceDiscovery.

      Returns:
        the created service discovery instance.
      Parameters:
        `vertx` - the vert.x instance
        `options` - the discovery options (see ServiceDiscoveryOptions)

    - #### static ServiceDiscovery create(Vertx vertx)

      Creates a new instance of ServiceDiscovery using the default configuration.

      Returns:
        the created instance
      Parameters:
        `vertx` - the vert.x instance

    - #### java.lang.Object getDelegate()

    - #### void getRecord(java.util.Map<java.lang.String, java.lang.Object> filter, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> 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 succeed, but the async result has no result.

    - #### void getRecord(java.util.function.Function<java.util.Map<java.lang.String, java.lang.Object>, java.lang.Boolean> filter, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)

      Lookups for a single record.

      The filter is a 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.

    - #### void getRecord(java.util.function.Function<java.util.Map<java.lang.String, java.lang.Object>, java.lang.Boolean> filter, boolean includeOutOfService, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)

      Lookups for a single record.

      The filter is a 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 ServiceDiscovery.getRecord, 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.

    - #### void getRecords(java.util.Map<java.lang.String, java.lang.Object> filter, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.List<java.util.Map<java.lang.String, java.lang.Object>>>> resultHandler)

      Lookups for a set of records. Unlike ServiceDiscovery.getRecord, this method returns all matching records.

      Parameters:
        `filter` - the filter - see ServiceDiscovery.getRecord
        `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.

    - #### void getRecords(java.util.function.Function<java.util.Map<java.lang.String, java.lang.Object>, java.lang.Boolean> filter, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.List<java.util.Map<java.lang.String, java.lang.Object>>>> resultHandler)

      Lookups for a set of records. Unlike ServiceDiscovery.getRecord, this method returns all matching records.

      The filter is a 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.

    - #### void getRecords(java.util.function.Function<java.util.Map<java.lang.String, java.lang.Object>, java.lang.Boolean> filter, boolean includeOutOfService, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.List<java.util.Map<java.lang.String, java.lang.Object>>>> resultHandler)

      Lookups for a set of records. Unlike ServiceDiscovery.getRecord, this method returns all matching records.

      The filter is a 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 ServiceDiscovery.getRecords, 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.

    - #### ServiceReference getReference(java.util.Map<java.lang.String, java.lang.Object> record = [:])

      Gets a service reference from the given record.

      Returns:
        the service reference, that allows retrieving the service object. Once called the service reference is cached, and need to be released.
      Parameters:
        `record` - the chosen record (see Record)

    - #### ServiceReference getReferenceWithConfiguration(java.util.Map<java.lang.String, java.lang.Object> record = [:], java.util.Map<java.lang.String, java.lang.Object> configuration)

      Gets a service reference from the given record, the reference is configured with the given json object.

      Returns:
        the service reference, that allows retrieving the service object. Once called the service reference is cached, and need to be released.
      Parameters:
        `record` - the chosen record (see Record)
        `configuration` - the configuration

    - #### void publish(java.util.Map<java.lang.String, java.lang.Object> record = [:], io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)

      Publishes a record.

      Parameters:
        `record` - the record (see 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.

    - #### ServiceDiscovery registerServiceExporter(ServiceExporter exporter, java.util.Map<java.lang.String, java.lang.Object> configuration)

      Registers a discovery bridge. Exporters let you integrate other discovery technologies in this service discovery.

      Returns:
        the current ServiceDiscovery
      Parameters:
        `exporter` - the service exporter
        `configuration` - the optional configuration

    - #### ServiceDiscovery registerServiceImporter(ServiceImporter importer, java.util.Map<java.lang.String, java.lang.Object> configuration)

      Registers a discovery service importer. Importers let you integrate other discovery technologies in this service discovery.

      Returns:
        the current ServiceDiscovery
      Parameters:
        `importer` - the service importer
        `configuration` - the optional configuration

    - #### boolean release(ServiceReference reference)

      Releases the service reference.

      Returns:
        whether or not the reference has been released.
      Parameters:
        `reference` - the reference to release, must not be `null`

    - #### static void releaseServiceObject(ServiceDiscovery discovery, java.lang.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

    - #### void unpublish(java.lang.String id, io.vertx.core.Handler<io.vertx.core.AsyncResult<java.lang.Void>> resultHandler)

      Un-publishes a record.

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

    - #### void update(java.util.Map<java.lang.String, java.lang.Object> record = [:], io.vertx.core.Handler<io.vertx.core.AsyncResult<java.util.Map<java.lang.String, java.lang.Object>>> resultHandler)

      Updates the given record. The record must has been published, and has it's registration id set.

      Parameters:
        `record` - the updated record (see Record)
        `resultHandler` - handler called when the lookup has been completed.