Package io.vertx.reactivex.servicediscovery

## Class ServiceDiscovery

- java.lang.Object
- - io.vertx.reactivex.servicediscovery.ServiceDiscovery

-     public class ServiceDiscovery
      extends Object

  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.

  NOTE: This class has been automatically generated from the `original` non RX-ified interface using Vert.x codegen.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static io.vertx.lang.rx.TypeArg<ServiceDiscovery>` | `__TYPE_ARG` |
    `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`.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ServiceDiscovery​(ServiceDiscovery delegate)` |
    `ServiceDiscovery​(Object delegate)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete 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`.
    `boolean` | `equals​(Object o)` |
    `ServiceDiscovery` | `getDelegate()` |
    `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​(java.util.function.Function<Record,​Boolean> filter)` | Lookups for a single record.
    `Future<Record>` | `getRecord​(java.util.function.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​(java.util.function.Function<Record,​Boolean> filter)` | Lookups for a set of records.
    `Future<List<Record>>` | `getRecords​(java.util.function.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.
    `int` | `hashCode()` |
    `static ServiceDiscovery` | `newInstance​(ServiceDiscovery arg)` |
    `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.
    `Maybe<Record>` | `rxGetRecord​(JsonObject filter)` | Lookups for a single record.
    `Maybe<Record>` | `rxGetRecord​(String id)` | Looks up for a single record by its registration `id`.
    `Maybe<Record>` | `rxGetRecord​(java.util.function.Function<Record,​Boolean> filter)` | Lookups for a single record.
    `Maybe<Record>` | `rxGetRecord​(java.util.function.Function<Record,​Boolean> filter, boolean includeOutOfService)` | Lookups for a single record.
    `Single<List<Record>>` | `rxGetRecords​(JsonObject filter)` | Lookups for a set of records.
    `Single<List<Record>>` | `rxGetRecords​(java.util.function.Function<Record,​Boolean> filter)` | Lookups for a set of records.
    `Single<List<Record>>` | `rxGetRecords​(java.util.function.Function<Record,​Boolean> filter, boolean includeOutOfService)` | Lookups for a set of records.
    `Single<Record>` | `rxPublish​(Record record)` | Publishes a record.
    `Completable` | `rxRegisterServiceExporter​(ServiceExporter exporter, JsonObject configuration)` | Registers a discovery bridge.
    `Completable` | `rxRegisterServiceImporter​(ServiceImporter importer, JsonObject configuration)` | Registers a discovery service importer.
    `Completable` | `rxUnpublish​(String id)` | Un-publishes a record.
    `Single<Record>` | `rxUpdate​(Record record)` | Updates the given record.
    `String` | `toString()` |
    `Future<Void>` | `unpublish​(String id)` | Un-publishes a record.
    `Future<Record>` | `update​(Record record)` | Updates the given record.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### __TYPE_ARG

          public static final io.vertx.lang.rx.TypeArg<ServiceDiscovery> __TYPE_ARG

    - #### EVENT_TYPE

          public static final String EVENT_TYPE

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

    - #### EVENT_TYPE_BIND

          public static final String EVENT_TYPE_BIND

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

    - #### EVENT_TYPE_RELEASE

          public static final String EVENT_TYPE_RELEASE

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

    - #### EVENT_RECORD

          public static final String EVENT_RECORD

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

    - #### EVENT_ID

          public static final String EVENT_ID

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

  - ### Constructor Detail

    - #### ServiceDiscovery

          public ServiceDiscovery​(ServiceDiscovery delegate)

    - #### ServiceDiscovery

          public ServiceDiscovery​(Object delegate)

  - ### Method Detail

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### equals

          public boolean equals​(Object o)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### getDelegate

          public ServiceDiscovery getDelegate()

    - #### create

          public 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

          public 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

          public 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

          public 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

          public 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

          public 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

    - #### rxRegisterServiceImporter

          public Completable rxRegisterServiceImporter​(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

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

    - #### rxRegisterServiceExporter

          public Completable rxRegisterServiceExporter​(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

          public void close()

      Closes the service discovery

    - #### publish

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

    - #### rxPublish

          public Single<Record> rxPublish​(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

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

    - #### rxUnpublish

          public Completable rxUnpublish​(String id)

      Un-publishes a record.
      Parameters:
        `id` - the registration id
      Returns:
        a future notified when the operation has completed (successfully or not).

    - #### getRecord

          public 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`).

    - #### rxGetRecord

          public Maybe<Record> rxGetRecord​(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

          public 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

    - #### rxGetRecord

          public Maybe<Record> rxGetRecord​(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

    - #### getRecord

          public Future<Record> getRecord​(java.util.function.Function<Record,​Boolean> filter)

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

    - #### rxGetRecord

          public Maybe<Record> rxGetRecord​(java.util.function.Function<Record,​Boolean> filter)

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

          public Future<Record> getRecord​(java.util.function.Function<Record,​Boolean> filter,
                                          boolean includeOutOfService)

      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 `getRecord(io.vertx.core.json.JsonObject)`, 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.

    - #### rxGetRecord

          public Maybe<Record> rxGetRecord​(java.util.function.Function<Record,​Boolean> filter,
                                           boolean includeOutOfService)

      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 `getRecord(io.vertx.core.json.JsonObject)`, 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

          public Future<List<Record>> getRecords​(JsonObject filter)

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

    - #### rxGetRecords

          public Single<List<Record>> rxGetRecords​(JsonObject filter)

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

          public Future<List<Record>> getRecords​(java.util.function.Function<Record,​Boolean> filter)

      Lookups for a set of records. Unlike `getRecord(io.vertx.core.json.JsonObject)`, 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
      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.

    - #### rxGetRecords

          public Single<List<Record>> rxGetRecords​(java.util.function.Function<Record,​Boolean> filter)

      Lookups for a set of records. Unlike `getRecord(io.vertx.core.json.JsonObject)`, 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
      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

          public Future<List<Record>> getRecords​(java.util.function.Function<Record,​Boolean> filter,
                                                 boolean includeOutOfService)

      Lookups for a set of records. Unlike `getRecord(io.vertx.core.json.JsonObject)`, 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 `getRecords(io.vertx.core.json.JsonObject)`, 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.

    - #### rxGetRecords

          public Single<List<Record>> rxGetRecords​(java.util.function.Function<Record,​Boolean> filter,
                                                   boolean includeOutOfService)

      Lookups for a set of records. Unlike `getRecord(io.vertx.core.json.JsonObject)`, 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 `getRecords(io.vertx.core.json.JsonObject)`, 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

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

    - #### rxUpdate

          public Single<Record> rxUpdate​(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

          public Set<ServiceReference> bindings()

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

    - #### options

          public 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

          public 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

    - #### newInstance

          public static ServiceDiscovery newInstance​(ServiceDiscovery arg)