Merge remote-tracking branch 'parent/master' into timestamp

Author: jmhofer

CHANGES.md

@@ -1,5 +1,12 @@
 # RxJava Releases #
 
+### Version 0.8.1 ([Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.netflix.rxjava%22%20AND%20v%3A%220.8.1%22)) ###
+
+* [Pull 250](https://github.com/Netflix/RxJava/pull/250) AsyncSubject
+* [Pull 252](https://github.com/Netflix/RxJava/pull/252) ToFuture
+* [Pull 246](https://github.com/Netflix/RxJava/pull/246) Scheduler.schedulePeriodically
+* [Pull 247](https://github.com/Netflix/RxJava/pull/247) flatMap aliased to mapMany
+
 ### Version 0.8.0 ([Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.netflix.rxjava%22%20AND%20v%3A%220.8.0%22)) ###
 
 This is a breaking (non-backwards compatible) release that updates the Scheduler implementation released in 0.7.0.

gradle.properties

@@ -1 +1 @@
-version=0.8.1-SNAPSHOT
+version=0.8.2-SNAPSHOT

rxjava-core/src/main/java/rx/Observable.java

@@ -42,9 +42,9 @@
 import rx.operators.OperationConcat;
 import rx.operators.OperationDefer;
 import rx.operators.OperationDematerialize;
-import rx.operators.OperationGroupBy;
 import rx.operators.OperationFilter;
 import rx.operators.OperationFinally;
+import rx.operators.OperationGroupBy;
 import rx.operators.OperationMap;
 import rx.operators.OperationMaterialize;
 import rx.operators.OperationMerge;
@@ -64,7 +64,7 @@
 import rx.operators.OperationTakeLast;
 import rx.operators.OperationTakeUntil;
 import rx.operators.OperationTakeWhile;
-import rx.operators.OperationTimestamp;
+import rx.operators.OperationToFuture;
 import rx.operators.OperationToIterator;
 import rx.operators.OperationToObservableFuture;
 import rx.operators.OperationToObservableIterable;
@@ -617,9 +617,11 @@ public void call(Object args) {
 
     /**
      * Returns a connectable observable sequence that upon connection causes the source sequence to push results into the specified subject.
-     *
-     * @param subject the subject to push source elements into.
-     * @param <R> result type
+     * 
+     * @param subject
+     *            the subject to push source elements into.
+     * @param <R>
+     *            result type
      * @return a connectable observable sequence that upon connection causes the source sequence to push results into the specified subject.
      */
     public <R> ConnectableObservable<R> multicast(Subject<T, R> subject) {
@@ -1199,6 +1201,8 @@ public R call(T t1) {
      * and then merges the results of that function applied to every item emitted by the original
      * Observable, emitting these merged results as its own sequence.
      * <p>
+     * Note: mapMany and flatMap are equivalent.
+     * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/mapMany.png">
      * 
      * @param sequence
@@ -1213,6 +1217,7 @@ public R call(T t1) {
      * @return an Observable that emits a sequence that is the result of applying the transformation
      *         function to each item emitted by the source Observable and merging the results of
      *         the Observables obtained from this transformation
+     * @see {@link #flatMap(Observable, Func1)}
      */
     public static <T, R> Observable<R> mapMany(Observable<T> sequence, Func1<T, Observable<R>> func) {
         return create(OperationMap.mapMany(sequence, func));
@@ -1378,6 +1383,62 @@ public static <T> Observable<T> finallyDo(Observable<T> source, Action0 action)
         return create(OperationFinally.finallyDo(source, action));
     }
 
+    /**
+     * Creates a new Observable sequence by applying a function that you supply to each object in the
+     * original Observable sequence, where that function is itself an Observable that emits objects,
+     * and then merges the results of that function applied to every item emitted by the original
+     * Observable, emitting these merged results as its own sequence.
+     * <p>
+     * Note: mapMany and flatMap are equivalent.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/mapMany.png">
+     * 
+     * @param sequence
+     *            the source Observable
+     * @param func
+     *            a function to apply to each item emitted by the source Observable, generating a
+     *            Observable
+     * @param <T>
+     *            the type emitted by the source Observable
+     * @param <R>
+     *            the type emitted by the Observables emitted by <code>func</code>
+     * @return an Observable that emits a sequence that is the result of applying the transformation
+     *         function to each item emitted by the source Observable and merging the results of
+     *         the Observables obtained from this transformation
+     * @see {@link #mapMany(Observable, Func1)}
+     */
+    public static <T, R> Observable<R> flatMap(Observable<T> sequence, Func1<T, Observable<R>> func) {
+        return mapMany(sequence, func);
+    }
+
+    /**
+     * Creates a new Observable sequence by applying a function that you supply to each object in the
+     * original Observable sequence, where that function is itself an Observable that emits objects,
+     * and then merges the results of that function applied to every item emitted by the original
+     * Observable, emitting these merged results as its own sequence.
+     * <p>
+     * Note: mapMany and flatMap are equivalent.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/mapMany.png">
+     * 
+     * @param sequence
+     *            the source Observable
+     * @param func
+     *            a function to apply to each item emitted by the source Observable, generating a
+     *            Observable
+     * @param <T>
+     *            the type emitted by the source Observable
+     * @param <R>
+     *            the type emitted by the Observables emitted by <code>func</code>
+     * @return an Observable that emits a sequence that is the result of applying the transformation
+     *         function to each item emitted by the source Observable and merging the results of
+     *         the Observables obtained from this transformation
+     * @see {@link #mapMany(Observable, Func1)}
+     */
+    public static <T, R> Observable<R> flatMap(Observable<T> sequence, final Object func) {
+        return mapMany(sequence, func);
+    }
+
     /**
      * Groups the elements of an observable and selects the resulting elements by using a specified function.
      * 
@@ -2032,6 +2093,19 @@ public Boolean call(T t, Integer integer)
         }));
     }
 
+    /**
+     * Return a Future representing a single value of the Observable.
+     * <p>
+     * This will throw an exception if the Observable emits more than 1 value. If more than 1 are expected then use <code>toList().toFuture()</code>.
+     * 
+     * @param that
+     *            the source Observable
+     * @returna Future that expects a single item emitted by the source Observable
+     */
+    public static <T> Future<T> toFuture(final Observable<T> that) {
+        return OperationToFuture.toFuture(that);
+    }
+
     /**
      * Returns an Observable that emits a single item, a list composed of all the items emitted by
      * the source Observable.
@@ -2115,11 +2189,15 @@ public static <T> Iterable<T> mostRecent(Observable<T> source, T initialValue) {
 
     /**
      * Returns a connectable observable sequence that upon connection causes the source sequence to push results into the specified subject.
-     *
-     * @param source the source sequence whose elements will be pushed into the specified subject.
-     * @param subject the subject to push source elements into.
-     * @param <T> source type
-     * @param <R> result type
+     * 
+     * @param source
+     *            the source sequence whose elements will be pushed into the specified subject.
+     * @param subject
+     *            the subject to push source elements into.
+     * @param <T>
+     *            source type
+     * @param <R>
+     *            result type
      * @return a connectable observable sequence that upon connection causes the source sequence to push results into the specified subject.
      */
     public static <T, R> ConnectableObservable<R> multicast(Observable<T> source, final Subject<T, R> subject) {
@@ -2128,7 +2206,7 @@ public static <T, R> ConnectableObservable<R> multicast(Observable<T> source, fi
 
     /**
      * Returns the only element of an observable sequence and throws an exception if there is not exactly one element in the observable sequence.
-     *
+     * 
      * @param that
      *            the source Observable
      * @return The single element in the observable sequence.
@@ -2698,6 +2776,48 @@ public Boolean call(T t1) {
         });
     }
 
+    /**
+     * Creates a new Observable sequence by applying a function that you supply to each item in the
+     * original Observable sequence, where that function is itself an Observable that emits items, and
+     * then merges the results of that function applied to every item emitted by the original
+     * Observable, emitting these merged results as its own sequence.
+     * <p>
+     * Note: mapMany and flatMap are equivalent.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/mapMany.png">
+     * 
+     * @param func
+     *            a function to apply to each item in the sequence, that returns an Observable.
+     * @return an Observable that emits a sequence that is the result of applying the transformation
+     *         function to each item in the input sequence and merging the results of the
+     *         Observables obtained from this transformation.
+     * @see {@link #mapMany(Func1)}
+     */
+    public <R> Observable<R> flatMap(Func1<T, Observable<R>> func) {
+        return mapMany(func);
+    }
+
+    /**
+     * Creates a new Observable sequence by applying a function that you supply to each item in the
+     * original Observable sequence, where that function is itself an Observable that emits items, and
+     * then merges the results of that function applied to every item emitted by the original
+     * Observable, emitting these merged results as its own sequence.
+     * <p>
+     * Note: mapMany and flatMap are equivalent.
+     * <p>
+     * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/mapMany.png">
+     * 
+     * @param callback
+     *            a function to apply to each item in the sequence that returns an Observable.
+     * @return an Observable that emits a sequence that is the result of applying the transformation'
+     *         function to each item in the input sequence and merging the results of the
+     *         Observables obtained from this transformation.
+     * @see {@link #mapMany(Object)}
+     */
+    public <R> Observable<R> flatMap(final Object callback) {
+        return mapMany(callback);
+    }
+
     /**
      * Filters an Observable by discarding any of its emissions that do not meet some test.
      * <p>
@@ -2834,13 +2954,16 @@ public R call(T t1) {
      * then merges the results of that function applied to every item emitted by the original
      * Observable, emitting these merged results as its own sequence.
      * <p>
+     * Note: mapMany and flatMap are equivalent.
+     * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/mapMany.png">
      * 
      * @param func
      *            a function to apply to each item in the sequence, that returns an Observable.
      * @return an Observable that emits a sequence that is the result of applying the transformation
      *         function to each item in the input sequence and merging the results of the
      *         Observables obtained from this transformation.
+     * @see {@link #flatMap(Func1)}
      */
     public <R> Observable<R> mapMany(Func1<T, Observable<R>> func) {
         return mapMany(this, func);
@@ -2852,13 +2975,16 @@ public <R> Observable<R> mapMany(Func1<T, Observable<R>> func) {
      * then merges the results of that function applied to every item emitted by the original
      * Observable, emitting these merged results as its own sequence.
      * <p>
+     * Note: mapMany and flatMap are equivalent.
+     * <p>
      * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/mapMany.png">
      * 
      * @param callback
      *            a function to apply to each item in the sequence that returns an Observable.
      * @return an Observable that emits a sequence that is the result of applying the transformation'
      *         function to each item in the input sequence and merging the results of the
      *         Observables obtained from this transformation.
+     * @see {@link #flatMap(Object))}
      */
     public <R> Observable<R> mapMany(final Object callback) {
         @SuppressWarnings("rawtypes")
@@ -3393,11 +3519,14 @@ public <E> Observable<T> takeUntil(Observable<E> other) {
     }
 
     /**
-     * Adds a timestamp to each item emitted by this observable.
-     * @return An observable sequence of timestamped items.
+     * Return a Future representing a single value of the Observable.
+     * <p>
+     * This will throw an exception if the Observable emits more than 1 value. If more than 1 are expected then use <code>toList().toFuture()</code>.
+     * 
+     * @returna Future that expects a single item emitted by the source Observable
      */
-    public Observable<Timestamped<T>> timestamp() {
-        return create(OperationTimestamp.timestamp(this));
+    public Future<T> toFuture() {
+        return toFuture(this);
     }
 
     /**