Add the concept of Set-components and dependencies. (#169)

* Add the contept of Set-components and dependencies.

Set-components are components of type T that contribute values into a
larger Set<T> rather than registering one unique T value whose
uniqueness is enforced at runtime.

* Add license to source file.

* Update consumer proguard config.

Author: vkryachko

firebase-common/proguard.txt

@@ -1 +1,2 @@
--dontwarn com.google.firebase.components.Component$Instantiation
+-dontwarn com.google.firebase.components.Component$Instantiation
+-dontwarn com.google.firebase.components.Component$ComponentType

firebase-common/src/main/java/com/google/firebase/components/Component.java

@@ -36,29 +36,67 @@
 @KeepForSdk
 public final class Component<T> {
 
+  /** Specifies instantiation behavior of a {@link Component}. */
   @IntDef({Instantiation.LAZY, Instantiation.ALWAYS_EAGER, Instantiation.EAGER_IN_DEFAULT_APP})
   @Retention(RetentionPolicy.SOURCE)
   private @interface Instantiation {
+    /** Component is not instantiated until requested by developer or a dependent component. */
     int LAZY = 0;
+
+    /**
+     * Component is unconditionally instantiated upon startup of the {@link ComponentRuntime}.
+     *
+     * <p>Namely when {@link ComponentRuntime#initializeEagerComponents(boolean)} is called.
+     */
     int ALWAYS_EAGER = 1;
+
+    /**
+     * Component is instantiated upon startup of the {@link ComponentRuntime} if the runtime is
+     * initialized for the default app.
+     */
     int EAGER_IN_DEFAULT_APP = 2;
   }
 
+  /** Specifies the type of a {@link Component}. */
+  @IntDef({ComponentType.VALUE, ComponentType.SET})
+  @Retention(RetentionPolicy.SOURCE)
+  private @interface ComponentType {
+    /**
+     * Value components provide scalar values to the {@link ComponentRuntime}.
+     *
+     * <p>Such components can be requested by dependents via {@link ComponentContainer#get(Class)}
+     * or {@link ComponentContainer#getProvider(Class)}. e.g. {@code FirebaseInstanceId}.
+     */
+    int VALUE = 0;
+
+    /**
+     * Set components collectively contribute values of type {@code T} to a {@link Set
+     * Set&lt;T&gt;}.
+     *
+     * <p>Such components can be requested by dependents via {@link ComponentContainer#setOf(Class)}
+     * or {@link ComponentContainer#setOfProvider(Class)}.
+     */
+    int SET = 1;
+  }
+
   private final Set<Class<? super T>> providedInterfaces;
   private final Set<Dependency> dependencies;
   private final @Instantiation int instantiation;
+  private final @ComponentType int type;
   private final ComponentFactory<T> factory;
   private final Set<Class<?>> publishedEvents;
 
   private Component(
       Set<Class<? super T>> providedInterfaces,
       Set<Dependency> dependencies,
       @Instantiation int instantiation,
+      @ComponentType int type,
       ComponentFactory<T> factory,
       Set<Class<?>> publishedEvents) {
     this.providedInterfaces = Collections.unmodifiableSet(providedInterfaces);
     this.dependencies = Collections.unmodifiableSet(dependencies);
     this.instantiation = instantiation;
+    this.type = type;
     this.factory = factory;
     this.publishedEvents = Collections.unmodifiableSet(publishedEvents);
   }
@@ -113,30 +151,38 @@ public boolean isEagerInDefaultApp() {
     return instantiation == Instantiation.EAGER_IN_DEFAULT_APP;
   }
 
+  /** Returns whether a component is a Value Component or a Set Component. */
+  public boolean isValue() {
+    return type == ComponentType.VALUE;
+  }
+
   @Override
   public String toString() {
     StringBuilder sb =
         new StringBuilder("Component<")
             .append(Arrays.toString(providedInterfaces.toArray()))
             .append(">{")
             .append(instantiation)
+            .append(", type=")
+            .append(type)
             .append(", deps=")
             .append(Arrays.toString(dependencies.toArray()))
             .append("}");
     return sb.toString();
   }
 
-  @KeepForSdk
   /** Returns a Component<T> builder. */
+  @KeepForSdk
   public static <T> Component.Builder<T> builder(Class<T> anInterface) {
-    return new Builder<T>(anInterface);
+    return new Builder<>(anInterface);
   }
 
-  @KeepForSdk
   /** Returns a Component<T> builder. */
+  @KeepForSdk
+  @SafeVarargs
   public static <T> Component.Builder<T> builder(
       Class<T> anInterface, Class<? super T>... additionalInterfaces) {
-    return new Builder<T>(anInterface, additionalInterfaces);
+    return new Builder<>(anInterface, additionalInterfaces);
   }
 
   /**
@@ -151,22 +197,46 @@ public static <T> Component<T> of(Class<T> anInterface, T value) {
   }
 
   /** Wraps a value in a {@link Component} with no dependencies. */
-  @SafeVarargs
   @KeepForSdk
+  @SafeVarargs
   public static <T> Component<T> of(
       T value, Class<T> anInterface, Class<? super T>... additionalInterfaces) {
     return builder(anInterface, additionalInterfaces).factory((args) -> value).build();
   }
 
+  /**
+   * Provides a builder for a {@link Set}-multibinding {@link Component}.
+   *
+   * <p>Such components can be requested by dependents via {@link ComponentContainer#setOf(Class)} *
+   * or {@link ComponentContainer#setOfProvider(Class)}.
+   */
+  @KeepForSdk
+  public static <T> Component.Builder<T> intoSetBuilder(Class<T> anInterface) {
+    return builder(anInterface).intoSet();
+  }
+
+  /**
+   * Wraps a value in a {@link Set}-multibinding {@link Component} with no dependencies. *
+   *
+   * <p>Such components can be requested by dependents via {@link ComponentContainer#setOf(Class)} *
+   * or {@link ComponentContainer#setOfProvider(Class)}.
+   */
+  @KeepForSdk
+  public static <T> Component<T> intoSet(T value, Class<T> anInterface) {
+    return intoSetBuilder(anInterface).factory(c -> value).build();
+  }
+
   /** FirebaseComponent builder. */
   @KeepForSdk
   public static class Builder<T> {
     private final Set<Class<? super T>> providedInterfaces = new HashSet<>();
     private final Set<Dependency> dependencies = new HashSet<>();
     private @Instantiation int instantiation = Instantiation.LAZY;
+    private @ComponentType int type = ComponentType.VALUE;
     private ComponentFactory<T> factory;
     private Set<Class<?>> publishedEvents = new HashSet<>();
 
+    @SafeVarargs
     private Builder(Class<T> anInterface, Class<? super T>... additionalInterfaces) {
       Preconditions.checkNotNull(anInterface, "Null interface");
       providedInterfaces.add(anInterface);
@@ -176,6 +246,7 @@ private Builder(Class<T> anInterface, Class<? super T>... additionalInterfaces)
       Collections.addAll(providedInterfaces, additionalInterfaces);
     }
 
+    /** Add a {@link Dependency} to the {@link Component} being built. */
     @KeepForSdk
     public Builder<T> add(Dependency dependency) {
       Preconditions.checkNotNull(dependency, "Null dependency");
@@ -184,16 +255,19 @@ public Builder<T> add(Dependency dependency) {
       return this;
     }
 
+    /** Make the {@link Component} initialize upon startup. */
     @KeepForSdk
     public Builder<T> alwaysEager() {
       return setInstantiation(Instantiation.ALWAYS_EAGER);
     }
 
+    /** Make the component initialize upon startup in default app. */
     @KeepForSdk
     public Builder<T> eagerInDefaultApp() {
       return setInstantiation(Instantiation.EAGER_IN_DEFAULT_APP);
     }
 
+    /** Make the {@link Component} eligible to publish events of provided eventType. */
     @KeepForSdk
     public Builder<T> publishes(Class<?> eventType) {
       publishedEvents.add(eventType);
@@ -213,19 +287,27 @@ private void validateInterface(Class<?> anInterface) {
           "Components are not allowed to depend on interfaces they themselves provide.");
     }
 
+    /** Set the factory that will be used to initialize the {@link Component}. */
     @KeepForSdk
     public Builder<T> factory(ComponentFactory<T> value) {
       factory = Preconditions.checkNotNull(value, "Null factory");
       return this;
     }
 
+    private Builder<T> intoSet() {
+      type = ComponentType.SET;
+      return this;
+    }
+
+    /** Return the built {@link Component} definition. */
     @KeepForSdk
     public Component<T> build() {
       Preconditions.checkState(factory != null, "Missing required property: factory.");
       return new Component<>(
           new HashSet<>(providedInterfaces),
           new HashSet<>(dependencies),
           instantiation,
+          type,
           factory,
           publishedEvents);
     }

firebase-common/src/main/java/com/google/firebase/components/Dependency.java

@@ -24,11 +24,12 @@
 @KeepForSdk
 public final class Dependency {
   /** Enumerates dependency types. */
-  @IntDef({Type.OPTIONAL, Type.REQUIRED})
+  @IntDef({Type.OPTIONAL, Type.REQUIRED, Type.SET})
   @Retention(RetentionPolicy.SOURCE)
   private @interface Type {
     int OPTIONAL = 0;
     int REQUIRED = 1;
+    int SET = 2;
   }
 
   @IntDef({Injection.DIRECT, Injection.PROVIDER})
@@ -58,6 +59,11 @@ public static Dependency required(Class<?> anInterface) {
     return new Dependency(anInterface, Type.REQUIRED, Injection.DIRECT);
   }
 
+  @KeepForSdk
+  public static Dependency setOf(Class<?> anInterface) {
+    return new Dependency(anInterface, Type.SET, Injection.DIRECT);
+  }
+
   @KeepForSdk
   public static Dependency optionalProvider(Class<?> anInterface) {
     return new Dependency(anInterface, Type.OPTIONAL, Injection.PROVIDER);
@@ -68,6 +74,11 @@ public static Dependency requiredProvider(Class<?> anInterface) {
     return new Dependency(anInterface, Type.REQUIRED, Injection.PROVIDER);
   }
 
+  @KeepForSdk
+  public static Dependency setOfProvider(Class<?> anInterface) {
+    return new Dependency(anInterface, Type.SET, Injection.PROVIDER);
+  }
+
   public Class<?> getInterface() {
     return anInterface;
   }
@@ -76,6 +87,10 @@ public boolean isRequired() {
     return type == Type.REQUIRED;
   }
 
+  public boolean isSet() {
+    return type == Type.SET;
+  }
+
   public boolean isDirectInjection() {
     return injection == Injection.DIRECT;
   }
@@ -105,8 +120,8 @@ public String toString() {
     StringBuilder sb =
         new StringBuilder("Dependency{anInterface=")
             .append(anInterface)
-            .append(", required=")
-            .append(type == Type.REQUIRED)
+            .append(", type=")
+            .append(type == Type.REQUIRED ? "required" : type == Type.OPTIONAL ? "optional" : "set")
             .append(", direct=")
             .append(injection == Injection.DIRECT)
             .append("}");

firebase-common/src/test/java/com/google/firebase/components/ComponentTest.java

@@ -17,6 +17,7 @@
 import static com.google.common.truth.Truth.assertThat;
 import static org.junit.Assert.fail;
 
+import java.math.BigDecimal;
 import java.util.List;
 import org.junit.Test;
 import org.junit.runner.RunWith;
@@ -26,16 +27,55 @@
 public class ComponentTest {
   interface TestInterface {}
 
-  static class TestClass implements TestInterface {}
+  private static class TestClass implements TestInterface {}
 
   private final ComponentFactory<TestClass> nullFactory = container -> null;
 
+  @Test
+  public void of_withMultipleInterfaces_shouldSetCorrectDefaults() {
+    TestClass testClass = new TestClass();
+    Component<TestClass> component = Component.of(testClass, TestClass.class, TestInterface.class);
+    assertThat(component.getProvidedInterfaces())
+        .containsExactly(TestClass.class, TestInterface.class);
+    assertThat(component.isLazy()).isTrue();
+    assertThat(component.isValue()).isTrue();
+    assertThat(component.isAlwaysEager()).isFalse();
+    assertThat(component.isEagerInDefaultApp()).isFalse();
+    assertThat(component.getDependencies()).isEmpty();
+    assertThat(component.getFactory().create(null)).isSameAs(testClass);
+  }
+
   @Test
   public void builder_shouldSetCorrectDefaults() {
     Component<TestClass> component =
         Component.builder(TestClass.class).factory(nullFactory).build();
     assertThat(component.getProvidedInterfaces()).containsExactly(TestClass.class);
     assertThat(component.isLazy()).isTrue();
+    assertThat(component.isValue()).isTrue();
+    assertThat(component.isAlwaysEager()).isFalse();
+    assertThat(component.isEagerInDefaultApp()).isFalse();
+    assertThat(component.getDependencies()).isEmpty();
+  }
+
+  @Test
+  public void intoSetBuilder_shouldSetCorrectDefaults() {
+    Component<TestClass> component =
+        Component.intoSetBuilder(TestClass.class).factory(nullFactory).build();
+    assertThat(component.getProvidedInterfaces()).containsExactly(TestClass.class);
+    assertThat(component.isLazy()).isTrue();
+    assertThat(component.isValue()).isFalse();
+    assertThat(component.isAlwaysEager()).isFalse();
+    assertThat(component.isEagerInDefaultApp()).isFalse();
+    assertThat(component.getDependencies()).isEmpty();
+  }
+
+  @Test
+  public void intoSet_shouldSetCorrectDefaults() {
+    TestClass testClass = new TestClass();
+    Component<TestClass> component = Component.intoSet(testClass, TestClass.class);
+    assertThat(component.getProvidedInterfaces()).containsExactly(TestClass.class);
+    assertThat(component.isLazy()).isTrue();
+    assertThat(component.isValue()).isFalse();
     assertThat(component.isAlwaysEager()).isFalse();
     assertThat(component.isEagerInDefaultApp()).isFalse();
     assertThat(component.getDependencies()).isEmpty();
@@ -62,7 +102,7 @@ public void eagerInDefaultApp_shouldProperlySetComponentInitialization() {
   }
 
   @Test
-  public void uptatingInstantiationMultipleTimes_shouldThrow() {
+  public void updatingInstantiationMultipleTimes_shouldThrow() {
     Component.Builder<TestClass> builder = Component.builder(TestClass.class).eagerInDefaultApp();
 
     try {
@@ -79,18 +119,22 @@ public void add_shouldProperlyAddDependencies() {
         Component.builder(TestClass.class)
             .add(Dependency.required(List.class))
             .add(Dependency.optional(Integer.class))
+            .add(Dependency.setOf(Long.class))
             .add(Dependency.requiredProvider(Float.class))
             .add(Dependency.optionalProvider(Double.class))
+            .add(Dependency.setOfProvider(BigDecimal.class))
             .factory(nullFactory)
             .build();
 
-    assertThat(component.getDependencies()).hasSize(4);
+    assertThat(component.getDependencies()).hasSize(6);
     assertThat(component.getDependencies())
         .containsExactly(
             Dependency.required(List.class),
             Dependency.optional(Integer.class),
+            Dependency.setOf(Long.class),
             Dependency.requiredProvider(Float.class),
-            Dependency.optionalProvider(Double.class));
+            Dependency.optionalProvider(Double.class),
+            Dependency.setOfProvider(BigDecimal.class));
   }
 
   @Test
@@ -113,6 +157,18 @@ public void addOptionalDependency_onSelf_shouldThrow() {
     }
   }
 
+  @Test
+  public void publishes_shouldProperlyAddToPublishedEvents() {
+    Component<TestClass> component =
+        Component.builder(TestClass.class)
+            .factory(nullFactory)
+            .publishes(Integer.class)
+            .publishes(Float.class)
+            .build();
+
+    assertThat(component.getPublishedEvents()).containsExactly(Integer.class, Float.class);
+  }
+
   @Test
   public void builder_withMultipleInterfaces_shouldProperlySetInterfaces() {
     Component<TestClass> component =