Author: limpbizkit
Date: Wed Oct 15 15:30:44 2008
New Revision: 634
Removed:
trunk/src/com/google/inject/spi/ProviderMethods.java
Modified:
trunk/extensions/privatemodules/src/com/google/inject/privatemodules/PrivateModule.java
Log:
Javadoc for PrivateModules
Modified:
trunk/extensions/privatemodules/src/com/google/inject/privatemodules/PrivateModule.java
==============================================================================
---
trunk/extensions/privatemodules/src/com/google/inject/privatemodules/PrivateModule.java
(original)
+++
trunk/extensions/privatemodules/src/com/google/inject/privatemodules/PrivateModule.java
Wed Oct 15 15:30:44 2008
@@ -51,6 +51,40 @@
import org.aopalliance.intercept.MethodInterceptor;
/**
+ * A module whose configuration information is hidden from other modules.
Only bindings that are
+ * explicitly [EMAIL PROTECTED] #expose(Class) exposed} will be available to
other
modules and to the injector.
+ * Exposed keys must be explicitly bound, either directly or via another
module that's installed
+ * by the private module.
+ *
+ * <p>In addition to the bindings configured via [EMAIL PROTECTED]
#configurePrivateBindings()}, bindings will
+ * be created for all methods with the [EMAIL PROTECTED] @[EMAIL PROTECTED]
com.google.inject.Provides Provides}
+ * annotation. These bindings will be hidden from other modules unless the
methods also have the
+ * [EMAIL PROTECTED] @[EMAIL PROTECTED] Exposed} annotation:
+ *
+ * <pre>
+ * public class FooBarBazModule extends PrivateModule {
+ * protected void configurePrivateBindings() {
+ * bind(Foo.class).to(RealFoo.class);
+ * expose(Foo.class);
+ *
+ * install(new TransactionalBarModule());
+ * expose(Bar.class).annotatedWith(Transactional.class);
+ *
+ * bind(SomeImplementationDetail.class);
+ * install(new MoreImplementationDetailsModule());
+ * }
+ *
+ * [EMAIL PROTECTED] @}Provides [EMAIL PROTECTED] @}Exposed
+ * public Baz provideBaz() {
+ * return new SuperBaz();
+ * }
+ * }
+ * </pre>
+ *
+ * <p>Private modules are implemented with [EMAIL PROTECTED]
Injector#createChildInjector(Module[]) parent
+ * injectors.} Types that inject an [EMAIL PROTECTED] Injector} will be
provided with
the child injector. This
+ * injector includes private bindings that are not available from the
parent injector.
+ *
* @author [EMAIL PROTECTED] (Jesse Wilson)
*/
public abstract class PrivateModule implements Module {
@@ -68,32 +102,31 @@
private Binder privateBinder;
public final synchronized void configure(Binder binder) {
- // when exposes is null, we're being run for the public injector
+ // when 'exposes' is null, we're being run for the public injector
if (exposes == null) {
configurePublicBindings(binder);
+ return;
+ }
// otherwise we're being run for the private injector
- } else {
- checkState(this.privateBinder == null, "Re-entry is not allowed.");
- privateBinder = binder.skipSources(PrivateModule.class);
- try {
- configurePrivateBindings();
-
- ProviderMethodsModule providerMethodsModule =
ProviderMethodsModule.forPrivateModule(this);
- for (ProviderMethod<?> providerMethod
- : providerMethodsModule.getProviderMethods(privateBinder)) {
- providerMethod.configure(privateBinder);
- if
(providerMethod.getMethod().isAnnotationPresent(Exposed.class)) {
- expose(providerMethod.getKey());
- }
- }
+ checkState(this.privateBinder == null, "Re-entry is not allowed.");
+ privateBinder = binder.skipSources(PrivateModule.class);
+ try {
+ configurePrivateBindings();
- for (Expose<?> expose : exposes) {
- expose.initPrivateProvider(binder);
+ ProviderMethodsModule providerMethods =
ProviderMethodsModule.forPrivateModule(this);
+ for (ProviderMethod<?> providerMethod :
providerMethods.getProviderMethods(privateBinder)) {
+ providerMethod.configure(privateBinder);
+ if (providerMethod.getMethod().isAnnotationPresent(Exposed.class))
{
+ expose(providerMethod.getKey());
}
- } finally {
- privateBinder = null;
}
+
+ for (Expose<?> expose : exposes) {
+ expose.initPrivateProvider(binder);
+ }
+ } finally {
+ privateBinder = null;
}
}
@@ -131,15 +164,26 @@
}
}
+ /** Marker object used to indicate the private injector has been created
*/
private static class Ready {}
- public abstract void configurePrivateBindings();
+ /**
+ * Creates bindings and other configurations private to this module. Use
[EMAIL PROTECTED] #expose(Class)
+ * expose()} to make the bindings in this module available externally.
+ */
+ protected abstract void configurePrivateBindings();
+ /** Makes the binding for [EMAIL PROTECTED] key} available to other modules
and the
injector. */
protected final <T> void expose(Key<T> key) {
checkState(exposes != null, "Cannot expose %s, private module is not
ready");
exposes.add(new Expose<T>(sourceProvider.get(), readyProvider, key));
}
+ /**
+ * Makes a binding for [EMAIL PROTECTED] type} available to other modules
and the
injector. Use [EMAIL PROTECTED]
+ * ExposedKeyBuilder#annotatedWith(Class) annotatedWith()} to expose
[EMAIL PROTECTED] type} with a binding
+ * annotation.
+ */
protected final <T> ExposedKeyBuilder expose(Class<T> type) {
checkState(exposes != null, "Cannot expose %s, private module is not
ready");
Expose<T> expose = new Expose<T>(sourceProvider.get(), readyProvider,
Key.get(type));
@@ -147,6 +191,11 @@
return expose;
}
+ /**
+ * Makes a binding for [EMAIL PROTECTED] type} available to other modules
and the
injector. Use [EMAIL PROTECTED]
+ * ExposedKeyBuilder#annotatedWith(Class) annotatedWith()} to expose
[EMAIL PROTECTED] type} with a binding
+ * annotation.
+ */
protected final <T> ExposedKeyBuilder expose(TypeLiteral<T> type) {
checkState(exposes != null, "Cannot expose %s, private module is not
ready");
Expose<T> expose = new Expose<T>(sourceProvider.get(), readyProvider,
Key.get(type));
@@ -154,14 +203,13 @@
return expose;
}
+ /** Qualifies an exposed type with a binding annotation. */
public interface ExposedKeyBuilder {
void annotatedWith(Class<? extends Annotation> annotationType);
void annotatedWith(Annotation annotation);
}
- /**
- * A binding from the private injector exposed to the public injector.
- */
+ /** A binding from the private injector exposed to the public injector.
*/
private static class Expose<T> implements ExposedKeyBuilder, Provider<T>
{
private final Object source;
private final Provider<Ready> readyProvider;
@@ -200,9 +248,7 @@
}
}
- /**
- * Returns the set of keys bound by [EMAIL PROTECTED] elements}.
- */
+ /** Returns the set of keys bound by [EMAIL PROTECTED] elements}. */
private Set<Key<?>> getBoundKeys(Iterable<? extends Element> elements) {
final Set<Key<?>> privatelyBoundKeys = Sets.newHashSet();
ElementVisitor<Void> visitor = new DefaultElementVisitor<Void>() {
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"google-guice-dev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/google-guice-dev?hl=en
-~----------~----~----~----~------~----~------~--~---
