Author: limpbizkit
Date: Thu Oct 23 22:37:55 2008
New Revision: 649
Modified:
trunk/extensions/privatemodules/src/com/google/inject/privatemodules/PrivateModule.java
Log:
Incorporating Brian Slesinsky's feedback into the PrivateModules javadoc
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
Thu Oct 23 22:37:55 2008
@@ -51,15 +51,19 @@
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:
+ * A module whose configuration information is hidden from its environment
by default. Only bindings
+ * that are explicitly exposed will be available to other modules and to
the users of the injector.
+ * This module may expose the bindings it creates and the bindings of the
modules it installs.
+ *
+ * <p>A private module can be nested within a regular module or within
another private module using
+ * [EMAIL PROTECTED] Binder#install install()}. Its bindings live in a new
environment that inherits bindings,
+ * type converters, scopes, and interceptors from the surrounding
("parent") environment. When you
+ * nest multiple private modules, the result is a tree of environments
where the injector's
+ * environment is the root.
+ *
+ * <p>Guice EDSL bindings can be exposed with [EMAIL PROTECTED] #expose(Class)
expose()}. [EMAIL PROTECTED] @[EMAIL PROTECTED]
+ * com.google.inject.Provides Provides} bindings can be exposed with the
[EMAIL PROTECTED] @[EMAIL PROTECTED]
+ * Exposed} annotation:
*
* <pre>
* public class FooBarBazModule extends PrivateModule {
@@ -81,21 +85,18 @@
* }
* </pre>
*
- * <p>Private modules inherit type converters, scopes, and interceptors
from their containing
- * modules. They can be nested within standard modules and within other
private modules using
- * [EMAIL PROTECTED] Binder#install install()}.
- *
- * <p>Private modules are implemented on top of [EMAIL PROTECTED]
Injector#createChildInjector(Module[]) parent
- * injectors}. Just-in-time bindings may be created in the parent
injector, sharing them with all
- * other modules. When bindings are shared:
- * <ul>
- * <li>Scoped instances are shared across modules. For example, if
[EMAIL PROTECTED] FooImpl} is a shared
- * singleton, the other modules get the same instance.</li>
- * <li>Bindings that inject the [EMAIL PROTECTED] Injector} get the parent
injector. It will not be able
- * to [EMAIL PROTECTED] Injector#getInstance(Key) get injections} bound
in the
private module.</li>
- * </ul>
- * Just-in-time bindings will not be shared if they have dependencies in
the private module. To
- * prevent it from being shared, write an explicit binding:
+ * <p>Private modules are implemented using [EMAIL PROTECTED]
Injector#createChildInjector(Module[]) parent
+ * injectors}. When it can satisfy their dependencies, just-in-time
bindings will be created in the
+ * root environment. Such bindings are shared among all environments in
the tree.
+ *
+ * <p>The scope of a shared binding is also shared among all environments
in the tree. For example,
+ * if [EMAIL PROTECTED] FooImpl} is a shared singleton, all other modules will
get
the same instance.
+ *
+ * <p>A shared binding that injects the [EMAIL PROTECTED] Injector} gets the
root
injector, which only has
+ * access to bindings in the root environment. An explicit binding that
injects the [EMAIL PROTECTED] Injector}
+ * gets access to all bindings in the child environment.
+ *
+ * <p>To promote a just-in-time binding to an explicit binding, bind it:
* <pre>
* bind(FooImpl.class);
* </pre>
--~--~---------~--~----~------------~-------~--~----~
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
-~----------~----~----~----~------~----~------~--~---
