io.vertx.servicediscovery

## Interface ServiceReference

- All Known Implementing Classes:
    AbstractServiceReference

      public interface ServiceReference

  Once a consumer has chosen a service, it builds a `ServiceReference` managing the binding with the chosen service provider.

  The reference lets the consumer: * access the service (via a proxy or a client) with the `get()` method * release the reference - so the binding between the consumer and the provider is removed

  Author:
    Clement Escoffier

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `<T> T` | `cached()` Gets the service object if already retrieved.
    `<X> X` | `cachedAs(Class<X> x)` Gets the service object if already retrieved.
    `<T> T` | `get()` Gets the object to access the service.
    `<X> X` | `getAs(Class<X> x)` Gets the object to access the service.
    `boolean` | `isHolding(Object object)` Checks whether or not the service reference has the given service object.
    `Record` | `record()`
    `void` | `release()` Releases the reference.

- - ### Method Detail

    - #### record

          Record record()

      Returns:
        the service record.

    - #### get

          <T> T get()

      Gets the object to access the service. It can be a proxy, a client or whatever object. The type depends on the service type and the server itself. This method returns the Java version and primary facet of the object, use `getAs(Class)` to retrieve the polyglot instance of the object or another facet..
      Returns:
        the object to access the service

    - #### getAs

          <X> X getAs(Class<X> x)

      Gets the object to access the service. It can be a proxy, a client or whatever object. The type depends on the service type and the server itself. This method wraps the service object into the desired type.
      Type Parameters:
        `X` - the type of object
      Parameters:
        `x` - the type of object
      Returns:
        the object to access the service wrapped to the given type

    - #### cachedAs

          <X> X cachedAs(Class<X> x)

      Gets the service object if already retrieved. It won't try to acquire the service object if not retrieved yet. Unlike `cached()`, this method return the warpped object to the desired (given) type.
      Type Parameters:
        `X` - the type of object
      Parameters:
        `x` - the type of object
      Returns:
        the object, `null` if not yet retrieved

    - #### cached

          <T> T cached()

      Gets the service object if already retrieved. It won't try to acquire the service object if not retrieved yet.
      Returns:
        the object, `null` if not yet retrieved

    - #### release

          void release()

      Releases the reference. Once released, the consumer must not use the reference anymore. This method must be idempotent and defensive, as multiple call may happen.

    - #### isHolding

          boolean isHolding(Object object)

      Checks whether or not the service reference has the given service object.
      Parameters:
        `object` - the service object, must not be `null`
      Returns:
        `true` if the service reference service object is equal to the given object, `false` otherwise.

Copyright © 2017. All rights reserved.