SQLBrite官翻

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

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

对SQLiteOpenHelper 和 ContentResolver的一个轻量级包装工具，并对查询引入了响应式流语法

Usage(用法)

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

创建一个SqlBrite实例，它是库功能的适配器。

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

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

传入一个SQLiteOpenHelper实例和一个Scheduler 实例来创建 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是必须的，最主要的原因是查询操作会在你选择的线程上触发通知。这个查询过程可以不阻塞主线程的或发起查询操作的线程。

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但它需要一个额外的表名参数，并会监听这个（些）表的改变。订阅Observable<Query>（方法的返回值）将会立即触发一个 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.

不同于传统的rawQuery， 只要你还持有方法返回值的订阅那么对这个表的更改都会触发额外的通知。这意味着你的插入，更新，或删除数据都会立刻触发订阅的更新。

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.

调用返回值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.

通过使用事务可以将多个修改合并成一个更新来通知订阅者

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 来监听一个另外一个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操作符都可用来组合，过滤和触发任意数量的查询操作和数据改变。

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是一种负责 协调和组织表更新通知 的机制，这样你可以在数据改变的时候立即收到更新。

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 。它不能为你执行数据库迁移。

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

SQLDelight提供了上面的部分特性，并可以结合SQLBrite使用

Download

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

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

正在开发中的快照版本看这里

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.