/*
* Copyright (c) 2011-2016 The original author or authors
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* and Apache License v2.0 which accompanies this distribution.
*
* The Eclipse Public License is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* The Apache License v2.0 is available at
* http://www.opensource.org/licenses/apache2.0.php
*
* You may elect to redistribute this code under either of these licenses.
*/
package io.vertx.servicediscovery;
import io.vertx.codegen.annotations.CacheReturn;
import io.vertx.codegen.annotations.VertxGen;
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
/**
* Once a consumer has chosen a service, it builds a {@link ServiceReference} managing the binding with the chosen
* service provider.
* <p>
* The reference lets the consumer:
* * access the service (via a proxy or a client) with the {@link #get()} method
* * release the reference - so the binding between the consumer and the provider is removed
*
* @author <a href="http://escoffier.me">Clement Escoffier</a>
*/
@VertxGen
public interface ServiceReference extends AutoCloseable {
Returns: the service record.
/**
* @return the service record.
*/
@CacheReturn
Record record();
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<Object>)
to retrieve the polyglot instance of the object or another facet.. Returns: the object to access the service
/**
* 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
* {@link #getAs(Class)} to retrieve the polyglot instance of the object or another facet..
*
* @return the object to access the service
*/
<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 wraps the service object into the desired type.
Params: - x – the type of object
Type parameters: - <X> – the type of object
Returns: the object to access the service wrapped to the given type
/**
* 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.
*
* @param x the type of object
* @param <X> the type of object
* @return the object to access the service wrapped to the given type
*/
<X> X getAs(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. Params: - x – the type of object
Type parameters: - <X> – the type of object
Returns: the object, null
if not yet retrieved
/**
* Gets the service object if already retrieved. It won't try to acquire the service object if not retrieved yet.
* Unlike {@link #cached()}, this method return the warpped object to the desired (given) type.
*
* @param x the type of object
* @param <X> the type of object
* @return the object, {@code null} if not yet retrieved
*/
<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.
Returns: the object, null
if not yet retrieved
/**
* Gets the service object if already retrieved. It won't try to acquire the service object if not retrieved yet.
*
* @return the object, {@code null} if not yet retrieved
*/
<T> T cached();
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.
/**
* 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.
*/
void release();
Checks whether or not the service reference has the given service object.
Params: - object – the service object, must not be
null
Returns: true
if the service reference service object is equal to the given object, false
otherwise.
/**
* Checks whether or not the service reference has the given service object.
*
* @param object the service object, must not be {@code null}
* @return {@code true} if the service reference service object is equal to the given object, {@code false} otherwise.
*/
boolean isHolding(Object object);
}