Skip to content

Java Client API

Jump to bottom
Renze de Vries edited this page Nov 24, 2015 · 2 revisions

Java Client API

JasDB has a number of API’s available that use different transport mechanisms to send your data to JasDB. The API, regardless of which transport protocol is used, is always the same. For a full oversight of the JasDB API have a look at the Javadocs: JasDB Javadoc

The samples on this page are based on using a LocalDBSession, in case of Android check Using JasDB on Android devices or REST check REST service for information on starting a session.

This page explains API calls for Instances (database container), Bags (Table equivalent) and Entities (the actual data).

Local JasDB session

In order to use a local (in-process) JasDB instance, the following code can be used to obtain a session to the remote DB:

DBSession session = new LocalDBSession();
session.createOrGetBag("MySpecialBag");

By default JasDB connects to the default instance which is stored inside the JASDB_HOME folder.

API Usage

Most operations take place on the DBSession object which holds a JasDB session. This object contains operations to create, remove and retrieve a list of bags. The EntityBags themselves contain operations for inserting, removing, updating and searching for entities. Next to this, the EntityBag has the ability to create, list and remove indexes. For an overview of the terminology we use in JasDB, check the JasDB definitions page.

Creating and retrieving Instances

In JasDB it is possible to create new instances separate from the default instances. The following API call can be used to connect to the default instance and create a new instance:

DBSession session = new LocalDBSession();
session.addInstance("myInstance", "/opt/myDataStore");

After an instance is created the session can be switched like following:

session.switchInstance("myInstance");

Also it is possible to directly connect the session to the instance:

DBSession session = new LocalDBSession("myInstance");

Also it is possible to delete a session and all its bags and entities (this operation is destructive):

session.deleteInstance("myInstance");

Creating and retrieving bags

The following code can be used to create and retrieve a bag:

EntityBag bag = session.createOrGetBag("MyBag");

If you just want to retrieve a bag, the following can be used:

EntityBag bag = session.getBag("MyBag");

In order to remove a bag the following can be used:

session.removeBag("MyBag");

Inserting and Retrieving entities

A small code example of creating an entity and adding it to the bag:

SimpleEntity entity = new SimpleEntity();
entity.addProperty("title", "Title of my content");
entity.addProperty("text", "Some big piece of text content");
bag.addEntity(entity);

Retrieving an entity by id:

bag.getEntity("056f8058-e1f7-4f8e-a2f8-332e62c15961");

Removing an entity:

bag.removeEntity(bag.getEntity("056f8058-e1f7-4f8e-a2f8-332e62c15961"));

Querying Entities

The Java Client API has extensive capabilities for querying the content, however it is important to note that indexes are vital to increase performance of the queries.

A very simple basic query looks like this

QueryExecutor executor = bag.find(QueryBuilder.createBuilder().field("field").value(queryKey));
QueryResult result = executor.execute();
for(SimpleEntity entity : result) {
   //access the properties if desired
   entity.getProperty("field1");
}

Adding limiting to the query

QueryExecutor executor = bag.find(QueryBuilder.createBuilder().field("age").value(20));
executor.limit(5);
QueryResult result = executor.execute();

With pagination of the results

QueryExecutor executor = bag.find(QueryBuilder.createBuilder().field("age").value(20));
executor.paging(5, 10); //gets from 5, the next 10
QueryResult result = executor.execute();

Query with multiple conditions and OR operator

QueryExecutor executor = bag.find(QueryBuilder.createBuilder()
    .field("field1").value("Value2")
    .or(QueryBuilder.createBuilder().field("field1").value("AnotherValue)));

Query with multiple conditions and AND operator

QueryExecutor executor = bag.find(QueryBuilder.createBuilder().field("field1")
   .value("value").field("field2").value("samevalueDifferentField));

Sorting of the query results with range query

QueryExecutor executor = bag.find(QueryBuilder.createBuilder().field("age")
   .greaterThan(10).field("age").smallerThan(30).sortBy("country"));

Creating indexes

The below example shows how to create an index with a unique constraint check (meaning the value needs to always be unique) on the field called ‘testkey’ and the field containing a string of maximum 200 characters:

bag.ensureIndex(new IndexField("testkey", new StringKeyType(200)), true);

The indexes are created on the bags and require that a property with a value is present. Also the index has a keytype, the above example uses ‘StringKeyType’, meaning that the entity should have a property of the same data type.

The available key types: LongKeyType UUIDKeyType StringKeyType

Also it is possible to create a non-unique index which can be used for a variety of purposes, the index allows for example to map every entity to a keyword or implement even text searches:

bag.ensureIndex(new IndexField("keywords", new StringKeyType(50)), false);

It is also possible to create multi-key indexes, for that the CompositeIndexField can be used like this:

bag.ensureIndex(new CompositeIndexField(new IndexField("age", new LongKeyType()), 
   new IndexField("city", new StringKeyType(200))), false);

Maven Artifacts

<dependency>
   <groupId>nl.renarj</groupId>
   <artifactId>jasdb_localservice</artifactId>
   <version>1.1.2</version>
</dependency>
Clone this wiki locally