MongoDB Programming Guide

This document explains how you can access MongoDB using IRIS Storage APIs. Through this guide, you will be able to learn how to make various IRIS modules and applications with a persistent storage. As you might already know, MongoDB provides Java driver with various powerful APIs as a default. IRIS Storage APIs are very similar to that of MongoDB’s Java APIs. However, we tried our best to provide the ease of programming on top of that by hiding some MongoDB specific information. Actually, there are two ways to program your modules or applications. First method is to use IRIS Storage Java APIs, and the other method is to use IRIS Storage REST APIs.

Java APIs for IRIS Storage

In most cases, we recommend you to use Java APIs for module programming. You need to understand OFModule and OFModel to develop modules for IRIS controller using the APIs.

this.storageInstance = (OFMStorageManager) getModule(IStorageService.class);

As above, we get the storage instance with getModule method.

1. CRUD operations
   1. Insertion
   2. Retrieval
   3. Update
   4. Deletion
2. Other operations
   1. retrieveDBs
   2. dropDB
   3. ensureIndex
   4. dropIndex
   5. ensureIndex
   6. getIndex

Insertion

...	
String dbName = "mydb";
String collection = "test";
Map<String, Object> data = new HashMap<String, Object>();
data.put("key test", "value test");
data.put("key name", "value justin");
data.put("key age", "value 20");
							
try {
	storageInstance.insert(dbName, collection, (Map<String, Object>)data);
	} catch (StorageException e) {
		e.printStackTrace();
	}
}
...

As you can see, insertion is very simple. You need database name, collection name, and data. The data you put in has to be either Map<String, Object> or String in JSON format.

Retrieval

...
Map<String, Object> query = new HashMap<String, Object>();
query.put("key test", "value test");

try {
	List<Map<String, Object>> result = storageInstance.retrieve(dbName, collection, query);
                for(Map<String, Object> m : result) {
		System.out.println(m);
	}
} catch (StorageException e) {
	e.printStackTrace();
}
...

In the above retrieval example, the method retrieves all the data that mathces {“key test”:”value test”} in the storage.

Update

...
HashMap<String, Object>();
key.put("key test", "value test");
query = new HashMap<String, Object>();
query.put("key age", "value 40");
try {
       storageInstance.update(dbName, collection, key, query);
} catch (StorageException e) {
       e.printStackTrace();
}

In the above example, The key is used to find data that matches, and after finding the data, data is replaced with updateQuery. The whole data is replaced with updateQuery. Unless updateQuery has all the key-value pairs, some key-value paris in the original will be lost. To prevent this from happening, you can use $set in the key field. This is explained in the next example.

...
Map<String, Object> key = new HashMap<String, Object>();
key.put("key test", "value test");
							
query = new HashMap<String, Object>();
query.put("key age", "value 30");
							
Map<String, Object> updateQuery = new HashMap<String, Object>();
updateQuery.put("$set", query);
							
try {
	storageInstance.update(dbName, collection, key, updateQuery);
} catch (StorageException e) {
	e.printStackTrace();
}
...

This example is same as first retrieve example, except for the updateQuery uses $set. If you put $set at key position in updateQuery, all other key-value pairs are preserved. Otherwise, the whole data is replaced with updateQuery.

Deletion

...
HashMap<String, Object>();
query.put("key name", "value Amber");
try {
boolean result = storageInstance.delete(dbName, collection, query);
} catch (StorageException e) {
e.printStackTrace();
...

In the above deletion example, the method deletes all the data that mathces {“key test”:”value test”} in the storage.

REST APIs for IRIS Storage

You can use the below REST APIs to develop applications utilizing IRIS Storage features. The API is available at port 8080 of the controller.

An example REST call is:

curl http://localhost:8080/wm/core/controller/database

URI	Method	Description
/wm/core/controller/database	GET	retrieve names of databases as a List.
/wm/core/controller/database/drop/{dbname}	GET	to drop a database.
/wm/core/controller/database/{dbname}/{collection}/insert	POST	inserts data into persistent storage.
/wm/core/controller/database/{dbname}/{collection}/upsert	POST	upserts data into persistent storage.
/wm/core/controller/database/{dbname}/{collection}/update	POST	updates data into persistent storage.
/wm/core/controller/database/{dbname}/{collection}/delete	POST	deletes data from persistent storage.
/wm/core/controller/database/{dbname}/{collection}/retrieve/all	POST	retrieves all data from a certain collection in persistent storage.
/wm/core/controller/database/{dbname}/{collection}/retrieve	POST	retrieves specific data from a certain collection in persistent storage.
/wm/core/controller/database/{dbname}/{collection}/ensureindex	POST	assigns a unique key-value pair index at a certain collection in persistent storage.
/wm/core/controller/database/{dbname}/{collection}/dropindex	POST	removes a key-value pair index at a certain collection in persistent storage.
/wm/core/controller/database/{dbname}/{collection}/getindex	GET	retrieves all key-value indexes at a certain collection in persistent storage.