com.arangodb.async.ArangoDBAsync Maven / Gradle / Ivy
/*
* DISCLAIMER
*
* Copyright 2016 ArangoDB GmbH, Cologne, Germany
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Copyright holder is ArangoDB GmbH, Cologne, Germany
*/
package com.arangodb.async;
import com.arangodb.*;
import com.arangodb.async.internal.ArangoDBAsyncImpl;
import com.arangodb.async.internal.velocystream.VstCommunicationAsync;
import com.arangodb.async.internal.velocystream.VstConnectionFactoryAsync;
import com.arangodb.config.ArangoConfigProperties;
import com.arangodb.entity.*;
import com.arangodb.internal.ArangoDefaults;
import com.arangodb.internal.InternalArangoDBBuilder;
import com.arangodb.internal.net.ConnectionFactory;
import com.arangodb.internal.net.HostHandler;
import com.arangodb.internal.net.HostResolver;
import com.arangodb.internal.serde.InternalSerde;
import com.arangodb.internal.serde.InternalSerdeProvider;
import com.arangodb.internal.velocystream.VstCommunicationSync;
import com.arangodb.internal.velocystream.VstConnectionFactorySync;
import com.arangodb.model.DBCreateOptions;
import com.arangodb.model.LogOptions;
import com.arangodb.model.UserCreateOptions;
import com.arangodb.model.UserUpdateOptions;
import com.arangodb.serde.ArangoSerde;
import javax.annotation.concurrent.ThreadSafe;
import javax.net.ssl.SSLContext;
import java.util.Collection;
import java.util.concurrent.CompletableFuture;
/**
* Central access point for applications to communicate with an ArangoDB server.
*
*
* Will be instantiated through {@link ArangoDBAsync.Builder}
*
*
*
* ArangoDBAsync arango = new ArangoDBAsync.Builder().build();
* ArangoDBAsync arango = new ArangoDBAsync.Builder().host("127.0.0.1", 8529).build();
*
*
* @author Mark Vollmary
*/
@ThreadSafe
public interface ArangoDBAsync extends ArangoSerdeAccessor {
void shutdown();
/**
* Updates the JWT used for requests authorization. It does not change already existing VST connections, since VST
* connections are authenticated during the initialization phase.
*
* @param jwt token to use
*/
void updateJwt(String jwt);
/**
* Returns a handler of the system database
*
* @return database handler
*/
ArangoDatabaseAsync db();
/**
* Returns a handler of the database by the given name
*
* @param dbName Name of the database
* @return database handler
*/
ArangoDatabaseAsync db(final DbName dbName);
/**
* @return entry point for accessing client metrics
*/
ArangoMetrics metrics();
/**
* Creates a new database
*
* @param dbName database name
* @return true if the database was created successfully.
* @see API
* Documentation
*/
CompletableFuture createDatabase(final DbName dbName);
/**
* Creates a new database
*
* @param options Creation options
* @return true if the database was created successfully.
* @see API
* Documentation
* @since ArangoDB 3.6.0
*/
CompletableFuture createDatabase(final DBCreateOptions options);
/**
* Retrieves a list of all existing databases
*
* @return a list of all existing databases
* @see API
* Documentation
*/
CompletableFuture> getDatabases();
/**
* Retrieves a list of all databases the current user can access
*
* @return a list of all databases the current user can access
* @see API
* Documentation
*/
CompletableFuture> getAccessibleDatabases();
/**
* List available database to the specified user
*
* @param user The name of the user for which you want to query the databases
* @return
* @see API
* Documentation
*/
CompletableFuture> getAccessibleDatabasesFor(final String user);
/**
* Returns the server name and version number.
*
* @return the server version, number
* @see API
* Documentation
*/
CompletableFuture getVersion();
/**
* Returns the server role.
*
* @return the server role
*/
CompletableFuture getRole();
/**
* Create a new user. This user will not have access to any database. You need permission to the _system database in
* order to execute this call.
*
* @param user The name of the user
* @param passwd The user password
* @return information about the user
* @see API Documentation
*/
CompletableFuture createUser(final String user, final String passwd);
/**
* Create a new user. This user will not have access to any database. You need permission to the _system database in
* order to execute this call.
*
* @param user The name of the user
* @param passwd The user password
* @param options Additional properties of the user, can be null
* @return information about the user
* @see API Documentation
*/
CompletableFuture createUser(final String user, final String passwd, final UserCreateOptions options);
/**
* Removes an existing user, identified by user. You need access to the _system database.
*
* @param user The name of the user
* @return void
* @see API Documentation
*/
CompletableFuture deleteUser(final String user);
/**
* Fetches data about the specified user. You can fetch information about yourself or you need permission to the
* _system database in order to execute this call.
*
* @param user The name of the user
* @return information about the user
* @see API Documentation
*/
CompletableFuture getUser(final String user);
/**
* Fetches data about all users. You can only execute this call if you have access to the _system database.
*
* @return informations about all users
* @see API
* Documentation
*/
CompletableFuture> getUsers();
/**
* Partially updates the data of an existing user. The name of an existing user must be specified in user. You can
* only change the password of your self. You need access to the _system database to change the active flag.
*
* @param user The name of the user
* @param options Properties of the user to be changed
* @return information about the user
* @see API Documentation
*/
CompletableFuture updateUser(final String user, final UserUpdateOptions options);
/**
* Replaces the data of an existing user. The name of an existing user must be specified in user. You can only
* change the password of your self. You need access to the _system database to change the active flag.
*
* @param user The name of the user
* @param options Additional properties of the user, can be null
* @return information about the user
* @see API
* Documentation
*/
CompletableFuture replaceUser(final String user, final UserUpdateOptions options);
/**
* Sets the default access level for databases for the user user. You need permission to the _system
* database in order to execute this call.
*
* @param user The name of the user
* @param permissions The permissions the user grant
* @return void
* @since ArangoDB 3.2.0
*/
CompletableFuture grantDefaultDatabaseAccess(final String user, final Permissions permissions);
/**
* Sets the default access level for collections for the user user. You need permission to the _system
* database in order to execute this call.
*
* @param user The name of the user
* @param permissions The permissions the user grant
* @return void
* @since ArangoDB 3.2.0
*/
CompletableFuture grantDefaultCollectionAccess(final String user, final Permissions permissions);
/**
* Execute custom requests. Requests can be programmatically built by setting low level detail such as method, path,
* query parameters, headers and body payload.
* This method can be used to call FOXX services, API endpoints not (yet) implemented in this driver or trigger
* async jobs, see
* Fire and Forget
* and
* Async Execution and later Result Retrieval
*
* @param request request
* @param type Deserialization target type for the response body (POJO or {@link com.arangodb.util.RawData})
* @return response
*/
CompletableFuture> execute(final Request request, final Class type);
/**
* Returns the server logs
*
* @param options Additional options, can be null
* @return the log messages
* @see
* API
* Documentation
* @since ArangoDB 3.8
*/
CompletableFuture getLogEntries(final LogOptions options);
/**
* Returns the server's current loglevel settings.
*
* @return the server's current loglevel settings
*/
CompletableFuture getLogLevel();
/**
* Modifies and returns the server's current loglevel settings.
*
* @param entity loglevel settings
* @return the server's current loglevel settings
*/
CompletableFuture setLogLevel(final LogLevelEntity entity);
/**
* @return the list of available rules and their respective flags
* @since ArangoDB 3.10
*/
CompletableFuture> getQueryOptimizerRules();
/**
* Builder class to build an instance of {@link ArangoDBAsync}.
*
* @author Mark Vollmary
*/
class Builder extends InternalArangoDBBuilder {
public Builder() {
super();
}
public Builder loadProperties(final ArangoConfigProperties config) {
super.doLoadProperties(config);
return this;
}
/**
* Adds a host to connect to. Multiple hosts can be added to provide fallbacks.
*
* @param host address of the host
* @param port port of the host
* @return {@link ArangoDBAsync.Builder}
*/
public Builder host(final String host, final int port) {
setHost(host, port);
return this;
}
/**
* Sets the timeout in milliseconds. It is used as socket timeout when opening a VecloyStream.
*
* @param timeout timeout in milliseconds
* @return {@link ArangoDBAsync.Builder}
*/
public Builder timeout(final Integer timeout) {
setTimeout(timeout);
return this;
}
/**
* Sets the username to use for authentication.
*
* @param user the user in the database (default: root)
* @return {@link ArangoDBAsync.Builder}
*/
public Builder user(final String user) {
setUser(user);
return this;
}
/**
* Sets the password for the user for authentication.
*
* @param password the password of the user in the database (default: null)
* @return {@link ArangoDBAsync.Builder}
*/
public Builder password(final String password) {
setPassword(password);
return this;
}
/**
* Sets the JWT for the user authentication.
*
* @param jwt token to use (default: {@code null})
* @return {@link ArangoDBAsync.Builder}
*/
public Builder jwt(final String jwt) {
setJwt(jwt);
return this;
}
/**
* If set to true SSL will be used when connecting to an ArangoDB server.
*
* @param useSsl whether or not use SSL (default: false)
* @return {@link ArangoDBAsync.Builder}
*/
public Builder useSsl(final Boolean useSsl) {
setUseSsl(useSsl);
return this;
}
/**
* Sets the SSL context to be used when true is passed through {@link #useSsl(Boolean)}.
*
* @param sslContext SSL context to be used
* @return {@link ArangoDBAsync.Builder}
*/
public Builder sslContext(final SSLContext sslContext) {
setSslContext(sslContext);
return this;
}
/**
* Sets the chunk size when {@link Protocol#VST} is used.
*
* @param chunksize size of a chunk in bytes
* @return {@link ArangoDBAsync.Builder}
*/
public Builder chunksize(final Integer chunksize) {
setChunkSize(chunksize);
return this;
}
/**
* Sets the maximum number of connections the built in connection pool will open.
*
*
* In an ArangoDB cluster setup with {@link LoadBalancingStrategy#ROUND_ROBIN} set, this value should be at
* least as high as the number of ArangoDB coordinators in the cluster.
*
*
* @param maxConnections max number of connections (default: 1)
* @return {@link ArangoDBAsync.Builder}
*/
public Builder maxConnections(final Integer maxConnections) {
setMaxConnections(maxConnections);
return this;
}
/**
* Set the maximum time to life of a connection. After this time the connection will be closed automatically.
*
* @param connectionTtl the maximum time to life of a connection.
* @return {@link ArangoDBAsync.Builder}
*/
public Builder connectionTtl(final Long connectionTtl) {
setConnectionTtl(connectionTtl);
return this;
}
/**
* Set the keep-alive interval for VST connections. If set, every VST connection will perform a no-op request
* every
* {@code keepAliveInterval} seconds, to avoid to be closed due to inactivity by the server (or by the external
* environment, eg. firewall, intermediate routers, operating system).
*
* @param keepAliveInterval interval in seconds
* @return {@link ArangoDBAsync.Builder}
*/
public Builder keepAliveInterval(final Integer keepAliveInterval) {
setKeepAliveInterval(keepAliveInterval);
return this;
}
/**
* Whether or not the driver should acquire a list of available coordinators in an ArangoDB cluster or a single
* server with active failover.
* In case of Active-Failover deployment set to {@code true} to enable automatic master discovery.
*
*
* The host list will be used for failover and load balancing.
*
*
* @param acquireHostList whether or not automatically acquire a list of available hosts (default: false)
* @return {@link ArangoDBAsync.Builder}
*/
public Builder acquireHostList(final Boolean acquireHostList) {
setAcquireHostList(acquireHostList);
return this;
}
/**
* Setting the amount of samples kept for queue time metrics
*
* @param responseQueueTimeSamples amount of samples to keep
* @return {@link ArangoDBAsync.Builder}
*/
public Builder responseQueueTimeSamples(final Integer responseQueueTimeSamples) {
setResponseQueueTimeSamples(responseQueueTimeSamples);
return this;
}
/**
* Sets the load balancing strategy to be used in an ArangoDB cluster setup.
* In case of Active-Failover deployment set to {@link LoadBalancingStrategy#NONE} or not set at all, since that
* would be the default.
*
* @param loadBalancingStrategy the load balancing strategy to be used (default:
* {@link LoadBalancingStrategy#NONE}
* @return {@link ArangoDBAsync.Builder}
*/
public Builder loadBalancingStrategy(final LoadBalancingStrategy loadBalancingStrategy) {
setLoadBalancingStrategy(loadBalancingStrategy);
return this;
}
/**
* Replace the built-in serializer/deserializer with the given one.
*
*
* ATTENTION!: Any registered custom serializer/deserializer or module will be ignored.
*
* @param serialization custom serializer/deserializer
* @return {@link ArangoDBAsync.Builder}
*/
public Builder serializer(final ArangoSerde serialization) {
setUserDataSerde(serialization);
return this;
}
/**
* Returns an instance of {@link ArangoDBAsync}.
*
* @return {@link ArangoDBAsync}
*/
public ArangoDBAsync build() {
if (hosts.isEmpty()) {
throw new ArangoDBException("No host has been set!");
}
final ArangoSerde userSerde = this.userDataSerde != null ? this.userDataSerde : serdeProvider().of(ContentType.VPACK);
final InternalSerde serde = InternalSerdeProvider.create(ContentType.VPACK, userSerde);
final int max = maxConnections != null ? Math.max(1, maxConnections)
: ArangoDefaults.MAX_CONNECTIONS_VST_DEFAULT;
final ConnectionFactory syncConnectionFactory = new VstConnectionFactorySync(timeout, connectionTtl,
keepAliveInterval, useSsl, sslContext);
final ConnectionFactory asyncConnectionFactory = new VstConnectionFactoryAsync(timeout, connectionTtl,
keepAliveInterval, useSsl, sslContext);
final HostResolver syncHostResolver = createHostResolver(createHostList(max, syncConnectionFactory), max,
syncConnectionFactory);
final HostResolver asyncHostResolver = createHostResolver(createHostList(max, asyncConnectionFactory), max,
asyncConnectionFactory);
final HostHandler syncHostHandler = createHostHandler(syncHostResolver);
final HostHandler asyncHostHandler = createHostHandler(asyncHostResolver);
return new ArangoDBAsyncImpl(
asyncBuilder(asyncHostHandler),
serde,
syncBuilder(syncHostHandler),
asyncHostResolver,
syncHostResolver,
asyncHostHandler,
syncHostHandler,
responseQueueTimeSamples,
timeout);
}
private VstCommunicationAsync.Builder asyncBuilder(final HostHandler hostHandler) {
return new VstCommunicationAsync.Builder(hostHandler).timeout(timeout).user(user).password(password)
.jwt(jwt).useSsl(useSsl).sslContext(sslContext).chunksize(chunkSize).maxConnections(maxConnections)
.connectionTtl(connectionTtl);
}
private VstCommunicationSync.Builder syncBuilder(final HostHandler hostHandler) {
return new VstCommunicationSync.Builder(hostHandler).timeout(timeout).user(user).password(password)
.jwt(jwt).useSsl(useSsl).sslContext(sslContext).chunksize(chunkSize).maxConnections(maxConnections)
.connectionTtl(connectionTtl);
}
}
}