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.

Author: loganj

src/main/java/rx/Observable.java

@@ -3641,6 +3641,14 @@ public final Observable<T> cache() {
         return CachedObservable.from(this);
     }
 
+  /**
+   * @see #cacheWithCapacityHint(int)
+   * @deprecated Use {@link #cacheWithCapacityHint(int)} instead.
+   */
+  @Deprecated public final Observable<T> cache(int capacityHint) {
+        return cacheWithCapacityHint(capacityHint);
+    }
+
     /**
      * 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
@@ -3666,13 +3674,16 @@ 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)
      * @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) {
+    public final Observable<T> cacheWithCapacityHint(int capacityHint) {
         return CachedObservable.from(this, capacityHint);
     }
 

src/test/java/rx/ObservableTests.java

@@ -663,7 +663,7 @@ public void run() {
                     }
                 }).start();
             }
-        }).cache(1);
+        }).cacheWithCapacityHint(1);
 
         // we then expect the following 2 subscriptions to get that same value
         final CountDownLatch latch = new CountDownLatch(2);