From bfe74125e90ae24e90c4e2cd7e5576cfbad49823 Mon Sep 17 00:00:00 2001
From: Logan Johnson <loganj@squareup.com>
Date: Fri, 6 Nov 2015 09:03:34 -0500
Subject: [PATCH] Rename cache(int) to cacheWithCapacityHint(int)

The parameter is a capacity hint, but more frequently confused with a
buffer size like replay(int) than it is correctly understood. It also
offers no guarantees, only the weak hope of optimization.

This change renames the method, deprecating the old name. It also adds
javadoc calling out that the parameter is not a bound and referencing
replay(int).autoConnect() as a way to achieve that behavior.
---
 src/main/java/rx/Observable.java      | 18 +++++++++++++++---
 src/test/java/rx/ObservableTests.java |  2 +-
 2 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/src/main/java/rx/Observable.java b/src/main/java/rx/Observable.java
index cb701d936d..71c8635bb0 100644
--- a/src/main/java/rx/Observable.java
+++ b/src/main/java/rx/Observable.java
@@ -3664,6 +3664,15 @@ public final Observable<T> cache() {
         return CachedObservable.from(this);
     }
 
+    /**
+     * @see #cacheWithInitialCapacity(int)
+     * @deprecated Use {@link #cacheWithInitialCapacity(int)} instead.
+     */
+    @Deprecated
+    public final Observable<T> cache(int initialCapacity) {
+        return cacheWithInitialCapacity(initialCapacity);
+    }
+
     /**
      * Caches emissions from the source Observable and replays them in order to any subsequent Subscribers.
      * This method has similar behavior to {@link #replay} except that this auto-subscribes to the source
@@ -3689,14 +3698,17 @@ public final Observable<T> cache() {
      *  <dt><b>Scheduler:</b></dt>
      *  <dd>{@code cache} does not operate by default on a particular {@link Scheduler}.</dd>
      * </dl>
+     * <p>
+     * <em>Note:</em> The capacity hint is not an upper bound on cache size. For that, consider
+     * {@link #replay(int)} in combination with {@link ConnectableObservable#autoConnect()} or similar.
      * 
-     * @param capacityHint hint for number of items to cache (for optimizing underlying data structure)
+     * @param initialCapacity hint for number of items to cache (for optimizing underlying data structure)
      * @return an Observable that, when first subscribed to, caches all of its items and notifications for the
      *         benefit of subsequent subscribers
      * @see <a href="http://reactivex.io/documentation/operators/replay.html">ReactiveX operators documentation: Replay</a>
      */
-    public final Observable<T> cache(int capacityHint) {
-        return CachedObservable.from(this, capacityHint);
+    public final Observable<T> cacheWithInitialCapacity(int initialCapacity) {
+        return CachedObservable.from(this, initialCapacity);
     }
 
     /**
diff --git a/src/test/java/rx/ObservableTests.java b/src/test/java/rx/ObservableTests.java
index d59e8c41a9..2d6598132b 100644
--- a/src/test/java/rx/ObservableTests.java
+++ b/src/test/java/rx/ObservableTests.java
@@ -663,7 +663,7 @@ public void run() {
                     }
                 }).start();
             }
-        }).cache(1);
+        }).cacheWithInitialCapacity(1);
 
         // we then expect the following 2 subscriptions to get that same value
         final CountDownLatch latch = new CountDownLatch(2);