Paper
Paper is a fast NoSQL data storage for Android that lets you save/restore Java objects by using efficient Kryo serialization and handling data structure changes automatically.
Add dependency
compile 'io.paperdb:paperdb:1.0'
Initialize Paper
Should be initialized one time in onCreate() in Application or Activity.
Paper.init(context);
It's OK to call it in UI thread. All other methods should be used in background thread.
Save
Save data object. Your custom classes must have no-arg constructor. Paper creates separate data file for each key.
Paper.book().write("city", "Lund"); // Primitive
Paper.book().write("task-queue", queue); // LinkedList
Paper.book().write("countries", countryCodeMap); // HashMap
Read
Read data objects. Paper instantiates exactly the classes which has been used in saved data. The limited backward and forward compatibility is supported. See Handle data class changes.
String city = Paper.book().read("city");
LinkedList queue = Paper.book().read("task-queue");
HashMap countryCodeMap = Paper.book().read("countries");
Use default values if object doesn't exist in the storage.
String city = Paper.book().read("city", "Kyiv");
LinkedList queue = Paper.book().read("task-queue", new LinkedList());
HashMap countryCodeMap = Paper.book().read("countries", new HashMap());
Delete
Delete data for one key.
Paper.book().delete("countries");
Completely destroys Paper storage. Requires to call Paper.init()
before usage.
Paper.book().destroy();
Use custom book
You can create custom Book with separate storage using
Paper.book("custom-book")...;
Any changes in one book doesn't affect to others books.
Handle data structure changes
Class fields which has been removed will be ignored on restore and new fields will have their default values. For example, if you have following data class saved in Paper storage:
class Volcano {
public String name; // I like Eyjafjallajökull
public boolean isActive;
}
And then you realized you need to change the class like:
class Volcano {
public String name; // I like Eyjafjallajökull
// public boolean isActive; removed field, who cares about volcano activity
public Location location; // New field
}
Then on restore the isActive field will be ignored and new location field will have its default value null.
Exclude fields
Use transient keyword for fields which you want to exclude from saving process.
public transient String tempId = "default"; // Won't be saved
Proguard config
- Keep data classes:
-keep class my.package.data.model.** { *; }
alternatively you can implement Serializable in all your data classes and keep all of them using:
-keep class * implements java.io.Serializable { *; }
- Keep library classes and its dependencies
-keep class io.paperdb.** { *; }
-keep class com.esotericsoftware.** { *; }
-dontwarn com.esotericsoftware.**
-keep class de.javakaffee.kryoserializers.** { *; }
-dontwarn de.javakaffee.kryoserializers.**
How it works
Paper is based on the following assumptions:
- Saved data on mobile are relatively small;
- Random file access on flash storage is very fast.
So each data object is saved in separate file and write/read operations write/read whole file.
The Kryo is used for object graph serialization and to provide data compatibility support.
Benchmark results
Running Benchmark on Nexus 4, in ms:
Benchmark | Paper | Hawk | sqlite |
---|---|---|---|
Read/write 500 contacts | 187 | 447 | |
Write 500 contacts | 108 | 221 | |
Read 500 contacts | 79 | 155 |
Apps using Paper
- AppDialer – Paper initially has been developed to reduce start up time for AppDialer. Currently AppDialer has the best start up time in its class. And simple no-sql-pain data storage layer like a bonus.
License
Copyright 2015 Aleksey Masny
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.