[picocontainer-scm] [5671] java/2.x/trunk/pico/container/src/java/org/picocontainer: Minor javadoc while I was thinking about it :)

Revision 5671
Author rimovm
Date 2010-03-30 17:42:59 -0500 (Tue, 30 Mar 2010)

Log Message

Minor javadoc while I was thinking about it :)

Modified Paths

- java/2.x/trunk/pico/container/src/java/org/picocontainer/MutablePicoContainer.java

- java/2.x/trunk/pico/container/src/java/org/picocontainer/PicoBuilder.java

Diff

Modified: java/2.x/trunk/pico/container/src/java/org/picocontainer/MutablePicoContainer.java (5670 => 5671)

--- java/2.x/trunk/pico/container/src/java/org/picocontainer/MutablePicoContainer.java 2010-03-30 19:43:39 UTC (rev 5670)
+++ java/2.x/trunk/pico/container/src/java/org/picocontainer/MutablePicoContainer.java 2010-03-30 22:42:59 UTC (rev 5671)
@@ -119,13 +119,28 @@
<T> ComponentAdapter<T> removeComponentByInstance(T componentInstance);

/**
- * Make a child container, using the same implementation of MutablePicoContainer as the parent.
+ * Make a child container, using both the same implementation of MutablePicoContainer as the parent
+ * and identical behaviors as well.
* It will have a reference to this as parent. This will list the resulting MPC as a child.
* Lifecycle events will be cascaded from parent to child
- * as a consequence of this.
- *
+ * as a consequence of this.
+ * <p>Note that for long-lived parent containers, you need to unregister child containers
+ * made with this call before disposing or you will leak memory. <em>(Experience
+ * speaking here! )</em></p>
+ * <p>Incorrect Example:</p>
+ * <pre>
+ * MutablePicoContainer parent = new PicoBuilder().withCaching().withLifecycle().build();
+ * MutablePicoContainer child = parent.makeChildContainer();
+ * child = null; //Child still retains in memory because parent still holds reference.
+ * </pre>
+ * <p>Correct Example:</p>
+ * <pre>
+ * MutablePicoContainer parent = new PicoBuilder().withCaching().withLifecycle().build();
+ * MutablePicoContainer child = parent.makeChildContainer();
+ * parent.removeChildContainer(child); //Remove the bi-directional references.
+ * child = null;
+ * </pre>
* @return the new child container.
- *
*/
MutablePicoContainer makeChildContainer();

Modified: java/2.x/trunk/pico/container/src/java/org/picocontainer/PicoBuilder.java (5670 => 5671)

--- java/2.x/trunk/pico/container/src/java/org/picocontainer/PicoBuilder.java 2010-03-30 19:43:39 UTC (rev 5670)
+++ java/2.x/trunk/pico/container/src/java/org/picocontainer/PicoBuilder.java 2010-03-30 22:42:59 UTC (rev 5671)
@@ -69,6 +69,12 @@
injectors.add(injectionType);
}

+ /**
+ * Constructs a PicoBuilder using the specified PicoContainer as an argument. Note
+ * that this only creates child -&gt; parent references. You must use parentContainer.addChildContainer()
+ * to the instance built here if you require child &lt;-&gt; parent references.
+ * @param parentContainer
+ */
public PicoBuilder(PicoContainer parentContainer) {
if (parentContainer != null) {
this.parentContainer = parentContainer;
@@ -81,6 +87,9 @@
this(new EmptyPicoContainer(), injectionType);
}

+ /**
+ * Will be used to build a PicoContainer not bound to any parent container.
+ */
public PicoBuilder() {
this(new EmptyPicoContainer());
}
@@ -91,26 +100,44 @@
return this;
}

+ /**
+ * Constructed PicoContainer will use {@linkplain org.picocontainer.lifecycle.ReflectionLifecycleStrategy ReflectionLifecycle}.
+ * @return <em>this</em> to allow for method chaining.
+ */
public PicoBuilder withReflectionLifecycle() {
lifecycleStrategyClass = ReflectionLifecycleStrategy.class;
lifecycleStrategy = null;
return this;
}

- public PicoBuilder withLifecycle(Class<? extends LifecycleStrategy> lifecycleStrategyClass) {
- this.lifecycleStrategyClass = lifecycleStrategyClass;
+ /**
+ * Allows you to specify your own lifecycle strategy class.
+ * @param specifiedLifecycleStrategyType lifecycle strategy type.
+ * @return <em>this</em> to allow for method chaining.
+ */
+ public PicoBuilder withLifecycle(Class<? extends LifecycleStrategy> specifiedLifecycleStrategyType) {
+ this.lifecycleStrategyClass = specifiedLifecycleStrategyType;
lifecycleStrategy = null;
return this;
}

+ /**
+ * Constructed PicoContainer will use {@linkplain org.picocontainer.lifecycle.JavaEE5LifecycleStrategy JavaEE5LifecycleStrategy}.
+ * @return <em>this</em> to allow for method chaining.
+ */
public PicoBuilder withJavaEE5Lifecycle() {
this.lifecycleStrategyClass = JavaEE5LifecycleStrategy.class;
lifecycleStrategy = null;
return this;
}

- public PicoBuilder withLifecycle(LifecycleStrategy lifecycleStrategy) {
- this.lifecycleStrategy = lifecycleStrategy;
+ /**
+ * Allows you to fully specify your lifecycle strategy by passing in a built instance
+ * @param specifiedLifecycleStrategy
+ * @return <em>this</em> to allow for method chaining.
+ */
+ public PicoBuilder withLifecycle(LifecycleStrategy specifiedLifecycleStrategy) {
+ this.lifecycleStrategy = specifiedLifecycleStrategy;
lifecycleStrategyClass = null;
return this;
}
@@ -286,8 +313,14 @@
return this;
}

- public PicoBuilder withMonitor(ComponentMonitor componentMonitor) {
- this.componentMonitor = componentMonitor;
+ /**
+ * Allows you to specify your very own component monitor to be used by the created
+ * picocontainer
+ * @param specifiedComponentMonitor
+ * @return <em>this</em> to allow for method chaining.
+ */
+ public PicoBuilder withMonitor(ComponentMonitor specifiedComponentMonitor) {
+ this.componentMonitor = specifiedComponentMonitor;
componentMonitorClass = null;
return this;
}

----------

To unsubscribe from this list please visit:

http://xircles.codehaus.org/manage_email