JSDB (Java Simple DB)

A simple Mongo like interface upon SQLite.

The JSDB interface provides a MONGO like interface on top of SQLite for those how looking simple (Java/Json) interface and embeded database.

Below follows some examples outlining the essential functionality provided by JSDB Full examples are found in the TestDB.java class.

Create Database

public static void createDatabase(String pSqlFile) throws JSDBException

Create a Database file in the location specified by the parameter pSqlFile

Create Collection

 public JSDBCollection createCollection(String pName, JSDBKey... pKeys ) throws JSDBException

Creates a Collection with keys specified by the parameter pKeys

     public JSDBKey(String pId, Class pType, boolean pUnique, boolean pPrimaryKey)
     public JSDBKey(String pId, Class pType)

Open Database

 public void openDatabase( String pSqlFile) throws JSDBException

Open a Database in the location specified by the parameter pSqlFile

Close Database

public void closeDatabase()

Close an open database

Get Collection

public JSDBCollection getCollections(String pName) throws JSDBException

Get a Collection object specified by the pName parameter

JSDBCollection

All operations on data in the DB is performed in the context of a collection. The JSDBCollection interface provides the following functionality.

Find All

public List<JsonObject> findAll() throws JSDBException 

Retrieve all JsonObjects kept/stored in the collection.

public List<JsonObject> findAll(int pOffset, int pMaxObjects ) throws JSDBException 

Retrieve all JsonObjects kept/stored in the collection from pOffset and limited to pMaxObjects. May be applicable when having large data sets.

Find

public List<JsonObject> find(String pFilterString) throws JSDBException 

Retrieve all JsonObjects kept/stored in the collection matching the filter specified by the parameter pFilterString

Insert

public void insert(JsonObject pObject, boolean pUpdate) throws JSDBException

Insert (or update) a JsonObject in the collection. An update will occur if the object exists and the pUpdate parameter is true. If the objects exists and the pUpdate parameter is false, an exception is thrown.

public void insert(JsonObject pObject) throws JSDBException

Insert or update a JsonObject in the collection. An update will occur if the object exists.

Update

public int update(String pFilterString, JsonObject pDeltaObject ) throws JSDBException

Updates objects in the collection with data specified by the parameter pDeltaObject matching the filter specified by the the pFilterString parameter.

The pDeltaObject contains the field/structor of the data that should be updated. The delta object contains a subset of the data elements in the JSON objects kept/stored in the collection.

public void update(JsonObject pObject, boolean insert) throws JSDBException 

Update (or insert) an JsonObject in the collection. An insert will occur if the object does exists and the pInsert parameter is true. If the object does not exist and the pInsert parameter is false, an exception is thrown.

public void update(JsonObject pObject) throws JSDBException

Update a JsonObject in the collection. If the object does not exists an exception is thrown.

Delete

public void deleteAll() throws JSDBException

Deletes all JsonObject in the collection.

public void delete( String pFilterString) throws JSDBException 

Deletes all JsonObject in the collection matching the the filter.

Collection Filter

A collection filter is used to select a set of JsonObjects from the collections. The filter is a combination of logical operators, fields and properaties.

For example;

    ($and: ($gt: (age, 28)) ($like: (name,'Fr%')))

in the example above any JsonObject containing a field 'age' having a value > 28 and a field 'name' having a (string) value starting with 'Fr' will match and be subject for operation.

The logical operation on data field are $GT:,$GTE:,$LT:,$LTE:,$NE:,$EQ:,$LIKE: For booleans the $NE:,$EQ: operators are the only applicable ones. The $LIKE: operator is only applicable for String fields, and have the save semantic as SQL LIKE.

The operator $AND: and $OR: are used to combined 2 or more logical expressions.

It's possible to specify fields in Json object substructures. The character "." is used as separator of structures

    {"foo": {"bar" : {"frotz" : 4711}}}
}

The notation for addressing the field 'frotz' is equivalent to "foo.bar.frotz"

Note! if a field specified in a filter is not a key in the collection, the filter needs to be matched against the JSON object. This requires that data in the collection needs to be converted from its internal representation i.e. Json string to a Json object in order to performe the matching. A worst case scenario is when the filter does not contain any collection key. Then all objects must be retrieved and unpacked for matching. However, if the filter contains collection key(s) the selction will be narrowed down to the collection key subset. This can and most like will improve performance significantly.

Coding of JsonObject

By default, JsonObjects are encoded as strings when kept in the database. Encoding/decoding of JsonObjects are surprisingly fast but when fiding objects with filters having attributes not being keys in the database, many objects may be required to be decoded in order to the filtering, it could be several thousends. This is of cause takes a fair bit of time. But by using the DB keys, if any when being part a filter and using an alternative coding of JsonObjects performance is improved.

The alternative codec, JCodec is a binary coding of objects and is approximately 3-4 times faster than the pure String encoding of the JsonObjects. By default String encoding is enabled. To change the encoding see JSDB.USE_JCODEC variable in the file JSDB.java.