@date 17-3-14
SQLBrite
========

A lightweight wrapper around SQLiteOpenHelper and ContentResolver which introduces reactive
stream semantics to queries.

對SQLiteOpenHelper 和 ContentResolver的一個輕量級包裝工具，并對查詢引入了響應(yīng)式流語法

Usage(用法)

Create a SqlBrite instance which is an adapter for the library functionality.

創(chuàng)建一個SqlBrite實例，它是庫功能的適配器。

SqlBrite sqlBrite = new SqlBrite.Builder().build();

Pass a SQLiteOpenHelper instance and a Scheduler to create a BriteDatabase.

傳入一個SQLiteOpenHelper實例和一個Scheduler 實例來創(chuàng)建 BriteDatabase

BriteDatabase db = sqlBrite.wrapDatabaseHelper(openHelper, Schedulers.io());

A Scheduler is required for a few reasons, but the most important is that query notifications can
trigger on the thread of your choice. The query can then be run without blocking the main thread or
the thread which caused the trigger.

基于一些原因 Scheduler是必須的，最主要的原因是查詢操作會在你選擇的線程上觸發(fā)通知。這個查詢過程可以不阻塞主線程的或發(fā)起查詢操作的線程。

The BriteDatabase.createQuery method is similar to SQLiteDatabase.rawQuery except it takes an
additional parameter of table(s) on which to listen for changes. Subscribe to the returned
Observable<Query> which will immediately notify with a Query to run.

BriteDatabase.createQuery 方法類似于SQLiteDatabase.rawQuery但它需要一個額外的表名參數(shù)，并會監(jiān)聽這個（些）表的改變。訂閱Observable<Query>（方法的返回值）將會立即觸發(fā)一個 Query去運行。

Observable<Query> users = db.createQuery("users", "SELECT * FROM users");
users.subscribe(new Action1<Query>() {
  @Override public void call(Query query) {
    Cursor cursor = query.run();
    // TODO parse data...
  }
});

Unlike a traditional rawQuery, updates to the specified table(s) will trigger additional
notifications for as long as you remain subscribed to the observable. This means that when you
insert, update, or delete data, any subscribed queries will update with the new data instantly.

不同于傳統(tǒng)的rawQuery， 只要你還持有方法返回值的訂閱那么對這個表的更改都會觸發(fā)額外的通知。這意味著你的插入，更新，或刪除數(shù)據(jù)都會立刻觸發(fā)訂閱的更新。

final AtomicInteger queries = new AtomicInteger();
users.subscribe(new Action1<Query>() {
  @Override public void call(Query query) {
    queries.getAndIncrement();
  }
});
System.out.println("Queries: " + queries.get()); // Prints 1

db.insert("users", createUser("jw", "Jake Wharton"));
db.insert("users", createUser("mattp", "Matt Precious"));
db.insert("users", createUser("strong", "Alec Strong"));

System.out.println("Queries: " + queries.get()); // Prints 4

In the previous example we re-used the BriteDatabase object "db" for inserts. All insert, update,
or delete operations must go through this object in order to correctly notify subscribers.

在上面的例子中我們重用BriteDarabase對象db的實例，所有的插入，更新或者刪除操作都必須使用這個對象才能正確的通知訂閱者。

Unsubscribe from the returned Subscription to stop getting updates.

調(diào)用返回值Subscription的unsubscribe方法可以停止獲取更新

final AtomicInteger queries = new AtomicInteger();
Subscription s = users.subscribe(new Action1<Query>() {
  @Override public void call(Query query) {
    queries.getAndIncrement();
  }
});
System.out.println("Queries: " + queries.get()); // Prints 1

db.insert("users", createUser("jw", "Jake Wharton"));
db.insert("users", createUser("mattp", "Matt Precious"));
s.unsubscribe();

db.insert("users", createUser("strong", "Alec Strong"));

System.out.println("Queries: " + queries.get()); // Prints 3

Use transactions to prevent large changes to the data from spamming your subscribers.

通過使用事務(wù)可以將多個修改合并成一個更新來通知訂閱者

final AtomicInteger queries = new AtomicInteger();
users.subscribe(new Action1<Query>() {
  @Override public void call(Query query) {
    queries.getAndIncrement();
  }
});
System.out.println("Queries: " + queries.get()); // Prints 1

Transaction transaction = db.newTransaction();
try {
  db.insert("users", createUser("jw", "Jake Wharton"));
  db.insert("users", createUser("mattp", "Matt Precious"));
  db.insert("users", createUser("strong", "Alec Strong"));
  transaction.markSuccessful();
} finally {
  transaction.end();
}

System.out.println("Queries: " + queries.get()); // Prints 2

Note: You can also use try-with-resources with a Transaction instance.

Note: 你也可以使用try-with-resources來管理Transaction實例。
try-with-resources看這里

Since queries are just regular RxJava Observable objects, operators can also be used to
control the frequency of notifications to subscribers.

基于查詢返回值就是RxJava的Observable對象，訂閱者可以使用RxJava的操作符來控制頻繁的更新。

users.debounce(500, MILLISECONDS).subscribe(new Action1<Query>() {
  @Override public void call(Query query) {
    // TODO...
  }
});

The SqlBrite object can also wrap a ContentResolver for observing a query on another app's
content provider.

SqlBrite對象同樣可以包裝ContentResolver 來監(jiān)聽一個另外一個app的content provider。

BriteContentResolver resolver = sqlBrite.wrapContentProvider(contentResolver, Schedulers.io());
Observable<Query> query = resolver.createQuery(/*...*/);

The full power of RxJava's operators are available for combining, filtering, and triggering any
number of queries and data changes.

所有的RxJava操作符都可用來組合，過濾和觸發(fā)任意數(shù)量的查詢操作和數(shù)據(jù)改變。

Philosophy（思想）

SqlBrite's only responsibility is to be a mechanism for coordinating and composing the notification
of updates to tables such that you can update queries as soon as data changes.

SqlBrite是一種負責(zé) 協(xié)調(diào)和組織表更新通知 的機制，這樣你可以在數(shù)據(jù)改變的時候立即收到更新。

This library is not an ORM. It is not a type-safe query mechanism. It won't serialize the same POJOs
you use for Gson. It's not going to perform database migrations for you.

這個庫不是ORM。它不是一個類型安全的查詢機制。它不能將相同的POJO序列化為Gson 。它不能為你執(zhí)行數(shù)據(jù)庫遷移。

Some of these features are offered by SQLDelight which can be used with SQLBrite.

SQLDelight提供了上面的部分特性，并可以結(jié)合SQLBrite使用

Download

compile 'com.squareup.sqlbrite:sqlbrite:1.1.1'

Snapshots of the development version are available in [Sonatype's snapshots repository][snap].

正在開發(fā)中的快照版本看這里

License

Copyright 2015 Square, Inc.

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.