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:

// ## 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 added
  • protocol(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), (default 0, no timeout)
  • user(String): username for authentication, (default: root)
  • password(String): password for authentication
  • jwt(String): JWT for authentication
  • useSsl(Boolean): use SSL connection, (default: false)
  • sslContext(SSLContext): SSL context
  • verifyHost(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-data
  • serdeProviderClass(Class<? extends ArangoSerdeProvider>): serde provider to be used to instantiate the user-data serde
  • protocolConfig(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. Different prefix and file name can be specified using its overloaded variants.

The properties read are:

  • hosts: comma-separated list of <hostname>:<port> entries
  • protocol: VST, HTTP_JSON, HTTP_VPACK, HTTP2_JSON or HTTP2_VPACK
  • timeout
  • user
  • password
  • jwt
  • useSsl
  • verifyHost
  • chunkSize
  • maxConnections
  • connectionTtl
  • keepAliveInterval
  • acquireHostList
  • acquireHostListInterval
  • loadBalancingStrategy: NONE, ROUND_ROBIN or ONE_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 to true
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.

Proxy configuration

The driver allows configuring the underlying Vert.x WebClient to work with HTTP proxies. The configuration is specific to the HTTP protocol and uses the io.vertx.core.net.ProxyOptions class of Vert.x Core :

ArangoDB arango = new ArangoDB.Builder()
    // ...
    .protocolConfig(HttpProtocolConfig.builder()
        .proxyOptions(new ProxyOptions()
            .setType(ProxyType.HTTP)
            .setHost("172.28.0.1")
            .setPort(8888)
            .setUsername("user")
            .setPassword("password"))
        .build())
    .build();

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.

On this page