com.arangodb.ArangoDB 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;
import com.arangodb.entity.*;
import com.arangodb.internal.ArangoDBImpl;
import com.arangodb.internal.InternalArangoDBBuilder;
import com.arangodb.internal.net.*;
import com.arangodb.model.*;
import javax.annotation.concurrent.ThreadSafe;
import java.util.Collection;
/**
* Central access point for applications to communicate with an ArangoDB server.
*
*
* Will be instantiated through {@link ArangoDB.Builder}
*
*
*
* ArangoDB arango = new ArangoDB.Builder().build();
* ArangoDB arango = new ArangoDB.Builder().host("127.0.0.1", 8529).build();
*
*
* @author Mark Vollmary
* @author Michele Rastelli
*/
@ThreadSafe
public interface ArangoDB extends ArangoSerdeAccessor {
/**
* Releases all connections to the server and clear the connection pool.
*/
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 {@code ArangoDatabase} instance for the {@code _system} database.
*
* @return database handler
*/
ArangoDatabase db();
/**
* Returns a {@code ArangoDatabase} instance for the given database name.
*
* @param name Name of the database
* @return database handler
*/
ArangoDatabase db(String name);
/**
* @return entry point for accessing client metrics
*/
ArangoMetrics metrics();
/**
* Creates a new database with the given name.
*
* @param name Name of the database to create
* @return true if the database was created successfully.
* @see API
* Documentation
*/
Boolean createDatabase(String name);
/**
* Creates a new database with the given name.
*
* @param options Creation options
* @return true if the database was created successfully.
* @see API
* Documentation
* @since ArangoDB 3.6.0
*/
Boolean createDatabase(DBCreateOptions options);
/**
* Retrieves a list of all existing databases
*
* @return a list of all existing databases
* @see API
* Documentation
*/
Collection 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
*/
Collection getAccessibleDatabases();
/**
* List available database to the specified user
*
* @param user The name of the user for which you want to query the databases
* @return list of database names which are available for the specified user
* @see API
* Documentation
*/
Collection getAccessibleDatabasesFor(String user);
/**
* Returns the server name and version number.
*
* @return the server version, number
* @see API
* Documentation
*/
ArangoDBVersion getVersion();
/**
* Returns the server storage engine.
*
* @return the storage engine name
* @see API
* Documentation
*/
ArangoDBEngine getEngine();
/**
* Returns the server role.
*
* @return the server role
*/
ServerRole getRole();
/**
* Returns the id of a server in a cluster.
*
* @return the server id
* @see API
* Documentation
*/
String getServerId();
/**
* 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
*/
UserEntity createUser(String user, 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 options, can be null
* @return information about the user
* @see API Documentation
*/
UserEntity createUser(String user, String passwd, UserCreateOptions options);
/**
* Removes an existing user, identified by user. You need access to the _system database.
*
* @param user The name of the user
* @see API Documentation
*/
void deleteUser(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
*/
UserEntity getUser(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
*/
Collection 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
*/
UserEntity updateUser(String user, 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
*/
UserEntity replaceUser(String user, UserUpdateOptions options);
/**
* Sets the default access level for databases for the user {@code 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
* @since ArangoDB 3.2.0
*/
void grantDefaultDatabaseAccess(String user, Permissions permissions);
/**
* Sets the default access level for collections for the user {@code 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
* @since ArangoDB 3.2.0
*/
void grantDefaultCollectionAccess(String user, 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
*/
Response execute(Request request, Class type);
/**
* Returns the server logs
*
* @param options Additional options, can be null
* @return the log messages
* @see API
* Documentation
* @since ArangoDB 3.8
*/
LogEntriesEntity getLogEntries(LogOptions options);
/**
* Returns the server's current loglevel settings.
*
* @return the server's current loglevel settings
* @since ArangoDB 3.1.0
*/
LogLevelEntity getLogLevel();
/**
* Returns the server's current loglevel settings.
*
* @return the server's current loglevel settings
* @since ArangoDB 3.10
*/
LogLevelEntity getLogLevel(LogLevelOptions options);
/**
* Modifies and returns the server's current loglevel settings.
*
* @param entity loglevel settings
* @return the server's current loglevel settings
* @since ArangoDB 3.1.0
*/
LogLevelEntity setLogLevel(LogLevelEntity entity);
/**
* Modifies and returns the server's current loglevel settings.
*
* @param entity loglevel settings
* @return the server's current loglevel settings
* @since ArangoDB 3.10
*/
LogLevelEntity setLogLevel(LogLevelEntity entity, LogLevelOptions options);
/**
* @return the list of available rules and their respective flags
* @since ArangoDB 3.10
*/
Collection getQueryOptimizerRules();
/**
* Builder class to build an instance of {@link ArangoDB}.
*
* @author Mark Vollmary
*/
class Builder extends InternalArangoDBBuilder {
public Builder protocol(final Protocol protocol) {
config.setProtocol(protocol);
return this;
}
/**
* Returns an instance of {@link ArangoDB}.
*
* @return {@link ArangoDB}
*/
public ArangoDB build() {
if (config.getHosts().isEmpty()) {
throw new ArangoDBException("No host has been set!");
}
ProtocolProvider protocolProvider = protocolProvider(config.getProtocol());
config.setProtocolModule(protocolProvider.protocolModule());
ConnectionFactory connectionFactory = protocolProvider.createConnectionFactory();
Collection hostList = createHostList(connectionFactory);
HostResolver hostResolver = createHostResolver(hostList, connectionFactory);
HostHandler hostHandler = createHostHandler(hostResolver);
hostHandler.setJwt(config.getJwt());
return new ArangoDBImpl(
config,
hostResolver,
protocolProvider,
hostHandler
);
}
}
}