[jboss-cvs] JBossAS SVN: r89526 - in projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi: dispatch and 1 other directories.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Fri May 29 07:14:38 EDT 2009
Author: kabir.khan at jboss.com
Date: 2009-05-29 07:14:38 -0400 (Fri, 29 May 2009)
New Revision: 89526
Modified:
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/CallbackItem.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/Cardinality.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/Controller.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerContext.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerContextActions.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerMode.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerState.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerStateModel.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/DependencyInfo.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/DependencyItem.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ErrorHandlingMode.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/LifecycleCallbackItem.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/dispatch/AttributeDispatchContext.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableControllerContext.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableDependencyInfo.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableScopeInfo.java
projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/package.html
Log:
[JBKERNEL-14] Javadocs for dependency module
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/CallbackItem.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/CallbackItem.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/CallbackItem.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -25,7 +25,25 @@
package org.jboss.dependency.spi;
/**
- * Callback information.
+ * This represents a callback. These are held within a {@link ControllerContext}'s
+ * {@link DependencyInfo}. The {@link ControllerContext} can have several callbacks associated
+ * with it. Callbacks can either be invoked when installing the owning {@link ControllerContext} or
+ * when uninstalling the owning {@link ControllerContext}. The {@link ControllerContext}s
+ * {@link DependencyInfo} maintains a collection of install callbacks and a collection of
+ * uninstall callbacks.
+ * <p>
+ * An install callback is a listener for when other beans of a certain type are installed into
+ * the {@link Controller}, and an uninstall callback is a listener for when other beans of a certain type
+ * are uninstalled from the {@link Controller}. Beans with callbacks must expose a method taking a single
+ * parameter, or a property/attribute which is a collection containing elements of a certain type.
+ * The type of the parameter, if using methods, or of the property/attribute collection type specifies
+ * the type of bean install/uninstalls this bean listens to.
+ * <p>
+ * When installing a bean implementing the given type, the associated install callback method on the
+ * bean owning this callback gets called, and when uninstalling a bean implementing the given type,
+ * the associated uninstall callback method on the bean owning this callback gets called. If a
+ * property/attribute is used installed beans get added to the collection of the bean owning this
+ * callback, and uninstalled beans get removed from the collection.
*
* @param <T> expected name type - Class, String, ...
* @author <a href="mailto:ales.justin at jboss.com">Ales Justin</a>
@@ -33,38 +51,44 @@
public interface CallbackItem<T>
{
/**
- * Get the object name i depend on
+ * The type of beans that my owning bean listens to being installed/uninstalled
*
- * @return the name
+ * @return the type
*/
T getIDependOn();
/**
- * Get when the dependency is required
+ * Get when the dependency is required. The callback must have been invoked
+ * before the bean owning this can enter this state.
+ * The default is {@link ControllerState#CONFIGURED}
*
* @return the state when required
*/
ControllerState getWhenRequired();
/**
- * Get the dependent's state
+ * Get the state the beans that we are listening for will be in when invoking
+ * the listener method/attribute/property. The default is {@link ControllerState#INSTALLED}
*
* @return the state of the required of the dependent
*/
ControllerState getDependentState();
/**
- * Get the method/attribute/property name
+ * Get the method/attribute/property name used for handling installs/uninstalls
+ * of beans we are listening for.
*
* @return the name
*/
String getAttributeName();
/**
- * Execute callback when item added to controller.
+ * Execute callback when item installed/uninstalled to controller. This will invoke the callback method
+ * on the owning bean. If a property/attribute as used it will add to the collection if it is an install
+ * callback, and remove from the collection if it is an uninstall callback.
*
* @param controller the controller
- * @param isInstallPhase install or uninstall
+ * @param isInstallPhase true if callback should be called on install, false if callback should be called on uninstall
* @throws Throwable for any error
*/
void ownerCallback(Controller controller, boolean isInstallPhase) throws Throwable;
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/Cardinality.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/Cardinality.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/Cardinality.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -27,7 +27,9 @@
import org.jboss.util.JBossStringBuilder;
/**
- * Cardinality def.
+ * Used to specify the number of beans as a range of a certain type that must have been registered
+ * with the {@link Controller} before invoking the callback method/property/attribute specified
+ * by a {@link CallbackItem} for that type on a bean's {@link ControllerContext}.
*
* @author <a href="mailto:ales.justin at jboss.com">Ales Justin</a>
*/
@@ -200,26 +202,46 @@
return left == card.left && right == card.right;
}
+ /**
+ * Returns a string represenation of the range, e.g. '1..2'
+ * @return the string representation
+ */
public String getType()
{
return type;
}
+ /**
+ * Get the lower bound of the range for this cardinality
+ * @return the lower bound of the range
+ */
public int getLeft()
{
return left;
}
+ /**
+ * Get the upper bound of the range for this cardinality
+ * @return the upper bound of the range
+ */
public int getRight()
{
return right;
}
+ /**
+ * Check if the lower bound is infinity
+ * return true if lower bound is infinity
+ */
public boolean isLeftInfinity()
{
return left <= INFINITY;
}
+ /**
+ * Check if the upper bound is infinity
+ * return true if upper bound is infinity
+ */
public boolean isRightInfinity()
{
return right <= INFINITY;
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/Controller.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/Controller.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/Controller.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -26,12 +26,14 @@
import org.jboss.util.JBossInterface;
/**
- * A controller.<p>
- *
- * The controller is the core component for keeping track
- * of contexts to make sure the configuration and lifecycle are
+ * The controller is the state-machine at the heart of the JBoss
+ * Microcontainer. It keeps track of {@link ControllerContext}s
+ * to make sure the configuration and lifecycle are
* done in the correct order including dependencies and
- * classloading considerations.
+ * classloading considerations. Several controllers can exist in a hiearchy.
+ * <p>
+ * The {@link ControllerContext}s each represent a bean that is to
+ * be installed in the Microcontainer.
*
* @author <a href="adrian at jboss.com">Adrian Brock</a>
* @version $Revision$
@@ -39,7 +41,14 @@
public interface Controller extends JBossInterface
{
/**
- * Install a context
+ * Install a controller context.
+ * This will attempt to move the controller context as far
+ * as possible through its states. For contexts using
+ * {@link ControllerMode#AUTOMATIC} it will attempt to move it to
+ * the {@link ControllerState#INSTALLED} state. If in any state the
+ * context's dependencies are not satisfied, the context will be held
+ * at that state until its depdencies are satisfied. Once its dependencies
+ * are satisfied the install initiated by calling this method will resume.
*
* @param context the context
* @throws Throwable for any error
@@ -47,7 +56,9 @@
void install(ControllerContext context) throws Throwable;
/**
- * Change a context to the given state
+ * Change a context to the given state. The given state can
+ * either be before or after the state the context is currently
+ * in.
*
* @param context the context
* @param state the state
@@ -56,7 +67,8 @@
void change(ControllerContext context, ControllerState state) throws Throwable;
/**
- * Enable an on demand context
+ * Enable an on demand context and move it to the {@link ControllerState#INSTALLED}
+ * state.
*
* @param context the context
* @throws Throwable for any error
@@ -64,15 +76,16 @@
void enableOnDemand(ControllerContext context) throws Throwable;
/**
- * Uninstall a context
+ * Uninstall a context. This will move the context to the {@link ControllerState#NOT_INSTALLED}
+ * atate. If other contexts depend on this context, they will be uninstalled first.
*
- * @param name the name of the component
+ * @param name the name of the component to uninstall
* @return the context
*/
ControllerContext uninstall(Object name);
/**
- * Add alias.
+ * Add an alias. An alias is an alternative name to be used for a bean, and are
*
* @param alias the alias to add
* @param original original name
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerContext.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerContext.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerContext.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -26,22 +26,27 @@
import org.jboss.util.JBossInterface;
/**
- * Information about a context.
+ * A controller context represents a bean installed in the Microcontainer's
+ * {@link Controller}. The {@link Controller} does work on the ControllerContext to move it through
+ * its lifecycle. The lifecycle is made up of a series of {@link ControllerState}s. Entry to each
+ * {@link ControllerState} can be associated to trigger an action configured in the {@link ControllerContextActions}
*
+ *
* @author <a href="adrian at jboss.com">Adrian Brock</a>
* @version $Revision$
*/
public interface ControllerContext extends JBossInterface
{
/**
- * Get the name
+ * Get the name of the context. The name uniquely identifies the context in the {@link Controller}
+ * (or hierarchy of {@link Controller}s).
*
* @return the name
*/
Object getName();
/**
- * The aliases
+ * Return a set of aliases for the context. Aliases must be unique within a {@link Controller}.
*
* @return the aliases or null if there are no aliases
*/
@@ -62,28 +67,31 @@
ScopeInfo getScopeInfo();
/**
- * Get any target
+ * Get the target of the context. This will normally be the bean instance, available after
+ * the context reaches the {@link ControllerState#INSTANTIATED} state.
*
* @return the target
*/
Object getTarget();
/**
- * Get the controller
+ * Get the controller that manages this controller context
*
* @return the controller
*/
Controller getController();
/**
- * Set the controller
+ * Set the controller that manages this controller context
*
* @param controller the controller
*/
void setController(Controller controller);
/**
- * Install
+ * Moves the context from fromState to toState, where toState is a later state than fromState.
+ * The corresponding install action set up in its {@link ControllerContextActions} for toState
+ * will be invoked.
*
* @param fromState the old state
* @param toState the new state
@@ -92,7 +100,9 @@
void install(ControllerState fromState, ControllerState toState) throws Throwable;
/**
- * Uninstall
+ * Moves the context from fromState to toState, where toState is an earlier state than fromState.
+ * The corresponding uninstall action set up in its {@link ControllerContextActions} for fromState
+ * will be invoked.
*
* @param fromState the old state
* @param toState the new state
@@ -100,42 +110,48 @@
void uninstall(ControllerState fromState, ControllerState toState);
/**
- * Get the state
+ * Get the current state of this controller context
*
* @return the state
*/
ControllerState getState();
/**
- * Set the state
+ * Set the current state of this controller context. Once under control of the {@link Controller},
+ * only the {@link Controller} should call this method
*
* @param state the state
*/
void setState(ControllerState state);
/**
- * Get the required state
+ * Get the state that this controller context should reach.
+ * For contexts using {@link ControllerMode#AUTOMATIC} this will typically
+ * be {@link ControllerState#INSTANTIATED}
*
* @return the required state
*/
ControllerState getRequiredState();
/**
- * Set the required state
+ * Set the state that this controller context should reach.
+ * For contexts using {@link ControllerMode#AUTOMATIC} in the out-of-the-box configuration
+ * this will typically be {@link ControllerState#INSTANTIATED}
*
* @param state the required state
*/
void setRequiredState(ControllerState state);
/**
- * Get the mode
+ * Get the mode for this controller context
*
* @return the mode
*/
ControllerMode getMode();
/**
- * Set the mode
+ * Set the mode for this controller context. Once under control of the {@link Controller},
+ * only the {@link Controller} should call this method.
*
* @param mode the mode
*/
@@ -143,20 +159,23 @@
/**
* Get the error handling mode.
+ * The default is {@link ErrorHandlingMode#DISCARD}
*
* @return the error handling mode
*/
ErrorHandlingMode getErrorHandlingMode();
/**
- * Get the error
+ * If installing this controller context caused an error, this method
+ * will return the underlying error.
*
* @return the error
*/
Throwable getError();
/**
- * Set the error
+ * If installing this controller context caused an error, set the error here.
+ * This method should only be called by the {@link Controller}.
*
* @param error the error
*/
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerContextActions.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerContextActions.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerContextActions.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -22,7 +22,29 @@
package org.jboss.dependency.spi;
/**
- * Controller context actions.
+ * The default implementation of {@link ControllerContext} has a reference to
+ * {@link ControllerContextActions}. When a {@link ControllerContext} is installed to
+ * or uninstalled from a given state that can be associated with an action.
+ * <p>
+ * The default actions when running the full kernel are on installing to/uninstalling from:
+ * <ul>
+ * <li>{@link ControllerState#NOT_INSTALLED} - This is the starting state
+ * for {@link ControllerContext}s to be installed</li>
+ * <li>{@link ControllerState#PRE_INSTALL} - Determine the scoping policy
+ * of the {@link ControllerContext} to see if it should go in the main controller
+ * or in a child controller</li>
+ * <li>{@link ControllerState#DESCRIBED} - Determine the bean's dependencies</li>
+ * <li>{@link ControllerState#PRE_INSTALL} - Instantiate the bean instance and set it
+ * in the {@link ControllerContext}'s target</li>
+ * <li>{@link ControllerState#CONFIGURED} - Configure the bean instance with the properties
+ * from the bean metadata and perform injection of other bean instances.</li>
+ * <li>{@link ControllerState#CREATE} - Call any create/destroy lifecycle methods</li>
+ * <li>{@link ControllerState#START} - Call any start/stop lifecycle methods</li>
+ * <li>{@link ControllerState#INSTALLED} - The bean is properly started. Any lifecycle
+ * install/uninstall methods are called on the bean</li>
+ * </ul>
+ * If something went wrong installing the {@link ControllerContext}, the {@link ControllerContext}
+ * enters the {@link ControllerState#ERROR} state.
*
* @author <a href="adrian at jboss.com">Adrian Brock</a>
* @version $Revision$
@@ -30,9 +52,10 @@
public interface ControllerContextActions
{
/**
- * Install a context
+ * Invokes the install action that as associated with the {@link ControllerContext}'s toState.
+ * If there is no such action, do nothing
*
- * @param context the context
+ * @param context the context being installed
* @param fromState the old state
* @param toState the new state
* @throws Throwable for any error
@@ -40,9 +63,10 @@
void install(ControllerContext context, ControllerState fromState, ControllerState toState) throws Throwable;
/**
- * Uninstall a context
+ * Invokes the uninstall action that as associated with the {@link ControllerContext}'s fromState.
+ * If there is no such action, do nothing
*
- * @param context the context
+ * @param context the context being uninstalled
* @param fromState the old state
* @param toState the new state
*/
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerMode.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerMode.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerMode.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -29,8 +29,13 @@
import org.jboss.xb.annotations.JBossXmlEnum;
/**
- * Mode of the context.
+ * Enumeration used to specify the mode a {@link ControllerContext} should be installed,
+ * which has impact on what the {@link Controller} does when told to install a {@link ControllerContext}.
+ * The comments on the enum constants relates to running the Microcontainer in its
+ * default configuration.<p>
*
+ * For a description of the {@link ControllerState}s mentioned, see {@link ControllerContextActions}.
+ *
* @author <a href="adrian at jboss.com">Adrian Brock</a>
* @author <a href="ales.justin at jboss.com">Ales Justin</a>
* @version $Revision$
@@ -38,10 +43,26 @@
@JBossXmlEnum(ignoreCase=true)
public enum ControllerMode
{
+ /**
+ * The {@link Controller} will install the {@link ControllerContext} all the way to the
+ * {@link ControllerState#INSTALLED} state.
+ */
AUTOMATIC("Automatic", ControllerState.INSTALLED),
+
+ /**
+ * The {@link Controller} will install the {@link ControllerContext} to the {@link ControllerState#DESCRIBED}
+ * state and keep it there until another {@link ControllerContext} actually wants to use it for injection.
+ */
@XmlEnumValue("On Demand") ON_DEMAND("On Demand", ControllerState.DESCRIBED),
MANUAL("Manual"),
+ /**
+ * The {@link Controller} will not install the {@link ControllerContext}
+ */
DISABLED("Disabled"),
+ /**
+ * The {@link Controller} will install the {@link ControllerContext} in another thread, allowing parallel deployments.
+ * The {@link ControllerContext} will be installed all the way to {@link ControllerState#INSTALLED}
+ */
ASYNCHRONOUS("Asynchronous", ControllerState.INSTALLED);
/** The mode string */
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerState.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerState.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerState.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -30,8 +30,13 @@
import org.jboss.util.JBossStringBuilder;
/**
- * Description of state.
+ * Description of the state of a {@link ControllerContext} in the controller.
+ * See {@link ControllerContextActions} for a description of the states and
+ * how they are used. The default states used when running in full kernel mode
+ * are constant ControllerState fields in this class.
*
+ *
+ * @see ControllerContextActions
* @author <a href="adrian at jboss.com">Adrian Brock</a>
* @version $Revision$
*/
@@ -106,6 +111,11 @@
return stateString;
}
+ /**
+ * Checks if the other object is also a ControllerState and has the same
+ * stateString
+ * @param object The object we want to compare with.
+ */
public boolean equals(Object object)
{
if (object == null || object instanceof ControllerState == false)
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerStateModel.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerStateModel.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ControllerStateModel.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -25,7 +25,7 @@
/**
* ControllerState model.
- * Helper/util methods.
+ * Helper/util methods used to compare and iterate over {@link ControllerState}s
*
* @author <a href="mailto:ales.justin at jboss.com">Ales Justin</a>
*/
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/DependencyInfo.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/DependencyInfo.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/DependencyInfo.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -27,8 +27,10 @@
import org.jboss.util.JBossInterface;
/**
- * Information about dependencies.
+ * Contains information about a {@link ControllerContext}'s dependencies on other dependencies.
+ * It also contains information about {@link CallbackItem}s and {@link LifecycleCallbackItem}s
*
+ * @see ControllerContext#getDependencyInfo();
* @author <a href="adrian at jboss.com">Adrian Brock</a>
* @version $Revision$
*/
@@ -79,24 +81,25 @@
void removeDependsOnMe(DependencyItem dependency);
/**
- * Try to resolve dependencies
+ * Try to resolve dependencies. Look for each unresolved dependency item
+ * in the controller, and if found move to the resolved state.
*
* @param controller the controller
- * @param state the state of dependency to resolve
+ * @param state the state of dependencies to resolve, or null to resolve all dependencies
* @return true when all dependencies are resolved
*/
boolean resolveDependencies(Controller controller, ControllerState state);
/**
- * Return the unresolved dependencies
+ * Return the unresolved dependencies.
*
- * @param state the controller state
+ * @param state the controller state of the dependencies we could not resolve, or null for all unresolved dependencies
* @return our unresolved dependencies
*/
Set<DependencyItem> getUnresolvedDependencies(ControllerState state);
/**
- * Add a callback reference
+ * Add an install callback reference
*
* @param <T> the callback item type
* @param callbackItem the callback to add
@@ -104,7 +107,7 @@
<T> void addInstallItem(CallbackItem<T> callbackItem);
/**
- * Remove a callback reference
+ * Remove an install callback reference
*
* @param <T> the callback item type
* @param callbackItem the callback to remove
@@ -119,7 +122,7 @@
Set<CallbackItem<?>> getInstallItems();
/**
- * Add a callback reference
+ * Add an uninstall callback reference
*
* @param <T> the callback item type
* @param callbackItem the callback to add
@@ -127,7 +130,7 @@
<T> void addUninstallItem(CallbackItem<T> callbackItem);
/**
- * Remove a callback reference
+ * Remove an uninstall callback reference
*
* @param <T> the callback item type
* @param callbackItem the callback to remove
@@ -156,7 +159,10 @@
List<LifecycleCallbackItem> getLifecycleCallbacks();
/**
- * Can we use this context for autowiring.
+ * Can we use this context for autowiring. If <code>true</code> then
+ * {@link ControllerContext}s wanting to inject the bean from the {@link ControllerContext} owning this DependencyInfo
+ * do not need to specify the name of the {@link ControllerContext}. Instead a match between the type of the target property/
+ * parameter and the bean type of the {@link ControllerContext} owning this DependencyInfo can be used.
*
* @return true if context can be used for autowiring
*/
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/DependencyItem.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/DependencyItem.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/DependencyItem.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -22,7 +22,13 @@
package org.jboss.dependency.spi;
/**
- * Information about a single dependency.
+ * Information about a single dependency on a {@link ControllerContext}. These are
+ * held within a {@link ControllerContext}'s {@link DependencyInfo}.
+ * <p>
+ * When the owning {@link ControllerContext} enters the state in
+ * {@link #getWhenRequired()}, if the {@link ControllerContext} we have a dependency
+ * on has not reached the state in {@link #getDependentState()} the owning
+ * {@link ControllerContext} cannot proceed to the state in {@link #getWhenRequired()}.
*
* @author <a href="adrian at jboss.com">Adrian Brock</a>
* @version $Revision$
@@ -30,42 +36,47 @@
public interface DependencyItem
{
/**
- * Get the object name i depend on
+ * Get the name of the {@link ControllerContext} I depend on.
*
* @return the name
*/
Object getIDependOn();
/**
- * Get my object name
+ * Get the name of the {@link ControllerContext} this dependency belongs to.
*
- * @return the name
+ * @return the name of the owning {@link ControllerContext}
*/
Object getName();
/**
- * Get when the dependency is required
+ * Get when the dependency is required. This is the state of the owning
+ * {@link ControllerContext}.
*
* @return the state when required
*/
ControllerState getWhenRequired();
/**
- * Get the dependent's state
+ * Get the dependencies state. This is the state of dependency the {@link ControllerContext}
+ * represented by this dependency item that the owning {@link ControllerContext}
+ * depends on.
*
* @return the state of the required of the dependent
*/
ControllerState getDependentState();
/**
- * Whether we are resolved
+ * Whether we are resolved. Resolved means that the dependency has reached the
+ * state given by {@link #getDependentState()}
*
* @return true for resolved, false otherwise
*/
boolean isResolved();
/**
- * Try to resolve
+ * Try to resolve. This will look up the dependency {@link ControllerContext} in the
+ * controller.
*
* @param controller the controller
* @return true for resolved, false otherwise
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ErrorHandlingMode.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ErrorHandlingMode.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/ErrorHandlingMode.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -24,14 +24,26 @@
import org.jboss.xb.annotations.JBossXmlEnum;
/**
- * Error handling mode.
+ * Specifies how the {@link Controller} should handle a {@link ControllerContext} that throws
+ * an error when moving between states.
*
* @author <a href="ales.justin at jboss.com">Ales Justin</a>
*/
@JBossXmlEnum(ignoreCase=true)
public enum ErrorHandlingMode
{
+ /**
+ * The default mode, unless otherwise specified when creating the {@link ControllerContext},
+ * tells the {@link Controller} to move the failed {@link ControllerContext}s to the
+ * {@link ControllerState#ERROR} state.
+ */
DISCARD, // The default as before
+ /**
+ * The Manual mode allows advanced users to handle {@link ControllerContext}s in error themselves.
+ */
MANUAL, // Handle contexts in error yourself
+ /**
+ * ???
+ */
CHECKED // As MANUAL but RuntimeExceptions, Errors lead to a DISCARD
}
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/LifecycleCallbackItem.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/LifecycleCallbackItem.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/LifecycleCallbackItem.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -22,15 +22,44 @@
package org.jboss.dependency.spi;
/**
+ * This represents a lifecycle callback applied via aop the
+ * <code>
+ * <lifecycle-xxx>
+ * </code> bindings.
*
+ * This represents a dependency on a {@link ControllerContext}. These are
+ * held within a {@link ControllerContext}'s {@link DependencyInfo}.
+ * <p>
+ * When the owning {@link ControllerContext} enters the state in
+ * {@link #getWhenRequired()}, if the {@link ControllerContext} of the lifecycle callback
+ * we have a dependency on has not reached the state in {@link #getDependentState()} the owning
+ * {@link ControllerContext} cannot proceed to the state in {@link #getWhenRequired()}.
+ * <p>
+ * When the owning {@link ControllerContext} enters the {@link #getWhenRequired()}
+ * state on install the {@link #install(ControllerContext)} method is called by the controller.
+ * This will delegate to the
+ * <code>
+ * public void install(ControllerContext context)
+ * </code> method of the lifecycle callback bean implementation.
+ * <p>
+ * On uninstalling the owning {@link ControllerContext} from the {@link #getWhenRequired()}
+ * state, the {@link #uninstall(ControllerContext)} method is called by the controller.
+ * This will delegate to the
+ * <code>
+ * public void uninstall(ControllerContext context)
+ * </code> method of the lifecycle callback bean implementation.
+ *
+ *
* @author <a href="kabir.khan at jboss.com">Kabir Khan</a>
* @version $Revision: 1.1 $
*/
public interface LifecycleCallbackItem
{
/**
- * Gets the target bean implementing this callback
- * @return the target bean name
+ * Gets the name of the lifecycle callback {@link ControllerContext}. This
+ * holds the bean implementing the lifecycle callback.
+ *
+ * @return the name of the lifecycle callback
*/
Object getBean();
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/dispatch/AttributeDispatchContext.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/dispatch/AttributeDispatchContext.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/dispatch/AttributeDispatchContext.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -24,7 +24,7 @@
/**
* The API similar to the DynamicMBean API
* where there are methods to get/set Properties/Attributes.
- * It is missing invoke, since not all context support it.
+ * It is missing invoke, since not all contexts support it.
* KernelControllerContext -> Configurator
* ServiceControllerContext -> MBeanServer
*
@@ -38,7 +38,7 @@
* Getter property / attribute
*
* @param name property / attribute name
- * @return target's property / attribute instance
+ * @return target's property / attribute value
* @throws Throwable for any error
*/
Object get(String name) throws Throwable;
@@ -47,7 +47,7 @@
* Setter property / attribute
*
* @param name property / attribute name
- * @param value set target's property / attribute instance
+ * @param value set target's property / attribute value
* @throws Throwable for any error
*/
void set(String name, Object value) throws Throwable;
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableControllerContext.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableControllerContext.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableControllerContext.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -34,7 +34,8 @@
import org.jboss.util.JBossObject;
/**
- * Unmodifiable delegate instance.
+ * A wrapper around a {@link ControllerContext} that throws UnsupportedOperationException when any
+ * methods that might mutate the underlying context's state is called.
*
* @author <a href="mailto:ales.justin at jboss.com">Ales Justin</a>
*/
@@ -92,6 +93,13 @@
return delegate.getController();
}
+ /**
+ * Overrides {@link ControllerContext#setController(Controller)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param state the controller
+ * @throws UnsupportedOperationException when called
+ */
public void setController(Controller controller)
{
throw new UnsupportedOperationException("Cannot invoke set on unmodifiable wrapper.");
@@ -112,6 +120,13 @@
return delegate.getState();
}
+ /**
+ * Overrides {@link ControllerContext#setState(ControllerState)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param state the state
+ * @throws UnsupportedOperationException when called
+ */
public void setState(ControllerState state)
{
throw new UnsupportedOperationException("Cannot invoke set on unmodifiable wrapper.");
@@ -122,6 +137,13 @@
return delegate.getRequiredState();
}
+ /**
+ * Overrides {@link ControllerContext#setRequiredState(ControllerState)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param state the required state
+ * @throws UnsupportedOperationException when called
+ */
public void setRequiredState(ControllerState state)
{
throw new UnsupportedOperationException("Cannot invoke set on unmodifiable wrapper.");
@@ -132,6 +154,13 @@
return delegate.getMode();
}
+ /**
+ * Overrides {@link ControllerContext#setMode(ControllerMode)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param mode the mode
+ * @throws UnsupportedOperationException when called
+ */
public void setMode(ControllerMode mode)
{
throw new UnsupportedOperationException("Cannot invoke set on unmodifiable wrapper.");
@@ -147,6 +176,13 @@
return delegate.getError();
}
+ /**
+ * Overrides {@link ControllerContext#setError(Throwable)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param error the error
+ * @throws UnsupportedOperationException when called
+ */
public void setError(Throwable error)
{
throw new UnsupportedOperationException("Cannot invoke set on unmodifiable wrapper.");
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableDependencyInfo.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableDependencyInfo.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableDependencyInfo.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -21,19 +21,20 @@
*/
package org.jboss.dependency.spi.helpers;
+import java.util.List;
import java.util.Set;
-import java.util.List;
+import org.jboss.dependency.spi.CallbackItem;
+import org.jboss.dependency.spi.Controller;
+import org.jboss.dependency.spi.ControllerState;
import org.jboss.dependency.spi.DependencyInfo;
import org.jboss.dependency.spi.DependencyItem;
-import org.jboss.dependency.spi.Controller;
-import org.jboss.dependency.spi.ControllerState;
-import org.jboss.dependency.spi.CallbackItem;
import org.jboss.dependency.spi.LifecycleCallbackItem;
import org.jboss.util.JBossObject;
/**
- * Unmodifiable instance.
+ * A wrapper around a {@link DependencyInfo} that throws UnsupportedOperationException when any
+ * methods that might mutate the underlying {@link DependencyInfo} state is called.
*
* @author <a href="mailto:ales.justin at jboss.com">Ales Justin</a>
*/
@@ -58,21 +59,48 @@
return delegate.getDependsOnMe(type);
}
+ /**
+ * Overrides {@link DependencyInfo#addIDependOn(DependencyItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param dependency the dependency
+ * @throws UnsupportedOperationException when called
+ */
public void addIDependOn(DependencyItem dependency)
{
throw new UnsupportedOperationException("Cannot execute add on unmodifiable wrapper.");
}
+ /**
+ * Overrides {@link DependencyInfo#removeIDependOn(DependencyItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param dependency the dependency
+ * @throws UnsupportedOperationException when called
+ */
public void removeIDependOn(DependencyItem dependency)
{
throw new UnsupportedOperationException("Cannot execute remove on unmodifiable wrapper.");
}
+ /**
+ * Overrides {@link DependencyInfo#addDependsOnMe(DependencyItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param dependency the dependency
+ */
public void addDependsOnMe(DependencyItem dependency)
{
throw new UnsupportedOperationException("Cannot execute add on unmodifiable wrapper.");
}
+ /**
+ * Overrides {@link DependencyInfo#removeDependsOnMe(DependencyItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param dependency the dependency
+ * @throws UnsupportedOperationException when called
+ */
public void removeDependsOnMe(DependencyItem dependency)
{
throw new UnsupportedOperationException("Cannot execute remove on unmodifiable wrapper.");
@@ -88,11 +116,25 @@
return delegate.getUnresolvedDependencies(state);
}
+ /**
+ * Overrides {@link DependencyInfo#addInstallItem(CallbackItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param callbackItem the callback item
+ * @throws UnsupportedOperationException when called
+ */
public <T> void addInstallItem(CallbackItem<T> callbackItem)
{
throw new UnsupportedOperationException("Cannot execute add on unmodifiable wrapper.");
}
+ /**
+ * Overrides {@link DependencyInfo#removeInstallItem(CallbackItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param callbackItem the callback item
+ * @throws UnsupportedOperationException when called
+ */
public <T> void removeInstallItem(CallbackItem<T> callbackItem)
{
throw new UnsupportedOperationException("Cannot execute remove on unmodifiable wrapper.");
@@ -103,11 +145,25 @@
return delegate.getInstallItems();
}
+ /**
+ * Overrides {@link DependencyInfo#addUninstallItem(CallbackItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param callbackItem the callback item
+ * @throws UnsupportedOperationException when called
+ */
public <T> void addUninstallItem(CallbackItem<T> callbackItem)
{
throw new UnsupportedOperationException("Cannot execute add on unmodifiable wrapper.");
}
+ /**
+ * Overrides {@link DependencyInfo#removeUninstallItem(CallbackItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param callbackItem the callback item
+ * @throws UnsupportedOperationException when called
+ */
public <T> void removeUninstallItem(CallbackItem<T> callbackItem)
{
throw new UnsupportedOperationException("Cannot execute remove on unmodifiable wrapper.");
@@ -118,6 +174,13 @@
return delegate.getUninstallItems();
}
+ /**
+ * Overrides {@link DependencyInfo#addLifecycleCallback(LifecycleCallbackItem)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param lifecycleCallbackItem the lifecycle callback item
+ * @throws UnsupportedOperationException when called
+ */
public void addLifecycleCallback(LifecycleCallbackItem lifecycleCallbackItem)
{
throw new UnsupportedOperationException("Cannot execute add on unmodifiable wrapper.");
@@ -133,6 +196,13 @@
return delegate.isAutowireCandidate();
}
+ /**
+ * Overrides {@link DependencyInfo#setAutowireCandidate(boolean)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param candidate if we are an autowire candidate
+ * @throws UnsupportedOperationException when called
+ */
public void setAutowireCandidate(boolean candidate)
{
throw new UnsupportedOperationException("Cannot execute set on unmodifiable wrapper.");
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableScopeInfo.java
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableScopeInfo.java 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/helpers/UnmodifiableScopeInfo.java 2009-05-29 11:14:38 UTC (rev 89526)
@@ -31,7 +31,8 @@
import org.jboss.metadata.spi.scope.ScopeKey;
/**
- * UnmodifiableScopeInfo.
+ * A wrapper around a {@link ScopeInfo} that throws UnsupportedOperationException when any
+ * methods that might mutate the underlying {@link ScopeInfo} state is called.
*
* @author <a href="adrian at jboss.com">Adrian Brock</a>
* @version $Revision: 1.1 $
@@ -53,26 +54,68 @@
this.delegate = delegate;
}
+ /**
+ * Overrides {@link ScopeInfo#addMetaData(MutableMetaDataRepository, ControllerContext)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param repository the MutableMetaDataRepository
+ * @param context the controller context
+ * @throws UnsupportedOperationException when called
+ */
public void addMetaData(MutableMetaDataRepository repository, ControllerContext context)
{
throw new UnsupportedOperationException("Cannot modify immutable");
}
+ /**
+ * Overrides {@link ScopeInfo#removeMetaData(MutableMetaDataRepository, ControllerContext)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param repository the MutableMetaDataRepository
+ * @param context the controller context
+ * @throws UnsupportedOperationException when called
+ */
public void removeMetaData(MutableMetaDataRepository repository, ControllerContext context)
{
throw new UnsupportedOperationException("Cannot modify immutable");
}
+ /**
+ * Overrides {@link ScopeInfo#initMetaDataRetrieval(MutableMetaDataRepository, ControllerContext, Scope)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param repository the MutableMetaDataRepository
+ * @param context the controller context
+ * @param scope the scope
+ * @throws UnsupportedOperationException when called
+ */
public MetaDataRetrieval initMetaDataRetrieval(MutableMetaDataRepository repository, ControllerContext context, Scope scope)
{
throw new UnsupportedOperationException("Cannot modify immutable");
}
+ /**
+ * Overrides {@link ScopeInfo#initMetaDataRetrieval(MutableMetaDataRepository, ControllerContext)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param repository the MutableMetaDataRepository
+ * @param context the controller context
+ * @throws UnsupportedOperationException when called
+ */
public MetaDataRetrieval initMetaDataRetrieval(MutableMetaDataRepository repository, ControllerContext context)
{
throw new UnsupportedOperationException("Cannot modify immutable");
}
+ /**
+ * Overrides {@link ScopeInfo#initMutableMetaDataRetrieval(MutableMetaDataRepository, ControllerContext, ScopeKey)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param repository the MutableMetaDataRepository
+ * @param context the controller context
+ * @param scopeKet the scope key
+ * @throws UnsupportedOperationException when called
+ */
public MutableMetaDataLoader initMutableMetaDataRetrieval(MutableMetaDataRepository repository, ControllerContext context, ScopeKey scopeKey)
{
throw new UnsupportedOperationException("Cannot modify immutable");
@@ -108,6 +151,13 @@
return delegate.getInstallScope();
}
+ /**
+ * Overrides {@link ScopeInfo#setInstallScope(ScopeKey)} to throw an {@link UnsupportedOperationException}
+ * when called.
+ *
+ * @param key the scope key
+ * @throws UnsupportedOperationException when called
+ */
public void setInstallScope(ScopeKey key)
{
throw new UnsupportedOperationException("Cannot modify immutable");
Modified: projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/package.html
===================================================================
--- projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/package.html 2009-05-29 08:43:36 UTC (rev 89525)
+++ projects/microcontainer/trunk/dependency/src/main/java/org/jboss/dependency/spi/package.html 2009-05-29 11:14:38 UTC (rev 89526)
@@ -25,16 +25,6 @@
<li><a href="javascript: alert('not available')">Not Available</a>
</ul>
- <h2>Package Status</h2>
- <ul>
- <li><font color="red"><b>ALPHA</b></font>
- </ul>
-
- <h2>Todo</h2>
- <ul>
- <li>???
- </ul>
-
<!-- Put @see and @since tags down here. -->
</body>
More information about the jboss-cvs-commits
mailing list