Provide convenience operators for mapping to a single item.

JakeWharton · JakeWharton · commit db9ba634cd0f · 2015-09-02T01:29:24.000-04:00
Queries returning single items is very common. It's not too terrible to do this yourself with Query#asRows, but we can provide something even more readable at little inconvenience.
diff --git a/sqlbrite/src/androidTest/java/com/squareup/sqlbrite/BriteDatabaseTest.java b/sqlbrite/src/androidTest/java/com/squareup/sqlbrite/BriteDatabaseTest.java
@@ -34,10 +34,13 @@
 import java.util.concurrent.TimeUnit;
 import org.junit.After;
 import org.junit.Before;
+import org.junit.Ignore;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import rx.Observable;
 import rx.Subscription;
+import rx.functions.Func1;
+import rx.observables.BlockingObservable;
 
 import static android.database.sqlite.SQLiteDatabase.CONFLICT_IGNORE;
 import static com.google.common.truth.Truth.assertThat;
@@ -124,11 +127,134 @@ public final class BriteDatabaseTest {
         .toBlocking()
         .first();
     assertThat(employees).containsExactly( //
-        new Employee("alice", "Alice Allison"),
-        new Employee("bob", "Bob Bobberson"),
+        new Employee("alice", "Alice Allison"), //
+        new Employee("bob", "Bob Bobberson"), //
         new Employee("eve", "Eve Evenson"));
   }
 
+  @Test public void queryMapToListEmpty() {
+    List<Employee> employees = db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES + " WHERE 1=2")
+        .mapToList(Employee.MAPPER)
+        .toBlocking()
+        .first();
+    assertThat(employees).isEmpty();
+  }
+
+  @Test public void queryMapToListMapperReturnNullThrows() {
+    BlockingObservable<List<Employee>> employees =
+        db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES) //
+            .mapToList(new Func1<Cursor, Employee>() {
+              private int count;
+              @Override public Employee call(Cursor cursor) {
+                return count++ == 2 ? null : Employee.MAPPER.call(cursor);
+              }
+            }) //
+            .toBlocking();
+    try {
+      employees.first();
+    } catch (NullPointerException e) {
+      assertThat(e).hasMessage("Mapper returned null for row 3");
+      assertThat(e.getCause()).hasMessage(
+          "OnError while emitting onNext value: SELECT username, name FROM employee");
+    }
+  }
+
+  @Test public void queryMapToOne() {
+    Employee employees = db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES + " LIMIT 1")
+        .mapToOne(Employee.MAPPER)
+        .toBlocking()
+        .first();
+    assertThat(employees).isEqualTo(new Employee("alice", "Alice Allison"));
+  }
+
+  @Ignore("How to test in black box way? Can't take(1).mapToOne() to trigger complete.") // TODO
+  @Test public void queryMapToOneEmpty() {
+    db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES + " WHERE 1=2")
+        .mapToOne(Employee.MAPPER)
+        .toBlocking()
+        .first();
+  }
+
+  @Test public void queryMapToOneMapperReturnNullThrows() {
+    BlockingObservable<Employee> employees =
+        db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES) //
+            .mapToOne(new Func1<Cursor, Employee>() {
+              @Override public Employee call(Cursor cursor) {
+                return null;
+              }
+            }) //
+            .toBlocking();
+    try {
+      employees.first();
+    } catch (NullPointerException e) {
+      assertThat(e).hasMessage("Mapper returned null for row 1");
+      assertThat(e.getCause()).hasMessage(
+          "OnError while emitting onNext value: SELECT username, name FROM employee");
+    }
+  }
+
+  @Test public void queryMapToOneMultipleRowsThrows() {
+    BlockingObservable<Employee> employees =
+        db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES + " LIMIT 2") //
+            .mapToOne(Employee.MAPPER) //
+            .toBlocking();
+    try {
+      employees.first();
+    } catch (IllegalStateException e) {
+      assertThat(e).hasMessage("Cursor returned more than 1 row");
+      assertThat(e.getCause()).hasMessage(
+          "OnError while emitting onNext value: SELECT username, name FROM employee LIMIT 2");
+    }
+  }
+
+  @Test public void queryMapToOneOrNull() {
+    Employee employees = db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES + " LIMIT 1")
+        .mapToOneOrNull(Employee.MAPPER)
+        .toBlocking()
+        .first();
+    assertThat(employees).isEqualTo(new Employee("alice", "Alice Allison"));
+  }
+
+  @Test public void queryMapToOneOrNullEmpty() {
+    Employee employees = db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES + " WHERE 1=2")
+        .mapToOneOrNull(Employee.MAPPER)
+        .toBlocking()
+        .first();
+    assertThat(employees).isNull();
+  }
+
+  @Test public void queryMapToOneOrNullMapperReturnNullThrows() {
+    BlockingObservable<Employee> employees =
+        db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES) //
+            .mapToOneOrNull(new Func1<Cursor, Employee>() {
+              @Override public Employee call(Cursor cursor) {
+                return null;
+              }
+            }) //
+            .toBlocking();
+    try {
+      employees.first();
+    } catch (NullPointerException e) {
+      assertThat(e).hasMessage("Mapper returned null for row 1");
+      assertThat(e.getCause()).hasMessage(
+          "OnError while emitting onNext value: SELECT username, name FROM employee");
+    }
+  }
+
+  @Test public void queryMapToOneOrNullMultipleRowsThrows() {
+    BlockingObservable<Employee> employees =
+        db.createQuery(TABLE_EMPLOYEE, SELECT_EMPLOYEES + " LIMIT 2") //
+            .mapToOneOrNull(Employee.MAPPER) //
+            .toBlocking();
+    try {
+      employees.first();
+    } catch (IllegalStateException e) {
+      assertThat(e).hasMessage("Cursor returned more than 1 row");
+      assertThat(e.getCause()).hasMessage(
+          "OnError while emitting onNext value: SELECT username, name FROM employee LIMIT 2");
+    }
+  }
+
   @Test public void badQueryCallsError() {
     db.createQuery(TABLE_EMPLOYEE, "SELECT * FROM missing").subscribe(o);
     o.assertErrorContains("no such table: missing");
diff --git a/sqlbrite/src/main/java/com/squareup/sqlbrite/QueryObservable.java b/sqlbrite/src/main/java/com/squareup/sqlbrite/QueryObservable.java
@@ -4,12 +4,9 @@
 import android.support.annotation.CheckResult;
 import android.support.annotation.NonNull;
 import com.squareup.sqlbrite.SqlBrite.Query;
-import java.util.ArrayList;
 import java.util.List;
 import rx.Observable;
 import rx.Subscriber;
-import rx.exceptions.Exceptions;
-import rx.exceptions.OnErrorThrowable;
 import rx.functions.Func1;
 
 /** An {@link Observable} of {@link Query} which offers query-specific convenience operators. */
@@ -22,6 +19,46 @@ public final class QueryObservable extends Observable<Query> {
     });
   }
 
+  /**
+   * Given a function mapping the current row of a {@link Cursor} to {@code T}, transform each
+   * emitted {@link Query} which returns a single row to {@code T}.
+   * <p>
+   * It is an error for a query to pass through this operator with more than 1 row in its result
+   * set. Use {@code LIMIT 1} on the underlying SQL query to prevent this. Result sets with 0 rows
+   * do not emit an item.
+   * <p>
+   * This method is equivalent to:
+   * <pre>{@code
+   * flatMap(q -> q.asRows(mapper).take(1))
+   * }</pre>
+   *
+   * @param mapper Maps the current {@link Cursor} row to {@code T}. May not return null.
+   */
+  @CheckResult @NonNull
+  public final <T> Observable<T> mapToOne(@NonNull final Func1<Cursor, T> mapper) {
+    return lift(new QueryToOneOperator<>(mapper, false));
+  }
+
+  /**
+   * Given a function mapping the current row of a {@link Cursor} to {@code T}, transform each
+   * emitted {@link Query} which returns a single row to {@code T}.
+   * <p>
+   * It is an error for a query to pass through this operator with more than 1 row in its result
+   * set. Use {@code LIMIT 1} on the underlying SQL query to prevent this. Result sets with 0 rows
+   * emit {@code null}.
+   * <p>
+   * This method is equivalent to:
+   * <pre>{@code
+   * flatMap(q -> q.asRows(mapper).take(1).defaultIfEmpty(null))
+   * }</pre>
+   *
+   * @param mapper Maps the current {@link Cursor} row to {@code T}. May not return null.
+   */
+  @CheckResult @NonNull
+  public final <T> Observable<T> mapToOneOrNull(@NonNull final Func1<Cursor, T> mapper) {
+    return lift(new QueryToOneOperator<>(mapper, true));
+  }
+
   /**
    * Given a function mapping the current row of a {@link Cursor} to {@code T}, transform each
    * emitted {@link Query} to a {@code List<T>}.
@@ -32,45 +69,14 @@ public final class QueryObservable extends Observable<Query> {
    * <p>
    * This method is equivalent to:
    * <pre>{@code
-   * flatMap(q -> q.asRows(Item.MAPPER).toList())
+   * flatMap(q -> q.asRows(mapper).toList())
    * }</pre>
    * Consider using {@link Query#asRows} if you need to limit or filter in memory.
+   *
+   * @param mapper Maps the current {@link Cursor} row to {@code T}. May not return null.
    */
   @CheckResult @NonNull
   public final <T> Observable<List<T>> mapToList(@NonNull final Func1<Cursor, T> mapper) {
-    return lift(new Operator<List<T>, Query>() {
-      @Override
-      public Subscriber<? super Query> call(final Subscriber<? super List<T>> subscriber) {
-        return new Subscriber<Query>(subscriber) {
-          @Override public void onNext(Query query) {
-            try {
-              Cursor cursor = query.run();
-              List<T> items = new ArrayList<>(cursor.getCount());
-              try {
-                while (cursor.moveToNext() && !subscriber.isUnsubscribed()) {
-                  items.add(mapper.call(cursor));
-                }
-              } finally {
-                cursor.close();
-              }
-              if (!subscriber.isUnsubscribed()) {
-                subscriber.onNext(items);
-              }
-            } catch (Throwable e) {
-              Exceptions.throwIfFatal(e);
-              onError(OnErrorThrowable.addValueAsLastCause(e, query));
-            }
-          }
-
-          @Override public void onCompleted() {
-            subscriber.onCompleted();
-          }
-
-          @Override public void onError(Throwable e) {
-            subscriber.onError(e);
-          }
-        };
-      }
-    });
+    return lift(new QueryToListOperator<>(mapper));
   }
 }
diff --git a/sqlbrite/src/main/java/com/squareup/sqlbrite/QueryToListOperator.java b/sqlbrite/src/main/java/com/squareup/sqlbrite/QueryToListOperator.java
@@ -0,0 +1,55 @@
+package com.squareup.sqlbrite;
+
+import android.database.Cursor;
+import java.util.ArrayList;
+import java.util.List;
+import rx.Observable;
+import rx.Subscriber;
+import rx.exceptions.Exceptions;
+import rx.exceptions.OnErrorThrowable;
+import rx.functions.Func1;
+
+final class QueryToListOperator<T> implements Observable.Operator<List<T>, SqlBrite.Query> {
+  private final Func1<Cursor, T> mapper;
+
+  QueryToListOperator(Func1<Cursor, T> mapper) {
+    this.mapper = mapper;
+  }
+
+  @Override
+  public Subscriber<? super SqlBrite.Query> call(final Subscriber<? super List<T>> subscriber) {
+    return new Subscriber<SqlBrite.Query>(subscriber) {
+      @Override public void onNext(SqlBrite.Query query) {
+        try {
+          Cursor cursor = query.run();
+          List<T> items = new ArrayList<>(cursor.getCount());
+          try {
+            for (int i = 1; cursor.moveToNext() && !subscriber.isUnsubscribed(); i++) {
+              T item = mapper.call(cursor);
+              if (item == null) {
+                throw new NullPointerException("Mapper returned null for row " + i);
+              }
+              items.add(item);
+            }
+          } finally {
+            cursor.close();
+          }
+          if (!subscriber.isUnsubscribed()) {
+            subscriber.onNext(items);
+          }
+        } catch (Throwable e) {
+          Exceptions.throwIfFatal(e);
+          onError(OnErrorThrowable.addValueAsLastCause(e, query.toString()));
+        }
+      }
+
+      @Override public void onCompleted() {
+        subscriber.onCompleted();
+      }
+
+      @Override public void onError(Throwable e) {
+        subscriber.onError(e);
+      }
+    };
+  }
+}
diff --git a/sqlbrite/src/main/java/com/squareup/sqlbrite/QueryToOneOperator.java b/sqlbrite/src/main/java/com/squareup/sqlbrite/QueryToOneOperator.java
@@ -0,0 +1,56 @@
+package com.squareup.sqlbrite;
+
+import android.database.Cursor;
+import rx.Observable;
+import rx.Subscriber;
+import rx.exceptions.Exceptions;
+import rx.exceptions.OnErrorThrowable;
+import rx.functions.Func1;
+
+final class QueryToOneOperator<T> implements Observable.Operator<T, SqlBrite.Query> {
+  private final Func1<Cursor, T> mapper;
+  private final boolean emitNull;
+
+  QueryToOneOperator(Func1<Cursor, T> mapper, boolean emitNull) {
+    this.mapper = mapper;
+    this.emitNull = emitNull;
+  }
+
+  @Override public Subscriber<? super SqlBrite.Query> call(final Subscriber<? super T> subscriber) {
+    return new Subscriber<SqlBrite.Query>(subscriber) {
+      @Override public void onNext(SqlBrite.Query query) {
+        try {
+          T item = null;
+          Cursor cursor = query.run();
+          try {
+            if (cursor.moveToNext()) {
+              item = mapper.call(cursor);
+              if (item == null) {
+                throw new NullPointerException("Mapper returned null for row 1");
+              }
+              if (cursor.moveToNext()) {
+                throw new IllegalStateException("Cursor returned more than 1 row");
+              }
+            }
+          } finally {
+            cursor.close();
+          }
+          if (!subscriber.isUnsubscribed() && (item != null || emitNull)) {
+            subscriber.onNext(item);
+          }
+        } catch (Throwable e) {
+          Exceptions.throwIfFatal(e);
+          onError(OnErrorThrowable.addValueAsLastCause(e, query.toString()));
+        }
+      }
+
+      @Override public void onCompleted() {
+        subscriber.onCompleted();
+      }
+
+      @Override public void onError(Throwable e) {
+        subscriber.onError(e);
+      }
+    };
+  }
+}
