JarCastingSnappyDB
SnappyDB is a key-value database for Android it's an alternative for SQLite if you want to use a NoSQL approach.
It allows you to store and get primitive types, but also a Serializable object or array in a type-safe way.
SnappyDB can outperform SQLite in read/write operations.
SnappyDB is based on leveldb and use snappy compression algorithm, on redundant content you could achieve a good compression ratio
Check out the Demo App
Usage
try {
DB snappydb = DBFactory.open(context); //create or open an existing database using the default name
snappydb.put("name", "Jack Reacher");
snappydb.putInt("age", 42);
snappydb.putBoolean("single", true);
snappydb.put("books", new String[]{"One Shot", "Tripwire", "61 Hours"});
String name = snappydb.get("name");
int age = snappydb.getInt("age");
boolean single = snappydb.getBoolean("single");
String[] books = snappydb.getArray("books", String.class);// get array of string
snappydb.close();
} catch (SnappydbException e) {
}
For more recipes please take a look at the Cookbook.
With SnappyDB you could seamlessly store and retrieve your object/array, it uses Kryo serialization which is faster than the regular Java serialization.
Installation
SnappyDB uses native code for performance, it's available as an Android Library Project AAR.
dependencies {
compile 'com.snappydb:snappydb-lib:0.5.2'
compile 'com.esotericsoftware.kryo:kryo:2.24.0'
}
or
Manual:
- Download JAR file and other folders from here
- Put all the files and folders in the libs subfolder of your Android project
libs
├───|── snappydb-0.5.2.jar
|── armeabi
│ └── libsnappydb-native.so
├── armeabi-v7a
│ └── libsnappydb-native.so
├── mips
│ └── libsnappydb-native.so
└── x86
└── libsnappydb-native.so
Cookbook
Common tasks snippets
- Open/Create database
- Close database
- Destroy database
- Insert primitive types
- Read primitive types
- Insert Serializable
- Insert Object
- Read Serializable
- Read Object
- Insert Array
- Read Array
- Check key
- Delete key
- Keys Search
- Keys Count
- Iterators
Create database
Create using the default name
DB snappydb = DBFactory.open(context);
Create with a given name
DB snappydb = DBFactory.open(context, "books");
SnappyDB use the internal storage to create your database. It creates a directory containing all the necessary files Ex: /data/data/com.snappydb/files/mydatabse
Using the builder pattern
DB snappyDB = new SnappyDB.Builder(context)
.directory(Environment.getExternalStorageDirectory().getAbsolutePath()) //optional
.name("books")//optional
.build();
directory Specify the location of the database (sdcard in this example)
Close database
snappydb.close();
Destroy database
snappydb.destroy();
Insert primitive types
snappyDB.put("quote", "bazinga!");
snappyDB.putShort("myshort", (short)32768);
snappyDB.putInt("max_int", Integer.MAX_VALUE);
snappyDB.putLong("max_long", Long.MAX_VALUE);
snappyDB.putDouble("max_double", Double.MAX_VALUE);
snappyDB.putFloat("myfloat", 10.30f);
snappyDB.putBoolean("myboolean", true);
Read primitive types
String quote = snappyDB.get("quote");
short myshort = snappyDB.getShort("myshort");
int maxInt = snappyDB.getInt("max_int");
long maxLong = snappyDB.getLong("max_long");
double maxDouble = snappyDB.getDouble("max_double");
float myFloat = snappyDB.getFloat("myfloat");
boolean myBoolean = snappyDB.getBoolean("myboolean");
Insert Serializable
AtomicInteger objAtomicInt = new AtomicInteger (42);
snappyDB.put("atomic integer", objAtomicInt);
Insert Object
MyPojo pojo = new MyPojo ();
snappyDB.put("my_pojo", pojo);
Note: MyPojo doesn't have to implement Serializable interface
Read Serializable
AtomicInteger myObject = snappyDB.get("atomic integer", AtomicInteger.class);
Read Object
MyPojo myObject = snappyDB.getObject("non_serializable", MyPojo.class);
Note: MyPojo doesn't have to implement Serializable interface
Insert Array
Number[] array = {new AtomicInteger (42), new BigDecimal("10E8"), Double.valueOf(Math.PI)};
snappyDB.put("array", array);
Read Array
Number [] numbers = snappyDB.getObjectArray("array", Number.class);
Check Key
boolean isKeyExist = snappyDB.exists("key");
Delete Key
snappyDB.del("key");
Keys Search
By Prefix
snappyDB.put("android:03", "Cupcake"); // adding 0 to maintain lexicographical order
snappyDB.put("android:04", "Donut");
snappyDB.put("android:05", "Eclair");
snappyDB.put("android:08", "Froyo");
snappyDB.put("android:09", "Gingerbread");
snappyDB.put("android:11", "Honeycomb");
snappyDB.put("android:14", "Ice Cream Sandwich");
snappyDB.put("android:16", "Jelly Bean");
snappyDB.put("android:19", "KitKat");
String [] keys = snappyDB.findKeys("android");
assert keys.length == 9;
keys = snappyDB.findKeys("android:0");
assert keys.length == 5;
assert snappyDB.get(keys[0]).equals("Cupcake");
assert snappyDB.get(keys[1]).equals("Donut");
assert snappyDB.get(keys[2]).equals("Eclair");
assert snappyDB.get(keys[3]).equals("Froyo");
assert snappyDB.get(keys[4]).equals("Gingerbread");
keys = snappyDB.findKeys("android:1");
assert keys.length == 4;
assert snappyDB.get(keys[0]).equals("Honeycomb");
assert snappyDB.get(keys[1]).equals("Ice Cream Sandwich");
assert snappyDB.get(keys[2]).equals("Jelly Bean");
assert snappyDB.get(keys[3]).equals("KitKat");
By Range [from .. to]
- both 'FROM' & 'TO' keys exist
keys = snappyDB.findKeysBetween("android:08", "android:11");
assertEquals(3, keys.length);
assertEquals("android:08", keys[0]);
assertEquals("android:09", keys[1]);
assertEquals("android:11", keys[2]);
- 'FROM' key exist, but not the `TO
keys = snappyDB.findKeysBetween("android:05", "android:10");
assertEquals(3, keys.length);
assertEquals("android:05", keys[0]);
assertEquals("android:08", keys[1]);
assertEquals("android:09", keys[2]);
- 'FROM' key doesn't exist but the 'TO' key do
keys = snappyDB.findKeysBetween("android:07", "android:09");
assertEquals(2, keys.length);
assertEquals("android:08", keys[0]);
assertEquals("android:09", keys[1]);
- both 'FROM' & 'TO' keys doesn't exist
keys = snappyDB.findKeysBetween("android:13", "android:99");
assertEquals(3, keys.length);
assertEquals("android:14", keys[0]);
assertEquals("android:16", keys[1]);
assertEquals("android:19", keys[2]);
With offset and limit
//return all keys starting with "android" after the first 5
keys = snappyDB.findKeys("android", 5);
assertEquals(4, keys.length);
assertEquals("android:11", keys[0]);
assertEquals("android:14", keys[1]);
assertEquals("android:16", keys[2]);
assertEquals("android:19", keys[3]);
//return 3 first keys starting with "android"
keys = snappyDB.findKeys("android", 0, 3);
assertEquals(3, keys.length);
assertEquals("android:03", keys[0]);
assertEquals("android:04", keys[1]);
assertEquals("android:05", keys[2]);
//return the fourth key starting with "android" (offset 3, limit 1)
keys = snappyDB.findKeys("android", 3, 1);
assertEquals(1, keys.length);
assertEquals("android:08", keys[0]);
//return the two first keys between android:14 and android:99
keys = snappyDB.findKeysBetween("android:14", "android:99", 0, 2);
assertEquals(2, keys.length);
assertEquals("android:14", keys[0]);
assertEquals("android:16", keys[1]);
//return the third key (offset 2, limit 1) after android:10 before android:99
keys = snappyDB.findKeysBetween("android:10", "android:99", 2, 1);
assertEquals(1, keys.length);
assertEquals("android:16", keys[0]);
Keys Count
Counting is quicker than extracting values (if you don't need them). Especially on very big collections.
By Prefix
assertEquals(9, snappyDB.countKeys("android"));
assertEquals(5, snappyDB.countKeys("android:0"));
By Range [from .. to]
assertEquals(3, snappyDB.countKeysBetween("android:08", "android:11"));
assertEquals(3, snappyDB.countKeysBetween("android:13", "android:99"));
Iterators
Each time you use the offset & limit arguments, the engine makes the query and then scrolls to your offset. Which means that the bigger the offset is, the longer the query will take. This is not a problem on small collections, but on very large collections, it is.
An iterator keeps it's position in the key collection and can be asked for the next key at any time. It is therefore better to use an iterator on very large collections.
Iterators work on DB snapshot, which means that if you add or delete value in / from the DB, the iterators will not see those changes.
Please note that iterators given by the SnappyDB are closeable and need to be closed once finished with. As iterators work on a DB snapshot, not closing them is a serious memory leak.
// An iterator to all keys
it = snappyDB.allKeysIterator();
/*...*/
it.close();
// An iterator to all keys in reverse order
it = snappyDB.allKeysReverseIterator();
/*...*/
it.close();
// An iterator to all keys including and after android:14
it = snappyDB.findKeysIterator("android:14");
/*...*/
it.close();
// An iterator to all keys from android:05 to android:10
it = snappyDB.findKeysBetweenIterator("android:05", "android:10");
/*...*/
it.close();
// An iterator to all keys from android:09 to android:05 in reverse order
it = snappyDB.findKeysBetweenReverseIterator("android:09", "android:05");
/*...*/
it.close();
Here are the methods implemented in KeyIterator :
public boolean hasNext(); // Whether or not this is the last key.
public String[] next(int max); // Get an array of next keys (maximum [max] keys).
void close(); // Closes the iterator.
Iterable<String[]> byBatch(int size); // Get an iterable of key batch, each batch of maximum [size] keys.
Iterators work on key batchs (key arrays) and not directly on keys. You may iterate on all keys with the form:
for (String[] batch : db.findKeysIterator("android").byBatch(BATCH_SIZE)) {
for (String key : batch) {
/*...*/
}
}
Please note that you should use the byBatch iterable to process all keys only on large collections. On reasonably small collections, using the array based APIs (findKeys and findKeysBetween) with the form for (String key : db.findKeys("android")) is a lot more efficient.
Iterators should only be used to process large collections or for collection paging view / access.
License
SnappyDB is opensource, contribution and feedback are welcomed
Copyright 2013 Nabil HACHICHA.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
