MERGE PREP: Renamed "ResourceProvider" to "ResourceSet".

"Cherry-picked" (manually) from branch "redesign" (the first such branch).

Author: rickbw

README.md

@@ -12,13 +12,13 @@ The Crud API supports data-oriented interactions based on generic _Resources_, w
 
 API Overview
 ------------
-There are two primary abstractions in the API: `Resources` and `ResourceProviders`. The former encapsulate the I/O operations on state, and hence uses a reactive style. There are two interfaces derived from [Resource](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/Resource.java):
+There are two primary abstractions in the API: `Resources` and `ResourceSets`. The former encapsulate the I/O operations on state, and hence uses a reactive style. There are two interfaces derived from [Resource](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/Resource.java):
 * [ReadableResource](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/ReadableResource.java)
 * [WritableResource](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/WritableResource.java)
 
-The latter abstraction, `ResourceProvider`, provides local (i.e. assumed-cheap) navigation among `Resources`. This navigation uses a key-value lookup idiom, where keys are generic and may be simple—e.g. a URL—or arbitrarily complex—e.g. a database query—depending on the underlying data-access technology. There are two derived [ResourceProvider](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/ResourceProvider.java) interfaces:
-* [ReadableResourceProvider](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/ReadableResourceProvider.java)
-* [WritableResourceProvider](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/WritableResourceProvider.java)
+The latter abstraction, `ResourceSet`, provides local (i.e. assumed-cheap) navigation among `Resources`. This navigation uses a key-value lookup idiom, where keys are generic and may be simple—e.g. a URL—or arbitrarily complex—e.g. a database query—depending on the underlying data-access technology. There are two derived [ResourceSet](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/ResourceSet.java) interfaces:
+* [ReadableResourceSet](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/ReadableResourceSet.java)
+* [WritableResourceSet](https://github.com/rickbw/crud-api/blob/master/src/main/java/rickbw/crud/core/WritableResourceSet.java)
 
 
 See Also

src/main/java/crud/core/ReadableResource.java

@@ -27,7 +27,7 @@
  * @param <RSRC>    The type of the resource's value(s).
  *
  * @see WritableResource
- * @see ReadableResourceProvider
+ * @see ReadableResourceSet
  */
 public interface ReadableResource<RSRC> extends Resource {
 

src/main/java/crud/core/ReadableResourceProvider.java renamed to src/main/java/crud/core/ReadableResourceSet.java

@@ -18,10 +18,10 @@
 /**
  * Look up a {@link ReadableResource} based on a given key.
  *
- * @see WritableResourceProvider
+ * @see WritableResourceSet
  * @see ReadableResource
  */
-public interface ReadableResourceProvider<KEY, RSRC> extends ResourceProvider<KEY> {
+public interface ReadableResourceSet<KEY, RSRC> extends ResourceSet<KEY> {
 
     @Override
     public abstract ReadableResource<RSRC> get(KEY key);

src/main/java/crud/core/ResourceProvider.java renamed to src/main/java/crud/core/ResourceSet.java

@@ -1,4 +1,4 @@
-/* Copyright 2013–2014 Rick Warren
+/* Copyright 2013–2015 Rick Warren
  *
  * 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
@@ -21,10 +21,10 @@
  * return resources that implement multiple interfaces (e.g. that are both a
  * {@link ReadableResource} and a {@link WritableResource}) can extend
  * multiple sub-interfaces of this interface (e.g. both
- * {@link ReadableResourceProvider} and {@link WritableResourceProvider}) by
+ * {@link ReadableResourceSet} and {@link WritableResourceSet}) by
  * overriding the return type of {@link #get(Object)}.
  */
-public interface ResourceProvider<KEY> {
+public interface ResourceSet<KEY> {
 
     /**
      * Get the {@link Resource} associated with the given key. Resources
@@ -36,7 +36,7 @@ public interface ResourceProvider<KEY> {
      * Specifically, when dealing with remote and/or persistent Resources,
      * implementers should locate expensive operations -- such as transferring
      * data across a network -- within the Resource implementations
-     * themselves, and leave the ResourceProviders to simply prepare the
+     * themselves, and leave the ResourceSets to simply prepare the
      * necessary objects.
      *
      * @throws NullPointerException if the given key is null.

src/main/java/crud/core/WritableResource.java

@@ -25,7 +25,7 @@
  *        a result of the change in the value.
  *
  * @see ReadableResource
- * @see WritableResourceProvider
+ * @see WritableResourceSet
  */
 public interface WritableResource<RSRC, RESPONSE> extends Resource {
 

src/main/java/crud/core/WritableResourceProvider.java renamed to src/main/java/crud/core/WritableResourceSet.java

@@ -18,10 +18,10 @@
 /**
  * Look up a {@link WritableResource} based on a given key.
  *
- * @see ReadableResourceProvider
+ * @see ReadableResourceSet
  * @see WritableResource
  */
-public interface WritableResourceProvider<KEY, RSRC, RESPONSE> extends ResourceProvider<KEY> {
+public interface WritableResourceSet<KEY, RSRC, RESPONSE> extends ResourceSet<KEY> {
 
     @Override
     public abstract WritableResource<RSRC, RESPONSE> get(KEY key);

src/main/java/crud/core/package-info.java

@@ -26,23 +26,23 @@
  *
  * There are two primary abstractions in the API:
  * {@link crud.core.Resource}s and
- * {@link crud.core.ResourceProvider}s. The former encapsulates the
+ * {@link crud.core.ResourceSet}s. The former encapsulates the
  * I/O operations on state, and hence uses a reactive style. There are two
  * derived interfaces:
  * <ul>
  *  <li>{@link crud.core.ReadableResource}</li>
  *  <li>{@link crud.core.WritableResource}</li>
  * </ul>
  *
- * The latter abstraction, the resource providers, provide local (i.e.
+ * The latter abstraction, the resource sets, provide local (i.e.
  * assumed-cheap) navigation among Resources. This navigation uses a key-value
  * lookup idiom, where keys are generic and may be simple -- e.g. a URL -- or
  * arbitrarily complex -- e.g. a database query -- depending on the underlying
  * data-access technology. There are two derived
- * {@link crud.core.ResourceProvider} interfaces:
+ * {@link crud.core.ResourceSet} interfaces:
  * <ul>
- *  <li>{@link crud.core.ReadableResourceProvider}</li>
- *  <li>{@link crud.core.WritableResourceProvider}</li>
+ *  <li>{@link crud.core.ReadableResourceSet}</li>
+ *  <li>{@link crud.core.WritableResourceSet}</li>
  * </ul>
  *
  * In addition to these core abstractions, this library provides a number of

src/main/java/crud/file/TextLineFileResource.java

@@ -25,9 +25,9 @@
 import com.google.common.annotations.VisibleForTesting;
 
 import crud.core.ReadableResource;
-import crud.core.ReadableResourceProvider;
+import crud.core.ReadableResourceSet;
 import crud.core.WritableResource;
-import crud.core.WritableResourceProvider;
+import crud.core.WritableResourceSet;
 import crud.util.BooleanSubscription;
 import rx.Observable;
 import rx.Observable.OnSubscribe;
@@ -43,8 +43,8 @@ public class TextLineFileResource
     private final File file;
 
 
-    public static Provider provider() {
-        return new Provider();
+    public static Set set() {
+        return new Set();
     }
 
     @Override
@@ -95,14 +95,14 @@ public int hashCode() {
     }
 
 
-    public static class Provider
-    implements ReadableResourceProvider<File, String>, WritableResourceProvider<File, String, Void> {
+    public static class Set
+    implements ReadableResourceSet<File, String>, WritableResourceSet<File, String, Void> {
         @Override
         public TextLineFileResource get(final File file) {
             return new TextLineFileResource(file);
         }
 
-        private Provider() {
+        private Set() {
             // instantiation via factory method only
         }
     }

src/main/java/crud/fluent/DelegateObjectMethods.java

@@ -1,4 +1,4 @@
-/* Copyright 2014 Rick Warren
+/* Copyright 2014–2015 Rick Warren
  *
  * 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
@@ -17,15 +17,14 @@
 import java.util.Objects;
 
 import crud.core.Resource;
-import crud.core.ResourceProvider;
-
+import crud.core.ResourceSet;
 import rx.functions.Func0;
 import rx.functions.Func1;
 
 
 /**
  * A base class for {@link rx.functions.Function} facades around
- * {@link Resource}s and {@link ResourceProvider}s. It delegates the common
+ * {@link Resource}s and {@link ResourceSet}s. It delegates the common
  * {@link Object} methods {@link #toString()}, {@link #equals(Object)}, and
  * {@link #hashCode()} to its delegate. Its concrete subclasses
  * {@link Function} and {@link Callable} pull in {@code call} methods.

src/main/java/crud/fluent/FluentReadableResourceProvider.java renamed to src/main/java/crud/fluent/FluentReadableResourceSet.java

@@ -1,4 +1,4 @@
-/* Copyright 2013–2014 Rick Warren
+/* Copyright 2013–2015 Rick Warren
  *
  * 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
@@ -17,74 +17,73 @@
 import java.util.Objects;
 
 import crud.core.ReadableResource;
-import crud.core.ReadableResourceProvider;
-
+import crud.core.ReadableResourceSet;
 import rx.Observable;
 import rx.Observer;
 import rx.functions.Func1;
 
 
-public abstract class FluentReadableResourceProvider<KEY, RSRC>
-implements ReadableResourceProvider<KEY, RSRC> {
+public abstract class FluentReadableResourceSet<KEY, RSRC>
+implements ReadableResourceSet<KEY, RSRC> {
 
-    public static <KEY, RSRC> FluentReadableResourceProvider<KEY, RSRC> from(
-            final ReadableResourceProvider<KEY, RSRC> provider) {
-        if (provider instanceof FluentReadableResourceProvider<?, ?>) {
-            return (FluentReadableResourceProvider<KEY, RSRC>) provider;
+    public static <KEY, RSRC> FluentReadableResourceSet<KEY, RSRC> from(
+            final ReadableResourceSet<KEY, RSRC> rsrcSet) {
+        if (rsrcSet instanceof FluentReadableResourceSet<?, ?>) {
+            return (FluentReadableResourceSet<KEY, RSRC>) rsrcSet;
         } else {
-            return new FluentReadableResourceProvider<KEY, RSRC>() {
+            return new FluentReadableResourceSet<KEY, RSRC>() {
                 @Override
                 public FluentReadableResource<RSRC> get(final KEY key) {
-                    return FluentReadableResource.from(provider.get(key));
+                    return FluentReadableResource.from(rsrcSet.get(key));
                 }
             };
         }
     }
 
-    public <R> FluentReadableResourceProvider<KEY, R> mapValue(
+    public <R> FluentReadableResourceSet<KEY, R> mapValue(
             final Func1<? super RSRC, ? extends R> mapper) {
         Objects.requireNonNull(mapper, "null function");
-        final FluentReadableResourceProvider<KEY, R> result = new FluentReadableResourceProvider<KEY, R>() {
+        final FluentReadableResourceSet<KEY, R> result = new FluentReadableResourceSet<KEY, R>() {
             @Override
             public FluentReadableResource<R> get(final KEY key) {
-                return outerProvider()
+                return outerResourceSet()
                         .get(key)
                         .mapValue(mapper);
             }
         };
         return result;
     }
 
-    public <R> FluentReadableResourceProvider<KEY, R> flatMapValue(
+    public <R> FluentReadableResourceSet<KEY, R> flatMapValue(
             final Func1<? super RSRC, ? extends Observable<? extends R>> mapper) {
         Objects.requireNonNull(mapper, "null function");
-        final FluentReadableResourceProvider<KEY, R> result = new FluentReadableResourceProvider<KEY, R>() {
+        final FluentReadableResourceSet<KEY, R> result = new FluentReadableResourceSet<KEY, R>() {
             @Override
             public FluentReadableResource<R> get(final KEY key) {
-                return outerProvider()
+                return outerResourceSet()
                         .get(key)
                         .flatMapValue(mapper);
             }
         };
         return result;
     }
 
-    public <K> FluentReadableResourceProvider<K, RSRC> adaptKey(
+    public <K> FluentReadableResourceSet<K, RSRC> adaptKey(
             final Func1<? super K, ? extends KEY> adapter) {
         Objects.requireNonNull(adapter, "null function");
-        final FluentReadableResourceProvider<K, RSRC> result = new FluentReadableResourceProvider<K, RSRC>() {
+        final FluentReadableResourceSet<K, RSRC> result = new FluentReadableResourceSet<K, RSRC>() {
             @Override
             public FluentReadableResource<RSRC> get(final K key) {
                 Objects.requireNonNull(key, "null key");
                 final KEY transformedKey = adapter.call(key);
-                return outerProvider().get(transformedKey);
+                return outerResourceSet().get(transformedKey);
             }
         };
         return result;
     }
 
     /**
-     * Return a resource provider, the resource from which will transparently
+     * Return a resource set, the resource from which will transparently
      * retry calls to {@link ReadableResource#read()} that throw, as with
      * {@link Observable#retry(long)}. Specifically, any {@link Observable}
      * returned by {@link ReadableResource#read()} will re-subscribe up to
@@ -100,29 +99,29 @@ public FluentReadableResource<RSRC> get(final K key) {
      *
      * @param maxRetries    number of retry attempts before failing
      */
-    public FluentReadableResourceProvider<KEY, RSRC> retry(final int maxRetries) {
+    public FluentReadableResourceSet<KEY, RSRC> retry(final int maxRetries) {
         if (maxRetries == 0) {
             return this;    // no-op
         } else if (maxRetries < 0) {
             throw new IllegalArgumentException("maxRetries " + maxRetries + " < 0");
         } else {
-            return new FluentReadableResourceProvider<KEY, RSRC>() {
+            return new FluentReadableResourceSet<KEY, RSRC>() {
                 @Override
                 public FluentReadableResource<RSRC> get(final KEY key) {
-                    return outerProvider()
+                    return outerResourceSet()
                             .get(key)
                             .retry(maxRetries);
                 }
             };
         }
     }
 
-    public <TO> FluentReadableResourceProvider<KEY, TO> lift(final Observable.Operator<TO, RSRC> bind) {
+    public <TO> FluentReadableResourceSet<KEY, TO> lift(final Observable.Operator<TO, RSRC> bind) {
         Objects.requireNonNull(bind, "null operator");
-        return new FluentReadableResourceProvider<KEY, TO>() {
+        return new FluentReadableResourceSet<KEY, TO>() {
             @Override
             public FluentReadableResource<TO> get(final KEY key) {
-                return outerProvider()
+                return outerResourceSet()
                         .get(key)
                         .lift(bind);
             }
@@ -141,7 +140,7 @@ public FluentReadableResource<RSRC> call(final KEY key) {
     @Override
     public abstract FluentReadableResource<RSRC> get(KEY key);
 
-    private FluentReadableResourceProvider<KEY, RSRC> outerProvider() {
+    private FluentReadableResourceSet<KEY, RSRC> outerResourceSet() {
         return this;
     }