-
Notifications
You must be signed in to change notification settings - Fork 0
Documentation
After this guide, I guarantee, you will never be required to see the documentation of this database. This guide will explain everything step-by-step with examples. So let's begin with the index.
It would be best if you first read Acknowledegement and javadocs. Anyway, let's get started.
First of all, you have to get a singleton instance of the class. Singleton so that no other instance can modify the database concurrently. Get it by static getInstance(dir, String) method passing root directory and name of the database. Then get root collection by calling getDatabase() method.
Example:
Collection root = Clorastore.getInstance(dir, "demo").getDatabase();
There is also getDatabase(String relativePath) method which also takes collections relative path from root. For example if there is a collection named 'mens' inside collection 'humans', you can pass getDatabase("/humans/mens").
Note : Unlike CloremDB & SyncDB, Initializing does not load the data. It is only loaded when required.
CRUD is as easy as pie
First of all, create a new collection. We will only use this collection in the below example but you can use as many as you want. Every collection can contain an unlimited number of documents each with its data. Note: Document can contain a maximum of 10 MB of data. This is to avoid speed capping.
Collection collection = root.collection("contributors");Then inside the collection, create a document & set the data to it.
Map<String,Object> map = new HashMap<>();
map.put("name","Rahil");
map.put("score",78);
map.put("isMale",true);
root.document("myDoc").setData(map);
root.document("myDoc").setObject(new Person(1,"Rahil"));To read data of a document, just use getData() and getAsObject() respectively
Map<String,? super Object> map = root.document("myDoc").data;
String name = (String) map.get("name");
int score = (int) map.get("score");
boolean gender = (boolean) map.get("isMale");or you can use the getBoolean(), getString() or get
There are 2 ways of updating data. One by setting new data to document and another by updating them one-by-one.
In this way, we will again set data but with modified/updated map.
Map<String,Object> map = new HashMap<>();
map.put("name","Rahil khan");
map.put("score",98);
map.put("isMale",true);
map.put("foo",bar) // Optional, To add new field in the document
root.document("myDoc").setData(map);In this way, we will only update required fields.
root.document("myDoc").put("name","Rahil khan mev");You can also itrate over data in the database. First iterate over collection followed by documents and finally over their data. See the example below Example:
for (Collection collection : root.getCollections()){
// All the collections in the 'root'
for (String name : collection.getDocuments()){
// Name of documents in each collection
Document document = collection.document(name);
// Iterating over map of each document
document.getData().forEach((key,value) -> {
// TODO : Your operation on data
});
}
}In the above example, we first loop over all the collections present in the 'root' collection. Then for every collection, we iterate over their documents followed by the data of each document. This way we can iterate over the whole database. This is useful while manual sorting of data.
Deleting data is also as simple as hell. Just call delete() method on the document or collection you want to delete.
Example
root.document("anas").delete(); // Deletes the document from itself
root.delete("shubam"); // deletes the document from its collection
db.delete(); // Deletes the whole databaseQuery comes handy when you want to retrive data by filtering them on the basis of some condition.
To query data, call query() method on the collection from where to start querying. Consider the below data,
Map<String,Object> rahil = new HashMap<>();
rahil.put("github","@Errorxcode");
rahil.put("score",86);
rahil.put("isStudent",true);
Map<String,Object> shubam = new HashMap<>();
shubam.put("github","@shubhamp98");
shubam.put("score",72);
shubam.put("isStudent",false);
Map<String,Object> anas = new HashMap<>();
anas.put("github","@anas43950");
anas.put("score",98);
anas.put("isStudent",true);
root.document("rahil").setData(rahil);
root.document("shubam").setData(shubam);
root.document("anas").setData(anas);Now,
List<Document> topers = root.query().whereGreater("score", 80); // [anas,rahil]List<Document> rahil = root.query().whereEqual("github","@ErrorxCode"); // [rahil]List<Document> students = root.query().where(map -> ((boolean) map.getOrDefault("isStudent",false)));List<Document> docs = root.query().orderBy("age",true);
You can also use this query on objects. Like this,
List<Document> documents = root.query().whereObject(Person.class, person -> person.id == 1); // [user1]CAUTION : Always Use getDefault() instead of get() method to avoid Exception. If the key passed in get(String key) is not present in every document, It will return null which may lead to some sort of exception.
A all-in-one example will help you understand better. Here it is:-
Map<String,Object> rahil = new HashMap<>();
rahil.put("github","@Errorxcode");
rahil.put("score",86);
rahil.put("isStudent",true);
Map<String,Object> shubam = new HashMap<>();
rahil.put("github","@shubhamp98");
rahil.put("score",72);
rahil.put("isStudent",false);
Map<String,Object> anas = new HashMap<>();
rahil.put("github","@anas43950");
rahil.put("score",98);
rahil.put("isStudent",true);
// Inserting data
root.document("rahil").setData(rahil);
root.document("shubam").setData(shubam);
root.document("anas").setData(anas);
// Reading data
String name = (String) root.document("rahil").getString("github","");
int score = (int) root.document("shubam").getData().getNumber("score",-1);
boolean student = (boolean) root.document("anas").getBoolean("isStudent",false);
// Updating data
root.document("rahil").put("score",90);
root.document("shubam").put("isStudent",true);
root.document("anas").put("isStudent",false);
// Deleting
root.document("anas").delete();
root.delete("shubam");
db.delete();doc.addItem("names","Item5");
doc.removeItem("names","Item4");
List<String> list = doc.getList("names");That's all that you need to learn about the "Clorastore database". You have mastered the database, it's time to contribute now.