Slight naming cleanup for Binding API, and a bit of Javadoc. More to follow . . .
git-svn-id: https://google-guice.googlecode.com/svn/trunk@569 d779f126-a31b-0410-b53b-1d3aecad763e
diff --git a/src/com/google/inject/BindElementProcessor.java b/src/com/google/inject/BindElementProcessor.java
index 489e987..eb66bdb 100644
--- a/src/com/google/inject/BindElementProcessor.java
+++ b/src/com/google/inject/BindElementProcessor.java
@@ -118,7 +118,7 @@
});
command.acceptTargetVisitor(new com.google.inject.Binding.TargetVisitor<T, Void>() {
- public Void visitToInstance(T instance) {
+ public Void visitInstance(T instance) {
if (instance == null) {
errors.cannotBindToNullInstance();
putBinding(invalidBinding(injector, key, source));
@@ -133,7 +133,7 @@
return null;
}
- public Void visitToProvider(Provider<? extends T> provider) {
+ public Void visitProvider(Provider<? extends T> provider) {
InternalFactoryToProviderAdapter<? extends T> factory
= new InternalFactoryToProviderAdapter<T>(provider, source);
memberInjector.requestInjection(provider, source);
@@ -144,7 +144,7 @@
return null;
}
- public Void visitToProviderKey(Key<? extends Provider<? extends T>> providerKey) {
+ public Void visitProviderKey(Key<? extends Provider<? extends T>> providerKey) {
final BoundProviderFactory<T> boundProviderFactory =
new BoundProviderFactory<T>(providerKey, source);
creationListeners.add(boundProviderFactory);
@@ -155,7 +155,7 @@
return null;
}
- public Void visitToKey(Key<? extends T> targetKey) {
+ public Void visitKey(Key<? extends T> targetKey) {
if (key.equals(targetKey)) {
errors.recursiveBinding();
}
@@ -258,7 +258,7 @@
@Override public Boolean visitBindConstant(BindConstant command) {
Object value = command.acceptTargetVisitor(new DefaultBindTargetVisitor<Object, Object>() {
- @Override public Object visitToInstance(Object instance) {
+ @Override public Object visitInstance(Object instance) {
return instance;
}
diff --git a/src/com/google/inject/Binding.java b/src/com/google/inject/Binding.java
index bb8b05f..d0a7438 100644
--- a/src/com/google/inject/Binding.java
+++ b/src/com/google/inject/Binding.java
@@ -21,9 +21,20 @@
import java.lang.reflect.Constructor;
/**
- * A mapping from a key (type and optional annotation) to a provider of
- * instances of that type. This interface is part of the {@link Injector}
- * introspection API and is intended primary for use by tools.
+ * A mapping from a key (type and optional annotation) to the strategy for getting instances of the
+ * type. This interface is part of the introspection API and is intended primarily for use by
+ * tools. Bindings exist on both {@link Module}s and on {@link Injector}s, and their behaviour is
+ * different for each.
+ *
+ * <p><strong>Module bindings</storng> are incomplete and cannot be used to provide instances. This
+ * is because the applicable scopes and interceptors may not be known until an injector is created.
+ * From a tool's perspective, module bindings are like the injector's source code. They can be
+ * inspected or rewritten, but this analysis must be done statically.
+ *
+ * <p><strong>Injector bindings</strong> are complete and valid and can be used to provide
+ * instances. From a tools' perspective, injector bindings are like reflection for an injector.
+ * They have full runtime information, including the complete graph of injections necessary to
+ * satisfy a binding.
*
* @author crazybob@google.com (Bob Lee)
* @author jessewilson@google.com (Jesse Wilson)
@@ -62,11 +73,20 @@
<V> V acceptScopingVisitor(ScopingVisitor<V> visitor);
+ /**
+ * A strategy to find an instance that satisfies an injection.
+ */
interface TargetVisitor<T, V> {
- V visitToInstance(T instance);
- V visitToProvider(Provider<? extends T> provider);
- V visitToProviderKey(Key<? extends Provider<? extends T>> providerKey);
- V visitToKey(Key<? extends T> key);
+
+ /**
+ * Visit a instance binding. The same instance is returned for every injection. This target is
+ * used in both module and injector bindings.
+ */
+ V visitInstance(T instance);
+
+ V visitProvider(Provider<? extends T> provider);
+ V visitProviderKey(Key<? extends Provider<? extends T>> providerKey);
+ V visitKey(Key<? extends T> key);
// module-only bindings
V visitUntargetted();
diff --git a/src/com/google/inject/CreationTimeMemberInjector.java b/src/com/google/inject/CreationTimeMemberInjector.java
index 6492167..c81b762 100644
--- a/src/com/google/inject/CreationTimeMemberInjector.java
+++ b/src/com/google/inject/CreationTimeMemberInjector.java
@@ -17,11 +17,11 @@
package com.google.inject;
import static com.google.common.base.Preconditions.checkNotNull;
-import com.google.common.collect.Lists;
import com.google.common.collect.Maps;
import com.google.inject.internal.Errors;
import com.google.inject.internal.ErrorsException;
import java.util.Map;
+import java.util.Map.Entry;
import java.util.concurrent.CountDownLatch;
/**
@@ -81,8 +81,11 @@
* arbitrary.
*/
void injectAll(final Errors errors) {
- // loop over a defensive copy since ensureInjected() mutates the set
- for (Map.Entry<Object, Object> entry : Lists.newArrayList(outstandingInjections.entrySet())) {
+ // loop over a defensive copy since ensureInjected() mutates the set. Unfortunately, that copy
+ // is made complicated by a bug in IBM's JDK, wherein entrySet().toArray(Object[]) doesn't work
+ for (Object entryObject : outstandingInjections.entrySet().toArray()) {
+ @SuppressWarnings("unchecked")
+ Entry<Object, Object> entry = (Entry<Object, Object>) entryObject;
try {
Object toInject = entry.getKey();
Object source = entry.getValue();
diff --git a/src/com/google/inject/InstanceBindingImpl.java b/src/com/google/inject/InstanceBindingImpl.java
index 9f61613..8c99cc1 100644
--- a/src/com/google/inject/InstanceBindingImpl.java
+++ b/src/com/google/inject/InstanceBindingImpl.java
@@ -47,7 +47,7 @@
}
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToInstance(instance);
+ return visitor.visitInstance(instance);
}
public T getInstance() {
diff --git a/src/com/google/inject/LinkedBindingImpl.java b/src/com/google/inject/LinkedBindingImpl.java
index db273c6..d88e0e9 100644
--- a/src/com/google/inject/LinkedBindingImpl.java
+++ b/src/com/google/inject/LinkedBindingImpl.java
@@ -43,7 +43,7 @@
}
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToKey(targetKey);
+ return visitor.visitKey(targetKey);
}
public OldVersionBinding<? extends T> getTargetBinding() {
diff --git a/src/com/google/inject/LinkedProviderBindingImpl.java b/src/com/google/inject/LinkedProviderBindingImpl.java
index e42eb45..7e198e4 100644
--- a/src/com/google/inject/LinkedProviderBindingImpl.java
+++ b/src/com/google/inject/LinkedProviderBindingImpl.java
@@ -47,7 +47,7 @@
}
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToProviderKey(providerKey);
+ return visitor.visitProviderKey(providerKey);
}
@Override public String toString() {
diff --git a/src/com/google/inject/ProviderInstanceBindingImpl.java b/src/com/google/inject/ProviderInstanceBindingImpl.java
index a96980b..59490f2 100644
--- a/src/com/google/inject/ProviderInstanceBindingImpl.java
+++ b/src/com/google/inject/ProviderInstanceBindingImpl.java
@@ -45,7 +45,7 @@
}
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToProvider(providerInstance);
+ return visitor.visitProvider(providerInstance);
}
public Provider<? extends T> getProviderInstance() {
diff --git a/src/com/google/inject/internal/ModuleBinding.java b/src/com/google/inject/internal/ModuleBinding.java
index 94f90ce..a955c2e 100644
--- a/src/com/google/inject/internal/ModuleBinding.java
+++ b/src/com/google/inject/internal/ModuleBinding.java
@@ -54,7 +54,7 @@
return true;
}
- @Override public Boolean visitToInstance(Object instance) {
+ @Override public Boolean visitInstance(Object instance) {
return false;
}
};
@@ -157,7 +157,7 @@
checkNotTargetted();
target = new Target<T>() {
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToKey(targetKey);
+ return visitor.visitKey(targetKey);
}
@Override public String toString() {
return String.valueOf(targetKey);
@@ -170,7 +170,7 @@
checkNotTargetted();
target = new Target<T>() {
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToInstance(instance);
+ return visitor.visitInstance(instance);
}
};
}
@@ -180,7 +180,7 @@
checkNotTargetted();
target = new Target<T>() {
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToProvider(provider);
+ return visitor.visitProvider(provider);
}
};
return this;
@@ -197,7 +197,7 @@
checkNotTargetted();
target = new Target<T>() {
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToProviderKey(providerKey);
+ return visitor.visitProviderKey(providerKey);
}
};
return this;
diff --git a/src/com/google/inject/spi/BindConstant.java b/src/com/google/inject/spi/BindConstant.java
index 3189dd8..0fd54c1 100644
--- a/src/com/google/inject/spi/BindConstant.java
+++ b/src/com/google/inject/spi/BindConstant.java
@@ -85,7 +85,7 @@
return type;
}
public <V> V acceptTargetVisitor(TargetVisitor<? super T, V> visitor) {
- return visitor.visitToInstance(value);
+ return visitor.visitInstance(value);
}
@Override public String toString() {
return String.valueOf(value);
diff --git a/src/com/google/inject/spi/DefaultBindTargetVisitor.java b/src/com/google/inject/spi/DefaultBindTargetVisitor.java
index 98046de..c0d0633 100644
--- a/src/com/google/inject/spi/DefaultBindTargetVisitor.java
+++ b/src/com/google/inject/spi/DefaultBindTargetVisitor.java
@@ -27,19 +27,19 @@
return null;
}
- public V visitToInstance(T instance) {
+ public V visitInstance(T instance) {
return visitTarget();
}
- public V visitToProvider(Provider<? extends T> provider) {
+ public V visitProvider(Provider<? extends T> provider) {
return visitTarget();
}
- public V visitToProviderKey(Key<? extends Provider<? extends T>> providerKey) {
+ public V visitProviderKey(Key<? extends Provider<? extends T>> providerKey) {
return visitTarget();
}
- public V visitToKey(Key<? extends T> key) {
+ public V visitKey(Key<? extends T> key) {
return visitTarget();
}
diff --git a/src/com/google/inject/spi/Elements.java b/src/com/google/inject/spi/Elements.java
index d1f6857..ce2f5fa 100644
--- a/src/com/google/inject/spi/Elements.java
+++ b/src/com/google/inject/spi/Elements.java
@@ -51,7 +51,7 @@
public final class Elements {
private static final TargetVisitor<Object, Object> GET_INSTANCE_VISITOR
= new DefaultBindTargetVisitor<Object, Object>() {
- @Override public Object visitToInstance(Object instance) {
+ @Override public Object visitInstance(Object instance) {
return instance;
}
diff --git a/src/com/google/inject/spi/ModuleWriter.java b/src/com/google/inject/spi/ModuleWriter.java
index 0664995..a85d106 100644
--- a/src/com/google/inject/spi/ModuleWriter.java
+++ b/src/com/google/inject/spi/ModuleWriter.java
@@ -171,20 +171,20 @@
public <T> ScopedBindingBuilder applyTarget(Binding<T> binding,
final LinkedBindingBuilder<T> linkedBindingBuilder) {
return binding.acceptTargetVisitor(new com.google.inject.Binding.TargetVisitor<T, ScopedBindingBuilder>() {
- public ScopedBindingBuilder visitToInstance(T instance) {
+ public ScopedBindingBuilder visitInstance(T instance) {
linkedBindingBuilder.toInstance(instance);
return null;
}
- public ScopedBindingBuilder visitToProvider(Provider<? extends T> provider) {
+ public ScopedBindingBuilder visitProvider(Provider<? extends T> provider) {
return linkedBindingBuilder.toProvider(provider);
}
- public ScopedBindingBuilder visitToProviderKey(Key<? extends Provider<? extends T>> providerKey) {
+ public ScopedBindingBuilder visitProviderKey(Key<? extends Provider<? extends T>> providerKey) {
return linkedBindingBuilder.toProvider(providerKey);
}
- public ScopedBindingBuilder visitToKey(Key<? extends T> key) {
+ public ScopedBindingBuilder visitKey(Key<? extends T> key) {
return linkedBindingBuilder.to(key);
}
diff --git a/src/com/google/inject/spi/oldversion/InstanceBinding.java b/src/com/google/inject/spi/oldversion/InstanceBinding.java
index 844303e..fa593d9 100644
--- a/src/com/google/inject/spi/oldversion/InstanceBinding.java
+++ b/src/com/google/inject/spi/oldversion/InstanceBinding.java
@@ -24,7 +24,7 @@
* <p>Example: {@code bind(Runnable.class).toInstance(new MyRunnable());}
*
* @deprecated replaced with {@link
- * com.google.inject.Binding.TargetVisitor#visitToInstance(Object)}
+ * com.google.inject.Binding.TargetVisitor#visitInstance(Object)}
*
* @author crazybob@google.com (Bob Lee)
*/
diff --git a/src/com/google/inject/spi/oldversion/LinkedBinding.java b/src/com/google/inject/spi/oldversion/LinkedBinding.java
index dfe5cce..552876b 100644
--- a/src/com/google/inject/spi/oldversion/LinkedBinding.java
+++ b/src/com/google/inject/spi/oldversion/LinkedBinding.java
@@ -22,7 +22,7 @@
* <p>Example: {@code bind(Collection.class).to(List.class);}
*
* @deprecated replaced with {@link
- * com.google.inject.Binding.TargetVisitor#visitToKey(com.google.inject.Key)}
+ * com.google.inject.Binding.TargetVisitor#visitKey(com.google.inject.Key)}
*
* @author crazybob@google.com (Bob Lee)
*/
diff --git a/src/com/google/inject/spi/oldversion/LinkedProviderBinding.java b/src/com/google/inject/spi/oldversion/LinkedProviderBinding.java
index 4bb8043..2ea8ee9 100644
--- a/src/com/google/inject/spi/oldversion/LinkedProviderBinding.java
+++ b/src/com/google/inject/spi/oldversion/LinkedProviderBinding.java
@@ -25,7 +25,7 @@
* <p>Example: {@code bind(Foo.class).toProvider(FooProvider.class);}
*
* @deprecated replaced with {@link
- * com.google.inject.Binding.TargetVisitor#visitToProviderKey(com.google.inject.Key)}
+ * com.google.inject.Binding.TargetVisitor#visitProviderKey(com.google.inject.Key)}
*
* @author crazybob@google.com (Bob Lee)
*/
diff --git a/src/com/google/inject/spi/oldversion/ProviderInstanceBinding.java b/src/com/google/inject/spi/oldversion/ProviderInstanceBinding.java
index ede4f43..7d8e139 100644
--- a/src/com/google/inject/spi/oldversion/ProviderInstanceBinding.java
+++ b/src/com/google/inject/spi/oldversion/ProviderInstanceBinding.java
@@ -25,7 +25,7 @@
* <p>Example: {@code bind(Foo.class).toProvider(new FooProvider());}
*
* @deprecated replaced with {@link
- * com.google.inject.Binding.TargetVisitor#visitToProvider(com.google.inject.Provider)}
+ * com.google.inject.Binding.TargetVisitor#visitProvider(com.google.inject.Provider)}
*
* @author crazybob@google.com (Bob Lee)
*/
diff --git a/test/com/google/inject/BinderTest.java b/test/com/google/inject/BinderTest.java
index 6f96ae0..5b3d8bb 100644
--- a/test/com/google/inject/BinderTest.java
+++ b/test/com/google/inject/BinderTest.java
@@ -35,7 +35,10 @@
* @author crazybob@google.com (Bob Lee)
*/
public class BinderTest extends TestCase {
-
+ private static final Boolean CONSTANT = false;
+ CONSTANT.toString()
+public static final Date PROMOTION_END_DATE = new Date(2008, 12, 31);
+
private ParameterizedType parameterizedWithVariable;
private ParameterizedType parameterizedWithWildcard;
private TypeVariable typeVariable;
diff --git a/test/com/google/inject/spi/ElementsTest.java b/test/com/google/inject/spi/ElementsTest.java
index db5b34d..ebf713b 100644
--- a/test/com/google/inject/spi/ElementsTest.java
+++ b/test/com/google/inject/spi/ElementsTest.java
@@ -351,7 +351,7 @@
@Override public <T> Void visitBinding(Binding<T> command) {
assertEquals(Key.get(String.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- public Void visitToProvider(Provider<? extends T> provider) {
+ public Void visitProvider(Provider<? extends T> provider) {
assertSame(aProvider, provider);
return null;
}
@@ -364,7 +364,7 @@
@Override public <T> Void visitBinding(Binding<T> command) {
assertEquals(Key.get(List.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- public Void visitToProviderKey(Key<? extends Provider<? extends T>> providerKey) {
+ public Void visitProviderKey(Key<? extends Provider<? extends T>> providerKey) {
assertEquals(Key.get(ListProvider.class), providerKey);
return null;
}
@@ -377,7 +377,7 @@
@Override public <T> Void visitBinding(Binding<T> command) {
assertEquals(Key.get(Collection.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- public Void visitToProviderKey(Key<? extends Provider<? extends T>> providerKey) {
+ public Void visitProviderKey(Key<? extends Provider<? extends T>> providerKey) {
assertEquals(Key.get(ListProvider.class), providerKey);
return null;
}
@@ -402,7 +402,7 @@
@Override public <T> Void visitBinding(Binding<T> command) {
assertEquals(Key.get(List.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- public Void visitToKey(Key<? extends T> key) {
+ public Void visitKey(Key<? extends T> key) {
assertEquals(Key.get(ArrayList.class), key);
return null;
}
@@ -415,7 +415,7 @@
@Override public <T> Void visitBinding(Binding<T> command) {
assertEquals(Key.get(Map.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- public Void visitToKey(Key<? extends T> key) {
+ public Void visitKey(Key<? extends T> key) {
assertEquals(Key.get(new TypeLiteral<HashMap<Integer, String>>() {}), key);
return null;
}
@@ -428,7 +428,7 @@
@Override public <T> Void visitBinding(Binding<T> command) {
assertEquals(Key.get(Set.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- public Void visitToKey(Key<? extends T> key) {
+ public Void visitKey(Key<? extends T> key) {
assertEquals(Key.get(TreeSet.class, SampleAnnotation.class), key);
return null;
}
diff --git a/test/com/google/inject/spi/SpiBindingsTest.java b/test/com/google/inject/spi/SpiBindingsTest.java
index 2349fb8..83d95e5 100644
--- a/test/com/google/inject/spi/SpiBindingsTest.java
+++ b/test/com/google/inject/spi/SpiBindingsTest.java
@@ -76,7 +76,7 @@
assertContains(command.getSource().toString(), "SpiBindingsTest.java");
assertEquals(Key.get(String.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- @Override public Void visitToInstance(T instance) {
+ @Override public Void visitInstance(T instance) {
assertEquals("A", instance);
return null;
}
@@ -102,7 +102,7 @@
assertContains(command.getSource().toString(), "SpiBindingsTest.java");
assertEquals(Key.get(String.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- @Override public Void visitToProvider(Provider<? extends T> provider) {
+ @Override public Void visitProvider(Provider<? extends T> provider) {
assertSame(stringProvider, provider);
return null;
}
@@ -126,7 +126,7 @@
assertContains(command.getSource().toString(), "SpiBindingsTest.java");
assertEquals(Key.get(String.class), command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- @Override public Void visitToProviderKey(Key<? extends Provider<? extends T>> key) {
+ @Override public Void visitProviderKey(Key<? extends Provider<? extends T>> key) {
assertEquals(Key.get(StringProvider.class), key);
return null;
}
@@ -154,7 +154,7 @@
assertContains(command.getSource().toString(), "SpiBindingsTest.java");
assertEquals(aKey, command.getKey());
command.acceptTargetVisitor(new FailingTargetVisitor<T>() {
- @Override public Void visitToKey(Key<? extends T> key) {
+ @Override public Void visitKey(Key<? extends T> key) {
assertEquals(bKey, key);
return null;
}
