Permalink
Browse files

providing StabilityMonitor & StabilityStatistics javadoc

  • Loading branch information...
1 parent 21ead6b commit 18f12c2f7f0e1c413ca127443101f953c0c82c3f @ropalka ropalka committed Jan 16, 2013
@@ -36,8 +36,53 @@
import java.util.concurrent.atomic.AtomicBoolean;
/**
- * A stability monitor for satisfying certain AS use cases.
- *
+ * A stability detection utility. It can be used to detect
+ * if all the registered controllers with {@link StabilityMonitor} are in REST state.
+ * The following controller substates are considered to be in REST state:
+ *
+ * <ul>
+ * <li>{@link ServiceController.Substate#CANCELLED}</li>
+ * <li>{@link ServiceController.Substate#WAITING}</li>
+ * <li>{@link ServiceController.Substate#WONT_START}</li>
+ * <li>{@link ServiceController.Substate#PROBLEM}</li>
+ * <li>{@link ServiceController.Substate#START_FAILED}</li>
+ * <li>{@link ServiceController.Substate#UP}</li>
+ * <li>{@link ServiceController.Substate#REMOVED}</li>
+ * </ul>
+ *
+ * Sample bulk usage:
+ *
+ * <pre>
+ * Set&lt;ServiceController&lt;?&gt;&gt; controllers = ...
+ * <b>StabilityMonitor monitor = new StabilityMonitor();</b>
+ * for (ServiceController&lt;?&gt; controller : controllers) {
+ * <b>monitor.addController(controller);</b>
+ * }
+ * try {
+ * <b>monitor.awaitStability();</b>
+ * } finally {
+ * <b>monitor.clear();</b>
+ * // since now on the monitor can be reused for another stability detection
+ * }
+ * // do something after all the controllers are in REST state
+ * </pre>
+ *
+ * Sample simple usage:
+ *
+ * <pre>
+ * ServiceController&lt;?&gt; controller = ...
+ * <b>StabilityMonitor monitor = new StabilityMonitor();</b>
+ * monitor.addController(controller);
+ * controller.setMode(REMOVE);
+ * try {
+ * <b>monitor.awaitStability();</b>
+ * } finally {
+ * <b>monitor.removeController(controller);</b>
+ * }
+ * // do something after controller have been removed from container
+ * </pre>
+ *
+ * @see StabilityStatistics
* @author <a href="mailto:david.lloyd@redhat.com">David M. Lloyd</a>
* @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
*/
@@ -51,6 +96,11 @@
private Set<ServiceControllerImpl<?>> controllers = new IdentityHashSet<ServiceControllerImpl<?>>();
private int unstableServices;
+ /**
+ * Register controller with this monitor.
+ *
+ * @param controller to be registered for stability detection.
+ */
public void addController(final ServiceController<?> controller) {
if (controller == null) return;
final ServiceControllerImpl<?> serviceController = (ServiceControllerImpl<?>) controller;
@@ -62,6 +112,11 @@ public void addController(final ServiceController<?> controller) {
}
}
+ /**
+ * Unregister controller with this monitor.
+ *
+ * @param controller to be unregistered from stability detection.
+ */
public void removeController(final ServiceController<?> controller) {
if (controller == null) return;
final ServiceControllerImpl<?> serviceController = (ServiceControllerImpl<?>) controller;
@@ -73,6 +128,10 @@ public void removeController(final ServiceController<?> controller) {
}
}
+ /**
+ * Removes all the registered controllers in this monitor.
+ * The monitor can be later reused for stability detection again.
+ */
public void clear() {
if (cleanupInProgress.compareAndSet(false, true)) {
synchronized (controllersLock) {
@@ -96,30 +155,93 @@ public void clear() {
}
}
+ /**
+ * Causes the current thread to wait until the monitor is stable.
+ *
+ * @throws InterruptedException if the current thread is interrupted
+ * while waiting
+ */
public void awaitStability() throws InterruptedException {
awaitStability(null, null, null);
}
+ /**
+ * Causes the current thread to wait until the monitor is stable.
+ *
+ * @param statistics stability statistics report to fill in
+ * @throws InterruptedException if the current thread is interrupted
+ * while waiting
+ */
public void awaitStability(final StabilityStatistics statistics) throws InterruptedException {
awaitStability(null, null, statistics);
}
+ /**
+ * Causes the current thread to wait until the monitor is stable.
+ *
+ * @param timeout the maximum time to wait
+ * @param unit the time unit of the {@code timeout} argument
+ * @return <tt>true</tt> if this monitor achieved stability,
+ * <tt>false</tt> if the timeout elapsed before stability
+ * @throws InterruptedException if the current thread is interrupted
+ * while waiting
+ */
public boolean awaitStability(final long timeout, final TimeUnit unit) throws InterruptedException {
return awaitStability(timeout, unit, null, null, null);
}
+ /**
+ * Causes the current thread to wait until the monitor is stable.
+ *
+ * @param timeout the maximum time to wait
+ * @param unit the time unit of the {@code timeout} argument
+ * @param statistics stability statistics report to fill in
+ * @return <tt>true</tt> if this monitor achieved stability,
+ * <tt>false</tt> if the timeout elapsed before stability
+ * @throws InterruptedException if the current thread is interrupted
+ * while waiting
+ */
public boolean awaitStability(final long timeout, final TimeUnit unit, final StabilityStatistics statistics) throws InterruptedException {
return awaitStability(timeout, unit, null, null, statistics);
}
+ /**
+ * Causes the current thread to wait until the monitor is stable.
+ *
+ * @param failed a set into which failed services should be copied
+ * @param problems a set into which problem services should be copied
+ * @throws InterruptedException if the current thread is interrupted
+ * while waiting
+ */
public void awaitStability(final Set<? super ServiceController<?>> failed, final Set<? super ServiceController<?>> problems) throws InterruptedException {
this.awaitStability(failed, problems, null);
}
+ /**
+ * Causes the current thread to wait until the monitor is stable.
+ *
+ * @param timeout the maximum time to wait
+ * @param unit the time unit of the {@code timeout} argument
+ * @param failed a set into which failed services should be copied
+ * @param problems a set into which problem services should be copied
+ * @return <tt>true</tt> if this monitor achieved stability,
+ * <tt>false</tt> if the timeout elapsed before stability
+ * @throws InterruptedException if the current thread is interrupted
+ * while waiting
+ */
public boolean awaitStability(final long timeout, final TimeUnit unit, final Set<? super ServiceController<?>> failed, final Set<? super ServiceController<?>> problems) throws InterruptedException {
return awaitStability(timeout, unit, failed, problems, null);
}
+ /**
+ * Causes the current thread to wait until the monitor is stable.
+ *
+ * @param failed a set into which failed services should be copied
+ * @param problems a set into which problem services should be copied
+ * @param statistics stability statistics report to fill in
+ * @throws InterruptedException if the current thread is interrupted
+ * while waiting
+ */
public void awaitStability(final Set<? super ServiceController<?>> failed, final Set<? super ServiceController<?>> problems, final StabilityStatistics statistics) throws InterruptedException {
final int failedCount;
final int problemsCount;
@@ -142,6 +264,19 @@ public void awaitStability(final Set<? super ServiceController<?>> failed, final
provideStatistics(failedCount, problemsCount, statistics);
}
+ /**
+ * Causes the current thread to wait until the monitor is stable.
+ *
+ * @param timeout the maximum time to wait
+ * @param unit the time unit of the {@code timeout} argument
+ * @param failed a set into which failed services should be copied
+ * @param problems a set into which problem services should be copied
+ * @param statistics stability statistics report to fill in
+ * @return <tt>true</tt> if this monitor achieved stability,
+ * <tt>false</tt> if the timeout elapsed before stability
+ * @throws InterruptedException if the current thread is interrupted
+ * while waiting
+ */
public boolean awaitStability(final long timeout, final TimeUnit unit, final Set<? super ServiceController<?>> failed, final Set<? super ServiceController<?>> problems, final StabilityStatistics statistics) throws InterruptedException {
long now = System.nanoTime();
long remaining = unit.toNanos(timeout);
@@ -23,8 +23,30 @@
package org.jboss.msc.service;
/**
- * A stability monitor statistics.
+ * A stability monitor statistics. Allows to collect statistics data
+ * about {@link ServiceController}s registered with {@link StabilityMonitor} object.
+ * The following data are available:
+ * <ul>
+ * <li>count of controllers in <b>ACTIVE</b> mode - see method {@link #getActiveCount()}</li>
+ * <li>count of controllers that <b>FAILED</b> to start - see method {@link #getFailedCount()}</li>
+ * <li>count of controllers in <b>LAZY</b> mode - see method {@link #getLazyCount()}</li>
+ * <li>count of controllers in <b>NEVER</b> mode - see method {@link #getNeverCount()}</li>
+ * <li>count of controllers in <b>ON_DEMAND</b> mode - see method {@link #getOnDemandCount()}</li>
+ * <li>count of controllers in <b>PASSIVE</b> mode - see method {@link #getPassiveCount()}</li>
+ * <li>count of controllers that had <b>PROBLEM</b> to start - see method {@link #getProblemsCount()}</li>
+ * <li>count of controllers in <b>UP</b> state - see method {@link #getStartedCount()}</li>
+ * <li>count of controllers in <b>REMOVE</b> mode - see method {@link #getRemovedCount()}</li>
+ * </ul>
+ *
+ * Sample usage:
+ * <pre>
+ * StabilityMonitor monitor = ...
+ * <b>StabilityStatistics statistics = new StabilityStatistics();</b>
+ * monitor.awaitStability(<b>statistics</b>);
+ * // do something with <b>statistics</b> object.
+ * </pre>
*
+ * @see StabilityMonitor
* @author <a href="mailto:ropalka@redhat.com">Richard Opalka</a>
*/
public final class StabilityStatistics {
@@ -38,39 +60,84 @@
private int problems;
private int started;
private int removed;
-
+
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that are in
+ * {@link ServiceController.Mode#ACTIVE} mode.
+ * @return count of <b>ACTIVE</b> controllers
+ */
public int getActiveCount() {
return active;
}
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that failed to start
+ * because of start exception being thrown.
+ * @return count of <b>FAILED</b> controllers
+ */
public int getFailedCount() {
return failed;
}
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that are in
+ * {@link ServiceController.Mode#LAZY} mode.
+ * @return count of <b>LAZY</b> controllers
+ */
public int getLazyCount() {
return lazy;
}
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that are in
+ * {@link ServiceController.Mode#NEVER} mode.
+ * @return count of <b>NEVER</b> controllers
+ */
public int getNeverCount() {
return never;
}
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that are in
+ * {@link ServiceController.Mode#ON_DEMAND} mode.
+ * @return count of <b>ON_DEMAND</b> controllers
+ */
public int getOnDemandCount() {
return onDemand;
}
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that are in
+ * {@link ServiceController.Mode#PASSIVE} mode.
+ * @return count of <b>PASSIVE</b> controllers
+ */
public int getPassiveCount() {
return passive;
}
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that had problem to start
+ * because of missing dependencies.
+ * @return count of <b>PROBLEM</b> controllers
+ */
public int getProblemsCount() {
return problems;
}
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that are in
+ * {@link ServiceController.State#UP} state.
+ * @return count of <b>STARTED</b> controllers
+ */
public int getStartedCount() {
return started;
}
+ /**
+ * Returns count of controllers registered with {@link StabilityMonitor} that are in
+ * {@link ServiceController.Mode#REMOVE} mode.
+ * @return count of <b>REMOVE</b> controllers
+ */
public int getRemovedCount() {
return removed;
}

0 comments on commit 18f12c2

Please sign in to comment.