arangodb-java-driver

This library is a Java driver for ArangoDB.

Supported version: ArangoDB-2.4.x, ArangoDB 2.5.x and ArangoDB 2.6.x

Required

• ArangoDB version 2.4.x, 2.5.x or 2.6.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):

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

If you want to test with a snapshot version (e.g. 2.5.8-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

Since 2.5.4 you can configure a default and a fallback database:

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);
    
    while (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] (http://docs.arangodb.com/ConfigureArango/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.createUser("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);

What's new in 2.4 / 2.5

since 2.4.1

httpclient version 4.3.6

since 2.4.2

Fixed issue#2

since 2.4.3

• Fixed a graph bug: when retrieving a graph via the driver, "from" and "to" were emtpy. This is fixed now.
• GraphEntity has been changed, so that edge definitions are stored in an EdgeDefinitionsEntity.
• Some additional methods in GraphEntity:
  • public EdgeDefinitionsEntity getEdgeDefinitionsEntity()
  • public void setEdgeDefinitionsEntity(EdgeDefinitionsEntity edgeDefinitionsEntity)
• Some additional methods in EdgeDefinitionsEntity:
  • public int getSize()
  • public EdgeDefinitionEntity getEdgeDefinition(String collectionName)

since 2.4.4

• fixed issue #5
  • added method to driver.createGraph(GraphEntity g);
• fixed issue #6
• fixed issue #7

since 2.5.0

Added support for sparse indexes

since 2.5.1

see 2.4.4

since 2.5.3

• fixed issue #9
  • added method to driver.getTraversal(...);

since 2.5.4

• fixed issue #12
  • added auto reconnection when connection breaks
  • added fallback server endpoints
• added new cursor implementation for AQL queries
  • DocumentCursor executeDocumentQuery(...)
  • VertexCursor executeVertexQuery(...)
  • EdgeCursor executeEdgeQuery(...)
• added new cursor implementation for simple queries
  • DocumentCursor executeSimpleAllDocuments(...)
  • DocumentCursor executeSimpleByExampleDocuments(...)
  • DocumentCursor executeSimpleRangeWithDocuments(...)
  • DocumentCursor executeSimpleFulltextWithDocuments(...)
• added some examples for AQL queries (see src/test/java/com/arangodb/example)

since 2.5.5

• updated driver.getTraversal(...);
  • removed VisitedEntity (Traversal)
  • added TraversalQueryOptions to avoid too many parameters
• added an examples for Transaction API (see src/test/java/com/arangodb/example/TransactionExample.java)
• fixed issue #17
  • Changed TransactionEntity.ReadWriteCollections to a static class

since 2.5.6

• fixed issue #19
  • createEdge takes graphName but needs database name
• ArangoDB 2.6 support