public class ResourceClient extends Object implements ResourceManager<ResourceClient>
Resources remotely.
This ResourceClient implementation facilitates working with Resources remotely as
a client of the Atomix cluster. To create a client, construct a client builder via builder(Address...).
The builder requires a list of Addresses to which to connect.
List<Address> servers = Arrays.asList(
new Address("123.456.789.0", 5000),
new Address("123.456.789.1", 5000)
);
ResourceManager manager = ResourceClient.builder(servers)
.withTransport(new NettyTransport())
.build();
The Address list does not have to include all servers in the cluster, but must include at least one live
server in order for the client to connect. Once the client connects to the cluster and opens a session, the client
will receive an updated list of servers to which to connect.
Clients communicate with the cluster via a Transport. By default, the NettyTransport is used if
no transport is explicitly configured. Thus, if no transport is configured then the Netty transport is expected
to be available on the classpath.
Client lifecycle
When a client is connected, the client will attempt to contact random servers in the provided
Address list to open a new session. Opening a client session requires only that the client be able to
communicate with at least one server which can communicate with the leader. Once a session has been opened,
the client will periodically send keep-alive requests to the cluster to maintain its session. In the event
that the client crashes or otherwise becomes disconnected from the cluster, the client's session will expire
after a configured session timeout and the client will have to open a new session to reconnect.
Clients may connect to and communicate with any server in the cluster. Typically, once a client connects to a server, the client will attempt to remain connected to that server until some exceptional case occurs. Exceptional cases may include a failure of the server, a network partition, or the server falling too far out of sync with the rest of the cluster. When a failure in the cluster occurs and the client becomes disconnected from the cluster, it will transparently reconnect to random servers until it finds a reachable server.
During certain cluster events such as leadership changes, the client may not be able to communicate with the cluster for some arbitrary (but typically short) period of time. During that time, Atomix guarantees that the client's session will not expire even if its timeout elapses. Once a new leader is elected, the client's session timeout is reset.
| Modifier and Type | Class and Description |
|---|---|
static class |
ResourceClient.Builder
Builds a
ResourceClient. |
| Constructor and Description |
|---|
ResourceClient(CopycatClient client) |
| Modifier and Type | Method and Description |
|---|---|
static ResourceClient.Builder |
builder(Address... members)
Returns a new Atomix client builder.
|
static ResourceClient.Builder |
builder(Collection<Address> members)
Returns a new Atomix client builder.
|
static ResourceClient.Builder |
builder(Properties properties)
Returns a new ResourceClient builder from the given properties.
|
static ResourceClient.Builder |
builder(String properties)
Returns a new ResourceClient builder from the given configuration file.
|
CopycatClient |
client()
Returns the underlying Copycat client.
|
CompletableFuture<Void> |
close()
Closes the client.
|
CompletableFuture<ResourceClient> |
connect()
Connects the client to the cluster.
|
ThreadContext |
context()
Returns the Atomix thread context.
|
CompletableFuture<Boolean> |
exists(String key)
Checks whether a resource exists with the given key.
|
<T extends io.atomix.resource.Resource> |
getResource(String key,
Class<? super T> type)
Gets or creates the given resource and acquires a singleton reference to it.
|
<T extends io.atomix.resource.Resource> |
getResource(String key,
Class<? super T> type,
io.atomix.resource.Resource.Config config)
Gets or creates the given resource and acquires a singleton reference to it.
|
<T extends io.atomix.resource.Resource> |
getResource(String key,
Class<? super T> type,
io.atomix.resource.Resource.Config config,
io.atomix.resource.Resource.Options options)
Gets or creates the given resource and acquires a singleton reference to it.
|
<T extends io.atomix.resource.Resource> |
getResource(String key,
Class<? super T> type,
io.atomix.resource.Resource.Options options)
Gets or creates the given resource and acquires a singleton reference to it.
|
<T extends io.atomix.resource.Resource> |
getResource(String key,
io.atomix.resource.ResourceType type)
Gets or creates the given resource and acquires a singleton reference to it.
|
<T extends io.atomix.resource.Resource> |
getResource(String key,
io.atomix.resource.ResourceType type,
io.atomix.resource.Resource.Config config)
Gets or creates the given resource and acquires a singleton reference to it.
|
<T extends io.atomix.resource.Resource> |
getResource(String key,
io.atomix.resource.ResourceType type,
io.atomix.resource.Resource.Config config,
io.atomix.resource.Resource.Options options)
Gets or creates the given resource and acquires a singleton reference to it.
|
<T extends io.atomix.resource.Resource> |
getResource(String key,
io.atomix.resource.ResourceType type,
io.atomix.resource.Resource.Options options)
Gets or creates the given resource and acquires a singleton reference to it.
|
CompletableFuture<Set<String>> |
keys()
Returns keys of all existing resources.
|
<T extends io.atomix.resource.Resource> |
keys(Class<? super T> type)
Returns the keys of existing resources belonging to a resource type.
|
CompletableFuture<Set<String>> |
keys(io.atomix.resource.ResourceType type)
Returns the keys of existing resources belonging to a resource type.
|
Serializer |
serializer()
Returns the resource manager serializer.
|
CopycatClient.State |
state()
Returns the resource client state.
|
String |
toString() |
io.atomix.resource.ResourceType |
type(Class<? extends io.atomix.resource.Resource<?>> type)
Returns the resource type for the given resource class.
|
public ResourceClient(CopycatClient client)
NullPointerException - if client or registry are nullpublic static ResourceClient.Builder builder(String properties)
properties - The properties file from which to load the replica builder.public static ResourceClient.Builder builder(Properties properties)
properties - The properties from which to load the replica builder.public static ResourceClient.Builder builder(Address... members)
The provided set of members will be used to connect to the Raft cluster. The members list does not have to represent the complete list of servers in the cluster, but it must have at least one reachable member.
members - The cluster members to which to connect.NullPointerException - if members is nullpublic static ResourceClient.Builder builder(Collection<Address> members)
The provided set of members will be used to connect to the Raft cluster. The members list does not have to represent the complete list of servers in the cluster, but it must have at least one reachable member.
members - The cluster members to which to connect.public CopycatClient client()
public ThreadContext context()
ResourceManager
This context is representative of the thread on which asynchronous callbacks will be executed for this
Atomix instance. Atomix guarantees that all CompletableFutures supplied by this instance will
be executed via the returned context. Users can use the context to access the thread-local
Serializer.
context in interface ResourceManager<ResourceClient>public Serializer serializer()
ResourceManager
The serializer applies to all resources controlled by this instance. Serializable types registered
on the serializer will be reflected at the Transport layer.
Types registered on the client must also be registered on the server for deserialization.
serializer in interface ResourceManager<ResourceClient>public final io.atomix.resource.ResourceType type(Class<? extends io.atomix.resource.Resource<?>> type)
ResourceManagertype in interface ResourceManager<ResourceClient>type - The resource class.public CompletableFuture<Boolean> exists(String key)
ResourceManager
If no resource with the given key exists in the cluster, the returned CompletableFuture will
be completed false. Note, however, that users should not significantly rely upon the existence or
non-existence of a resource due to race conditions. While a resource may not exist when the returned future is
completed, it may be created by another node shortly thereafter.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
if (!atomix.exists("lock").get()) {
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
}
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.exists("lock").thenAccept(exists -> {
if (!exists) {
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
}
});
exists in interface ResourceManager<ResourceClient>key - The key to check.public CompletableFuture<Set<String>> keys()
ResourceManager
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
Collection<String> resourceKeys = atomix.keys().get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<Collection<String>>keys().thenAccept(resourceKeys -> {
...
});
keys in interface ResourceManager<ResourceClient>public <T extends io.atomix.resource.Resource> CompletableFuture<Set<String>> keys(Class<? super T> type)
ResourceManager
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
Set<String> resourceKeys = atomix.keys(DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<Set<String>>keys().thenAccept(resourceKeys -> {
...
});
keys in interface ResourceManager<ResourceClient>T - The resource type.type - The resource type by which to filter resources.public CompletableFuture<Set<String>> keys(io.atomix.resource.ResourceType type)
ResourceManager
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
Set<String> resourceKeys = atomix.keys(DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<Set<String>>keys().thenAccept(resourceKeys -> {
...
});
keys in interface ResourceManager<ResourceClient>type - The resource type by which to filter resources.public <T extends io.atomix.resource.Resource> CompletableFuture<T> getResource(String key, Class<? super T> type)
ResourceManagerIf a resource at the given key already exists, the resource will be validated to verify that its type matches the given type. If no resource yet exists, a new resource will be created in the cluster. Once the session for the resource has been opened, a resource instance will be returned.
The returned Resource instance will be a singleton reference to an global instance for this node.
That is, multiple calls to this method for the same resource will result in the same Resource
instance being returned.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
getResource in interface ResourceManager<ResourceClient>T - The resource type.key - The key at which to get the resource.type - The expected resource type.public <T extends io.atomix.resource.Resource> CompletableFuture<T> getResource(String key, Class<? super T> type, io.atomix.resource.Resource.Config config)
ResourceManagerIf a resource at the given key already exists, the resource will be validated to verify that its type matches the given type. If no resource yet exists, a new resource will be created in the cluster. Once the session for the resource has been opened, a resource instance will be returned.
The returned Resource instance will be a singleton reference to an global instance for this node.
That is, multiple calls to this method for the same resource will result in the same Resource
instance being returned.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
getResource in interface ResourceManager<ResourceClient>T - The resource type.key - The key at which to get the resource.type - The expected resource type.config - The cluster-wide resource configuration.public <T extends io.atomix.resource.Resource> CompletableFuture<T> getResource(String key, Class<? super T> type, io.atomix.resource.Resource.Options options)
ResourceManagerIf a resource at the given key already exists, the resource will be validated to verify that its type matches the given type. If no resource yet exists, a new resource will be created in the cluster. Once the session for the resource has been opened, a resource instance will be returned.
The returned Resource instance will be a singleton reference to an global instance for this node.
That is, multiple calls to this method for the same resource will result in the same Resource
instance being returned.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
getResource in interface ResourceManager<ResourceClient>T - The resource type.key - The key at which to get the resource.type - The expected resource type.options - The local resource options.public <T extends io.atomix.resource.Resource> CompletableFuture<T> getResource(String key, Class<? super T> type, io.atomix.resource.Resource.Config config, io.atomix.resource.Resource.Options options)
ResourceManagerIf a resource at the given key already exists, the resource will be validated to verify that its type matches the given type. If no resource yet exists, a new resource will be created in the cluster. Once the session for the resource has been opened, a resource instance will be returned.
The returned Resource instance will be a singleton reference to an global instance for this node.
That is, multiple calls to this method for the same resource will result in the same Resource
instance being returned.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
getResource in interface ResourceManager<ResourceClient>T - The resource type.key - The key at which to get the resource.type - The expected resource type.config - The cluster-wide resource configuration.options - The local resource options.public <T extends io.atomix.resource.Resource> CompletableFuture<T> getResource(String key, io.atomix.resource.ResourceType type)
ResourceManagerIf a resource at the given key already exists, the resource will be validated to verify that its type matches the given type. If no resource yet exists, a new resource will be created in the cluster. Once the session for the resource has been opened, a resource instance will be returned.
The returned Resource instance will be a singleton reference to an global instance for this node.
That is, multiple calls to this method for the same resource will result in the same Resource
instance being returned.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
getResource in interface ResourceManager<ResourceClient>T - The resource type.key - The key at which to get the resource.type - The expected resource type.public <T extends io.atomix.resource.Resource> CompletableFuture<T> getResource(String key, io.atomix.resource.ResourceType type, io.atomix.resource.Resource.Config config)
ResourceManagerIf a resource at the given key already exists, the resource will be validated to verify that its type matches the given type. If no resource yet exists, a new resource will be created in the cluster. Once the session for the resource has been opened, a resource instance will be returned.
The returned Resource instance will be a singleton reference to an global instance for this node.
That is, multiple calls to this method for the same resource will result in the same Resource
instance being returned.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
getResource in interface ResourceManager<ResourceClient>T - The resource type.key - The key at which to get the resource.type - The expected resource type.config - The cluster-wide resource configuration.public <T extends io.atomix.resource.Resource> CompletableFuture<T> getResource(String key, io.atomix.resource.ResourceType type, io.atomix.resource.Resource.Options options)
ResourceManagerIf a resource at the given key already exists, the resource will be validated to verify that its type matches the given type. If no resource yet exists, a new resource will be created in the cluster. Once the session for the resource has been opened, a resource instance will be returned.
The returned Resource instance will be a singleton reference to an global instance for this node.
That is, multiple calls to this method for the same resource will result in the same Resource
instance being returned.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
getResource in interface ResourceManager<ResourceClient>T - The resource type.key - The key at which to get the resource.type - The expected resource type.options - The local resource options.public <T extends io.atomix.resource.Resource> CompletableFuture<T> getResource(String key, io.atomix.resource.ResourceType type, io.atomix.resource.Resource.Config config, io.atomix.resource.Resource.Options options)
ResourceManagerIf a resource at the given key already exists, the resource will be validated to verify that its type matches the given type. If no resource yet exists, a new resource will be created in the cluster. Once the session for the resource has been opened, a resource instance will be returned.
The returned Resource instance will be a singleton reference to an global instance for this node.
That is, multiple calls to this method for the same resource will result in the same Resource
instance being returned.
This method returns a CompletableFuture which can be used to block until the operation completes
or to be notified in a separate thread once the operation completes. To block until the operation completes,
use the CompletableFuture.get() method:
DistributedLock lock = atomix.getResource("lock", DistributedLock.class).get();
Alternatively, to execute the operation asynchronous and be notified once the result is received in a different
thread, use one of the many completable future callbacks:
atomix.<DistributedLock>getResource("lock", DistributedLock.class).thenAccept(lock -> {
...
});
getResource in interface ResourceManager<ResourceClient>T - The resource type.key - The key at which to get the resource.type - The expected resource type.config - The cluster-wide resource configuration.options - The local resource options.public CopycatClient.State state()
public CompletableFuture<ResourceClient> connect()
public CompletableFuture<Void> close()
Copyright © 2013–2016. All rights reserved.