Существуют различные решения NoSQL для мобильных платформ, таких как iOS и Android. Здесь мы рассмотрим Couchbase Lite (CBL — преемник TouchDB), легкую, полнофункциональную встроенную базу данных JSON.
Почему полнофункциональная база данных, а не просто оболочка для облачного сервиса? В основном, отзывчивость . Идея заключается в том, что приложение всегда должно быть доступно пользователям, даже если сеть не работает или работает медленно. Конечно, возможность работать с данными локально также означает, что в какой-то момент нам придется синхронизироваться с сервером.
Обратите внимание, что CBL значительно отличается от Apache CouchDB, несмотря на «Couch».
Теперь давайте приступим к делу и создадим небольшое приложение для Android (весь код доступен на GitHub ), которое настраивает базу данных с использованием собственного API CBL и выполняет основные операции CRUD.
После прохождения относительно легкой установки ( это один для хороших старых пользователей Eclipse, что один для поклонников Android Studio), давайте начнем писать код:
import com.couchbase.lite.*;
import com.couchbase.lite.android.AndroidContext;
/** Database wrapper*/
public class CbDatabase {
private Database database;
private Manager manager;
/** Ctor Setup */
public CbDatabase(String dbname)
throws IOException, CouchbaseLiteException {
// 1. use default settings (read/write access)
manager = new Manager( new AndroidContext(ctx),
Manager.DEFAULT_OPTIONS );
// 2. Check database name given by user
// No upper case allowed in CBL!
// Only the following characters are valid:
// abcdefghijklmnopqrstuvwxyz0123456789_$()+-/
if ( ! Manager.isValidDatabaseName(dbname)) {
// report...
return;
}
// 3. Get existing db with that name
// or create a new one if it doesn't exist
database = manager.getDatabase(dbname);
}
//...more methods to come
}
Приведенный выше код использует Manager для настройки базы данных с допустимым именем. CBL базы данных в основном контейнер для документов. Менеджер может создать несколько разных баз данных, каждая со своим собственным пространством имен. Вот как освободить все ресурсы:
/** */
public void close(){
if(manager != null){
manager.close();
}
}
Once given the Database object, we are now ready to do CRUD operations on it:
/** C-rud */
public String create( Map<String, Object> docContent )
throws CouchbaseLiteException {
// create an empty document
Document doc = database.createDocument();
// add content to document and save it
doc.putProperties(docContent);
return doc.getId();
}
A CBL Document is the primary entity stored in a database, and has the following attributes:
- A unique ID (_id property) which can be automatically generated as a UUID
- A revision ID (_rev property) to keep track of updates
- A set of key/value pairs forming the body of the Document
Once created, we can retrieve a Document’s content by its id:
/** c-R-ud */
public Map<String, Object> retrieve(String docId){
return database.getDocument(docId)
.getProperties();
}
We can update an existing key/value pair entry in a Document by using a callback:
/** cr-U-d (auto-retry) */
public void update( final String key, final Object value,
String docId )
throws CouchbaseLiteException {
// retrieve the document from the database
Document doc = database.getDocument(docId);
doc.update(new Document.DocumentUpdater() {
@Override
/** This may be called more than once */
public boolean update(UnsavedRevision newRevision) {
Map<String, Object> properties = newRevision.getUserProperties();
properties.put(key, value);
newRevision.setUserProperties(properties);
return true;
}
});
}
The method retries automatically the update in case of write conflicts by re-reading the Document and re-calling the callback method. That process will continue until the write succeeds. As its name implies, UnsavedRevision is a mutable copy to work with until data is finally persisted to the database.
Deleting a Document is pretty straightforward. Here, we do it by its id:
/** cru-D */
public boolean delete(String docId)
throws CouchbaseLiteException {
// retrieve the document from the database
Document doc = database.getDocument(docId);
// delete the document
doc.delete();
return doc.isDeleted();
}
Deleting the Document will create a new revision called the “tombstone” (no kidding). It will be marked as deleted so that its status can be replicated to a server when doing a sync. As for updates, this can lead to conflicts if other users made changes to the same Document. In that case, the decision to retry the delete is left to us.
We are now ready to use this wrapper class in our project. First, let’s define our use case: let’s say we need to store locally some user data for our mobile games, like the user email, when the user registered in our system, and a bunch of game scores. Here’s a quick test we can run in our main Activity’s onCreate() method. First, let’s input some data:
// get the current date and time
Date now = new Date();
String nowString = DateFormat.getDateTimeInstance(
DateFormat.LONG, DateFormat.LONG).format(now);
// game scores
List<Double> scores = new ArrayList<Double>();
scores.add(190.00);
scores.add(210.00);
scores.add(250.00);
scores.add(275.00);
// create an object that contains data for a document
Map<String, Object> docContent = new HashMap<String, Object>();
docContent.put("email", "[email protected]");
docContent.put("registered", nowString);
docContent.put("scores", scores);
Now, the database operations:
try{
CbDatabase db = new CbDatabase("testdb");
// 1. Create
String docId = db.create(docContent);
// 2. Retrieve
Map<String, Object> docContent = db.retrieve(docId);
// 3. Update
scores.add(350.00);
db.update("scores", scores, docId);
// 4. Delete
boolean deleted = db.delete(docId);
assert(deleted == true);
}
catch (Exception e) {
// handle here...
}
finally{
if(db != null){
db.close();
}
}
Here are the corresponding JSON Documents for Retrieve and Update:
// retrieved
{
_rev=1-1ef4c4618a712cdf437d4b0c92594ddc,
_id=69fdcb83-1774-4a3f-9e88-b298d3c7304a,
scores=[190.0, 210.0, 250.0, 275.0],
[email protected],
registered=June 18, 2014 11:03:18 AM GMT+02:00
}
//--------------------------------------------
// updated scores: note the change in revision
{
_rev=2-23e6d83d243f80c03b17c4160d511e16,
scores=[190.0, 210.0, 250.0, 275.0, 350.0],
_id=69fdcb83-1774-4a3f-9e88-b298d3c7304a,
[email protected],
registered=June 18, 2014 11:03:18 AM GMT+02:00
}
That’s it. Further code details are on GitHub. We just scratched the surface of CBL with this very basic introduction. Unfortunately, the CBL online documentation for Android is incomplete at this time, compared to the one for the iOS. Anyway, there are other important CBL features like adding attachments, Views & Queries, replication (Server & P2P), a REST API, etc. Those would be the subjects of future articles.