arangodb-java-driver

2.7: 3.0: 3.1:

master:

This library is a Java driver for ArangoDB.

Supported version: ArangoDB 3.0.X

(Use arangodb-java-driver 2.7.4 for ArangoDB 2.7.x and ArangoDB 2.8.x)

Required

• ArangoDB version 3.0.X
• Java 1.6 later

Basics

Maven

To add the driver to your project with maven, add the following code to your pom.xml (please use a driver with a version number compatible to your ArangoDB server's version):

ArangoDB 3.0.X

<dependencies>
  <dependency>
    <groupId>com.arangodb</groupId>
    <artifactId>arangodb-java-driver</artifactId>
    <version>3.0.3</version>
  </dependency>
	....
</dependencies>

ArangoDB 2.7.x and ArangoDB 2.8.x:

<dependencies>
  <dependency>
    <groupId>com.arangodb</groupId>
    <artifactId>arangodb-java-driver</artifactId>
    <version>2.7.4</version>
  </dependency>
	....
</dependencies>

If you want to test with a snapshot version (e.g. 3.0.0-SNAPSHOT), add the staging repository of oss.sonatype.org to your pom.xml:

<repositories>
  <repository>
    <id>arangodb-snapshots</id>
    <url>https://oss.sonatype.org/content/groups/staging</url>
  </repository>
</repositories>

Driver Setup

Setup with default configuration:

  // Initialize configure
  ArangoConfigure configure = new ArangoConfigure();
  configure.init();

  // Create Driver (this instance is thread-safe)
  ArangoDriver arangoDriver = new ArangoDriver(configure);
  

The driver is configured with some default values:

property-key	description	default value
host	ArangoDB host	127.0.0.1
port	ArangoDB port	8529
maxPerConnection	Max http connection per host.	20
maxTotalConnection	Max http connection per configure.	20
user	Basic Authentication User
password	Basic Authentication Password
proxy.host	proxy host
proxy.port	proxy port
connectionTimeout	socket connect timeout(millisecond)	-1
timeout	socket read timeout(millisecond)	-1
retryCount	http retry count	3
defaultDatabase	default database
enableCURLLogger	logging flag by curl format for debug	false
useSsl	use HTTPS connection	false
property-key	description	default value
arangoHost	ArangoDB host and port	127.0.0.1:8529
fallbackArangoHost	fallback ArangoDB host and port

To customize the configuration the parameters can be changed in the code...

  // Initialize configure
  ArangoConfigure configure = new ArangoConfigure();
  configure.setArangoHost(new ArangoHost("192.168.182.50", 8888));
  configure.init();

  // Create Driver (this instance is thread-safe)
  ArangoDriver arangoDriver = new ArangoDriver(configure);
  

... or with a properties file (arangodb.properties)

  // Initialize configure
  ArangoConfigure configure = new ArangoConfigure();
  configure.loadProperties();
  configure.init();

  // Create Driver (this instance is thread-safe)
  ArangoDriver arangoDriver = new ArangoDriver(configure);
  

Example for arangodb.properties:

arangoHost=192.168.182.50:8888
user=root
password=
enableCURLLogger=true

Basic database operations

create database

  // create database 
  arangoDriver.createDatabase("myDatabase");
  // and set as default
  arangoDriver.setDefaultDatabase("myDatabase");
  

changing the database

This ArangoDB driver is thread-safe. Unfortunately the ArangoDriver#setDefaultDatabase() is not (yet). So its recommended to create a new driver instance, if you want to change the database.

  //Driver instance to database "_system" (default database)
  ArangoDriver driverSystem = new ArangoDriver(configure);
  //Driver instance to database "mydb2"
  ArangoDriver driverMyDB = new ArangoDriver(configure, "mydb2");
  

drop database

  // drop database 
  arangoDriver.deleteDatabase("myDatabase");
  

Basic collection operations

create collection

  // create collection
  CollectionEntity myArangoCollection = ArangoCollectionarangoDriver.createCollection("myCollection");
  

delete collection by name

  // delete database 
  arangoDriver.deleteCollection("myCollection");
  

delete collection by id

  // delete database 
  arangoDriver.deleteCollection(myArangoCollection.getId());
  

Basic document operations

For the next examples we use a small object:

public class MyObject {

    private String name;
    private int age;

    public MyObject(String name, int age) {
        this.name = name;
        this.age = age;
    }
    
    /*
    *  + getter and setter
    */
   

}  

create document

  // create document 
  MyObject myObject = new MyObject("Homer", 38);
  DocumentEntity<MyObject> myDocument = arangoDriver.createDocument("myCollection", myObject);
  

When creating a document, the attributes of the object will be stored as key-value pair E.g. in the previous example the object was stored as follows:

"name" : "Homer"
"age" : "38"

delete document

  // delete document 
  arangoDriver.deleteDocument(myDocument.getDocumentHandle());
  

AQL

Executing an AQL statement

E.g. get all Simpsons aged 3 or older in ascending order:

    arangoDriver.deleteDatabase("myDatabase");
    arangoDriver.createDatabase("myDatabase");
    arangoDriver.setDefaultDatabase("myDatabase");
    CollectionEntity myArangoCollection = arangoDriver.createCollection("myCollection");
    
    arangoDriver.createDocument("myCollection", new MyObject("Homer", 38));
    arangoDriver.createDocument("myCollection", new MyObject("Marge", 36));
    arangoDriver.createDocument("myCollection", new MyObject("Bart", 10));
    arangoDriver.createDocument("myCollection", new MyObject("Lisa", 8));
    arangoDriver.createDocument("myCollection", new MyObject("Maggie", 2));
    
    String query = "FOR t IN myCollection FILTER t.age >= @age SORT t.age RETURN t";
    Map<String, Object> bindVars = new MapBuilder().put("age", 3).get();
    
    DocumentCursor<MyObject> documentCursor = arangoDriver.executeDocumentQuery(
      query, bindVars, driver.getDefaultAqlQueryOptions(), MyObject.class);
    
    for (DocumentEntity<MyObject> documentEntity : documentCursor.asList()) {
      MyObject obj = documentEntity.getEntity();
      System.out.println(obj.getName());
    }

instead of using a for statement you can also use an DocumentEntitiy or an entity iterator:

    Iterator<DocumentEntity<Person>> iterator = documentCursor.iterator();
    while (iterator.hasNext()) {
      DocumentEntity<MyObject> documentEntity = iterator.next();
      MyObject obj = documentEntity.getEntity();
      System.out.println(obj.getName());
    }

    Iterator<Person> iterator = documentCursor.entityIterator();
    while (iterator.hasNext()) {
      MyObject obj = iterator.next();
      System.out.println(obj.getName());
    }

#User Management If you are using [authentication] (https://docs.arangodb.com/Manual/GettingStarted/Authentication.html) you can manage users with the driver.

##add user

  //username, password, active, extras
  arangoDriver.createUser("myUser", "myPassword", true, null);

##list users

  List<UserEntity> users = arangoDriver.getUsers();
  for(UserEntity user : users) {
    System.out.println(user.getName())
  }

##DELETE user

  arangoDriver.deleteUser("myUser");

#Graphs This driver supports the new graph api.

Some of the basic graph operations are described in the following:

##add graph A graph consists of vertices and edges (stored in collections). Which collections are used within a graph is defined via edge definitions. A graph can contain more than one edge definition, at least one is needed.

  List<EdgeDefinitionEntity> edgeDefinitions = new ArrayList<EdgeDefinitionEntity>();
  EdgeDefinitionEntity edgeDefinition = new EdgeDefinitionEntity();
  // define the edgeCollection to store the edges
  edgeDefinition.setCollection("myEdgeCollection");
  // define a set of collections where an edge is going out...
  List<String> from = new ArrayList<String>();
  // and add one or more collections
  from.add("myCollection1");
  from.add("myCollection2");
  edgeDefinition.setFrom(from);
   
  // repeat this for the collections where an edge is going into  
  List<String> to = new ArrayList<String>();
  to.add("myCollection1");
  to.add("myCollection3");
  edgeDefinition.setTo(to);
  
  edgeDefinitions.add(edgeDefinition);
  
  // A graph can contain additional vertex collections, defined in the set of orphan collections
  List<String> orphanCollections = new ArrayList<String>(); 
  orphanCollections.add("myCollection4");
  orphanCollections.add("myCollection5");
  
  // now it's possible to create a graph (the last parameter is the waitForSync option)
  GraphEntity graph = arangoDriver.createGraph("myGraph", edgeDefinitions, orphanCollections, true);

##delete graph

A graph can be deleted by its name

  arangoDriver.deleteGraph("myGraph");

##add vertex

Vertices are stored in the vertex collections defined above.

  MyObject myObject1 = new MyObject("Homer", 38);
  MyObject myObject2 = new MyObject("Marge", 36);
  DocumentEntity<MyObject> vertexFrom = arangoDriver.graphCreateVertex(
      "myGraph",
      "collection1",
      myObject1,
      true); 
  
  DocumentEntity<MyObject> vertexTo = arangoDriver.graphCreateVertex(
      "myGraph",
      "collection3",
      myObject2,
      true); 

add edge

Now an edge can be created to set a relation between vertices

    EdgeEntity<?> edge = arangoDriver.graphCreateEdge(
      "myGraph",
      "myEdgeCollection",
      null,
      vertexFrom.getDocumentHandle(),
      vertexTo.getDocumentHandle(),
      null,
      null);

Compile java driver

	mvn clean install -DskipTests=true -Dgpg.skip=true -Dmaven.javadoc.skip=true -B

Learn more

• ArangoDB
• ChangeLog
• Examples
• Document examples
• Graph examples
• HTTPS examples
• Tutorial