Author: tchemit Date: 2010-03-12 16:32:43 +0100 (Fri, 12 Mar 2010) New Revision: 1775 Log: add javadoc Modified: trunk/jaxx-runtime/src/main/java/jaxx/runtime/swing/AbstractActionThread.java Modified: trunk/jaxx-runtime/src/main/java/jaxx/runtime/swing/AbstractActionThread.java =================================================================== --- trunk/jaxx-runtime/src/main/java/jaxx/runtime/swing/AbstractActionThread.java 2010-03-12 00:24:04 UTC (rev 1774) +++ trunk/jaxx-runtime/src/main/java/jaxx/runtime/swing/AbstractActionThread.java 2010-03-12 15:32:43 UTC (rev 1775) @@ -7,10 +7,24 @@ import java.beans.PropertyChangeEvent; import java.beans.PropertyChangeListener; +/** + * An abstract action thread to consume actions in a non Swing event thread. + * <p/> + * Implements the method {@code onActionXXX(ActionWorker)} to hook on action + * status. + * <p/> + * To consume an action, use the method {@link #addAction(String, Runnable)}. + * <p/> + * TODO Make this multi-action enable + * + * @author tchemit <chemit@codelutin.com> + * @since 2.0 + */ public abstract class AbstractActionThread extends Thread { /** Logger */ - private static final Log log = LogFactory.getLog(AbstractActionThread.class); + private static final Log log = + LogFactory.getLog(AbstractActionThread.class); /** l'état du thread si annulé */ private boolean canceled; @@ -21,16 +35,20 @@ */ private final Object LOCK = new Object(); + /** current worker to execute action */ protected ActionWorker worker; + /** the listener of running action */ protected final PropertyChangeListener workerListener; + /** State of a running action */ enum ActionStatus { OK, CANCEL, FAIL } + /** Action worker to execute a incoming action. */ public static class ActionWorker extends SwingWorker<Void, Object> { protected final String actionLabel; @@ -152,15 +170,13 @@ }; } - - public void cancel() { - log.info("cancel " + this); - canceled = true; - - // on rend la main au thread - setWaiting(false); - } - + /** + * Add an new action to perform. + * + * @param actionLabel the name of the action to perform + * @param action the action to perform + * @return the worker that will launch the action + */ public ActionWorker addAction(String actionLabel, Runnable action) { if (worker != null && !worker.isDone()) { // on ne peut traiter qu'une seule opération à la fois @@ -181,12 +197,35 @@ return worker; } + /** + * Hook when a action is about to start. + * + * @param source the action worker containing the action to perform + */ public abstract void onActionStart(ActionWorker source); + + /** + * Hook when a action has failed. + * + * @param source the action worker containing the action to perform + */ public abstract void onActionFail(ActionWorker source); + + /** + * Hook when a action has been canceled. + * + * @param source the action worker containing the action to perform + */ public abstract void onActionCancel(ActionWorker source); + + /** + * Hook when a action has end with no failure or cancel. + * + * @param source the action worker containing the action to perform + */ public abstract void onActionEnd(ActionWorker source); @Override @@ -256,17 +295,40 @@ throw new RuntimeException(e); } finally { unlockThread(); - log.trace(this + " will close..."); + if (log.isInfoEnabled()) { + log.info(this + " will close..."); + } close(); } } + /** + * Cancel the thread, this will release any lock of the tread. + * <p/> + * As a side effect, this will close the thread. + */ + public void cancel() { + log.info("cancel " + this); + canceled = true; + + // on rend la main au thread + setWaiting(false); + } + /** La méthode pour nettoyer le thread, a la fermeture. */ protected void close() { // par defaut, on ne fait rien log.info(this); } + /** + * Mutates the waiting state of the thread. + * <p/> + * If parameter {@code waiting} is to {@code true}, then will lock the + * thread, otherwise will unlock the thread. + * + * @param waiting {@code true} if a lock is required + */ protected void setWaiting(boolean waiting) { if (waiting && !canceled) { @@ -285,6 +347,11 @@ } } + /** + * To lock the thread. + * + * @throws InterruptedException if locking was interruped + */ protected void lockThread() throws InterruptedException { synchronized (LOCK) { log.trace(this); @@ -293,6 +360,7 @@ } } + /** To unlock the thread. */ protected void unlockThread() { synchronized (LOCK) { log.trace(this);