Driver setup
How to connect your Java application to an ArangoDB server, as well as important configuration settings and information about the driver
The driver can be configured and instantiated using com.arangodb.ArangoDB.Builder
:
ArangoDB arangoDB = new ArangoDB.Builder()
// ...
.build();
To customize the configuration properties can be set programmatically in the builder:
ArangoDB arangoDB = new ArangoDB.Builder()
.host("127.0.0.1",8529)
// ...
.build();
or providing an implementation of com.arangodb.config.ArangoConfigProperties
to the builder:
ArangoConfigProperties props = ...
ArangoDB arangoDB = new ArangoDB.Builder()
.loadProperties(props)
// ...
.build();
Implementations of com.arangodb.config.ArangoConfigProperties
could supply
configuration properties coming from different sources, eg. system properties,
remote stores, frameworks integrations, etc.
An implementation for loading properties from local files is provided by
ArangoConfigProperties.fromFile()
and its overloaded variants.
To read config properties prefixed with arangodb
from arangodb.properties
file (as in version 6
):
// ## src/main/resources/arangodb.properties
// arangodb.hosts=172.28.0.1:8529
// arangodb.password=test
// ...
ArangoConfigProperties props = ArangoConfigProperties.fromFile();
To read config properties from arangodb-with-prefix.properties
file, where the
config properties are prefixed with adb
:
// ## src/main/resources/arangodb-with-prefix.properties
// adb.hosts=172.28.0.1:8529
// adb.password=test
// ...
ArangoConfigProperties props = ArangoConfigProperties.fromFile("arangodb-with-prefix.properties", "adb");
Here are examples to integrate configuration properties from different sources:
Configuration
ArangoDB.Builder
has the following configuration methods:
host(String, int)
: adds a host (hostname and port) to connect to, multiple hosts can be addedprotocol(Protocol)
: communication protocol, possible values are:VST
,HTTP_JSON
,HTTP_VPACK
,HTTP2_JSON
,HTTP2_VPACK
, (default:HTTP2_JSON
)timeout(Integer)
: connection and request timeout (ms), (default0
, no timeout)user(String)
: username for authentication, (default:root
)password(String)
: password for authenticationjwt(String)
: JWT for authenticationuseSsl(Boolean)
: use SSL connection, (default:false
)sslContext(SSLContext)
: SSL contextverifyHost(Boolean)
: enable hostname verification, (HTTP only, default:true
)chunkSize(Integer)
: VST chunk size in bytes, (default:30000
)maxConnections(Integer)
: max number of connections per host, (default: 1 VST, 1 HTTP/2, 20 HTTP/1.1)connectionTtl(Long)
: time to live of an inactive connection (ms), (default:30_000
for HTTP, no TTL for VST)keepAliveInterval(Integer)
: VST keep-alive interval (s), (default: no keep-alive probes will be sent)acquireHostList(Boolean)
: acquire the list of available hosts, (default:false
)acquireHostListInterval(Integer)
: acquireHostList interval (ms), (default:3_600_000
, 1 hour)loadBalancingStrategy(LoadBalancingStrategy)
: load balancing strategy, possible values are:NONE
,ROUND_ROBIN
,ONE_RANDOM
, (default:NONE
)responseQueueTimeSamples(Integer)
: amount of samples kept for queue time metrics, (default:10
)serde(ArangoSerde)
: serde to serialize and deserialize user-dataserdeProviderClass(Class<? extends ArangoSerdeProvider>)
: serde provider to be used to instantiate the user-data serdeprotocolConfig(ProtocolConfig)
: configuration specific for the used protocol provider implementation
HTTP Protocol Provider Configuration
The ProtocolConfig
for the default HTTP protocol provider can be created via:
HttpProtocolConfig.builder()
// ...
.build();
and configured using the following builder methods:
vertx(Vertx)
: Vert.x instance to use. If not set, a new instance is created.
For example, to reuse the existing Vert.x instance:
HttpProtocolConfig.builder()
.protocolConfig(HttpProtocolConfig.builder()
.vertx(Vertx.currentContext().owner())
.build()
)
.build();
Config File Properties
ArangoConfigProperties.fromFile()
reads config properties prefixed with arangodb
from arangodb.properties
file (as in version 6
). Different prefix and
file name can be specified using its overloaded variants.
The properties read are:
hosts
: comma-separated list of<hostname>:<port>
entriesprotocol
:VST
,HTTP_JSON
,HTTP_VPACK
,HTTP2_JSON
orHTTP2_VPACK
timeout
user
password
jwt
useSsl
verifyHost
chunkSize
maxConnections
connectionTtl
keepAliveInterval
acquireHostList
acquireHostListInterval
loadBalancingStrategy
:NONE
,ROUND_ROBIN
orONE_RANDOM
responseQueueTimeSamples
serdeProviderClass
: fully qualified name of the provider class
SSL
To use SSL, you have to set the configuration useSsl
to true
and set a SSLContext
(see example code ).
ArangoDB arangoDB = new ArangoDB.Builder()
.useSsl(true)
.sslContext(sc)
.build();
Connection Pooling
The driver keeps a pool of connections for each host, the max amount of connections is configurable.
Inactive connections are released after the configured connection time-to-live
(ArangoDB.Builder.connectionTtl(Long)
) or when the driver is shut down:
arangoDB.shutdown();
Thread Safety
The driver can be used concurrently by multiple threads. All the following classes are thread safe:
com.arangodb.ArangoDB
com.arangodb.ArangoDatabase
com.arangodb.ArangoCollection
com.arangodb.ArangoGraph
com.arangodb.ArangoVertexCollection
com.arangodb.ArangoEdgeCollection
com.arangodb.ArangoView
com.arangodb.ArangoSearch
Any other class should not be considered thread safe. In particular classes
representing request options (package com.arangodb.model
) and response entities
(package com.arangodb.entity
) are not thread safe.
Fallback hosts
The driver supports configuring multiple hosts. The first host is used to open a
connection to. When this host is not reachable the next host from the list is used.
To use this feature just call the method host(String, int)
multiple times.
ArangoDB arangoDB = new ArangoDB.Builder()
.host("host1", 8529)
.host("host2", 8529)
.build();
The driver is also able to acquire a list of known hosts in a cluster. For this the driver has to be able to successfully open a connection to at least one host to get the list of hosts. Then it can use this list when fallback is needed. To enable this feature:
ArangoDB arangoDB = new ArangoDB.Builder()
.acquireHostList(true)
.build();
Load Balancing
The driver supports load balancing for cluster setups in two different ways.
The first one is a round robin load balancing where the driver iterates through a list of known hosts and performs every request on a different host than the request before.
ArangoDB arangoDB = new ArangoDB.Builder()
.loadBalancingStrategy(LoadBalancingStrategy.ROUND_ROBIN)
.build();
The second load balancing strategy picks a random host from host list (configured or acquired) and sticks to it as long as the connection is open.
ArangoDB arangoDB = new ArangoDB.Builder()
.loadBalancingStrategy(LoadBalancingStrategy.ONE_RANDOM)
.build();
Active Failover
In case of an Active Failover deployment the driver should be configured in the following way:
- the load balancing strategy must be either set to
LoadBalancingStrategy.NONE
(default) acquireHostList
should be set totrue
ArangoDB arangoDB = new ArangoDB.Builder()
.loadBalancingStrategy(LoadBalancingStrategy.NONE)
.acquireHostList(true)
.build();
Connection time to live
The driver supports setting a TTL (time to live) for connections:
ArangoDB arango = new ArangoDB.Builder()
.connectionTtl(5 * 60 * 1000) // ms
.build();
In this example, inactive connections are closed after 5 minutes.
The default TTL for HTTP connections is 30 seconds, while it is null
for VST connections.
If set to null
, no automatic connection closure is performed.
VST Keep-Alive
The driver supports setting keep-alive interval (in seconds) for VST connections. If set, every VST connection performs a no-op request at the specified intervals, to avoid to be closed due to inactivity by the server (or by the external environment, e.g. firewall, intermediate routers, operating system, … ).
ArangoDB arangoDB = new ArangoDB.Builder()
.keepAliveInterval(1_800) // 30 minutes
.build();
If not set or set to null
(default), no keep-alive probes will be sent.