Author: jverhaeg(a)redhat.com Date: 2008-06-10 18:16:01 -0400 (Tue, 10 Jun 2008) New Revision: 260 Added: trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java trunk/dna-common/src/main/java/org/jboss/dna/common/collection/SimpleProblems.java Removed: trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/NullProgressMonitor.java Modified: trunk/dna-common/src/main/java/org/jboss/dna/common/collection/UnmodifiableProperties.java trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/ProgressMonitor.java trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/ProgressMonitorWrapper.java trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/SimpleProgressMonitor.java trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/SubProgressMonitor.java trunk/dna-common/src/test/java/org/jboss/dna/common/component/ComponentLibraryTest.java trunk/dna-common/src/test/java/org/jboss/dna/common/monitor/SimpleProgressMonitorTest.java Log: DNA-75: Added ability to add problems to a progress monitor. Also clarified some documentation and removed NullProgressMonitor (used only for testing) in lieu of using a mock object. Deleted: trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java 2008-06-10 22:16:01 UTC (rev 260) @@ -1,187 +0,0 @@ -/* - * JBoss, Home of Professional Open Source. - * Copyright 2008, Red Hat Middleware LLC, and individual contributors - * as indicated by the @author tags. See the copyright.txt file in the - * distribution for a full listing of individual contributors. - * - * This is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation; either version 2.1 of - * the License, or (at your option) any later version. - * - * This software is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this software; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA - * 02110-1301 USA, or see the FSF site: http://www.fsf.org. - */ -package org.jboss.dna.common.collection; - -import java.util.Iterator; -import java.util.LinkedList; -import java.util.List; -import net.jcip.annotations.NotThreadSafe; -import org.jboss.dna.common.i18n.I18n; - -/** - * @author Randall Hauch - */ -@NotThreadSafe -public class Problems implements Iterable<Problem> { - - private List<Problem> problems; - - public Problems() { - } - - public void addError( I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.ERROR, Problem.DEFAULT_CODE, message, params)); - } - - public void addError( Throwable throwable, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.ERROR, Problem.DEFAULT_CODE, message, null, null, throwable)); - } - - public void addError( I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.ERROR, Problem.DEFAULT_CODE, message, resource, location)); - } - - public void addError( Throwable throwable, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.ERROR, Problem.DEFAULT_CODE, message, resource, location, throwable)); - } - - public void addError( int code, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.ERROR, code, message)); - } - - public void addError( Throwable throwable, int code, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.ERROR, code, message, null, null, throwable)); - } - - public void addError( int code, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.ERROR, code, message, resource, location)); - } - - public void addError( Throwable throwable, int code, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.ERROR, code, message, resource, location, throwable)); - } - - public void addWarning( I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.WARNING, Problem.DEFAULT_CODE, message)); - } - - public void addWarning( Throwable throwable, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.WARNING, Problem.DEFAULT_CODE, message, null, null, throwable)); - } - - public void addWarning( I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.WARNING, Problem.DEFAULT_CODE, message, resource, location)); - } - - public void addWarning( Throwable throwable, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.WARNING, Problem.DEFAULT_CODE, message, resource, location, throwable)); - } - - public void addWarning( int code, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.WARNING, code, message)); - } - - public void addWarning( Throwable throwable, int code, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.WARNING, code, message, null, null, throwable)); - } - - public void addWarning( int code, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.WARNING, code, message, resource, location)); - } - - public void addWarning( Throwable throwable, int code, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.WARNING, code, message, resource, location, throwable)); - } - - public void addInfo( I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.INFO, Problem.DEFAULT_CODE, message)); - } - - public void addInfo( Throwable throwable, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.INFO, Problem.DEFAULT_CODE, message, null, null, throwable)); - } - - public void addInfo( I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.INFO, Problem.DEFAULT_CODE, message, resource, location)); - } - - public void addInfo( Throwable throwable, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.INFO, Problem.DEFAULT_CODE, message, resource, location, throwable)); - } - - public void addInfo( int code, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.INFO, code, message)); - } - - public void addInfo( Throwable throwable, int code, I18n message, Object... params ) { - addProblem(new Problem(Problem.Status.INFO, code, message, null, null, throwable)); - } - - public void addInfo( int code, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.INFO, code, message, resource, location)); - } - - public void addInfo( Throwable throwable, int code, I18n message, String resource, String location, Object... params ) { - addProblem(new Problem(Problem.Status.INFO, code, message, resource, location, throwable)); - } - - public boolean hasProblems() { - return this.problems != null && this.problems.size() > 0; - } - - public boolean hasErrors() { - if (this.problems == null) return false; - for (Problem problem : this.problems) { - if (problem.getStatus() == Problem.Status.ERROR) return true; - } - return false; - } - - public boolean hasWarnings() { - if (this.problems == null) return false; - for (Problem problem : this.problems) { - if (problem.getStatus() == Problem.Status.WARNING) return true; - } - return false; - } - - public boolean hasInfo() { - if (this.problems == null) return false; - for (Problem problem : this.problems) { - if (problem.getStatus() == Problem.Status.INFO) return true; - } - return false; - } - - public boolean isEmpty() { - return this.problems == null || this.problems.isEmpty(); - } - - public int size() { - if (this.problems == null) return 0; - return this.problems.size(); - } - - /** - * {@inheritDoc} - */ - public Iterator<Problem> iterator() { - return problems.iterator(); - } - - protected void addProblem( Problem problem ) { - if (problem == null) return; - if (problems == null) problems = new LinkedList<Problem>(); - problems.add(problem); - } - -} Added: trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java (rev 0) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java 2008-06-10 22:16:01 UTC (rev 260) @@ -0,0 +1,154 @@ +/* + * + */ +package org.jboss.dna.common.collection; + +import java.util.Iterator; +import org.jboss.dna.common.i18n.I18n; + +/** + * @author John Verhaeg + */ +public interface Problems extends Iterable<Problem> { + + void addError( I18n message, + Object... params ); + + void addError( Throwable throwable, + I18n message, + Object... params ); + + void addError( I18n message, + String resource, + String location, + Object... params ); + + void addError( Throwable throwable, + I18n message, + String resource, + String location, + Object... params ); + + void addError( int code, + I18n message, + Object... params ); + + void addError( Throwable throwable, + int code, + I18n message, + Object... params ); + + void addError( int code, + I18n message, + String resource, + String location, + Object... params ); + + void addError( Throwable throwable, + int code, + I18n message, + String resource, + String location, + Object... params ); + + void addWarning( I18n message, + Object... params ); + + void addWarning( Throwable throwable, + I18n message, + Object... params ); + + void addWarning( I18n message, + String resource, + String location, + Object... params ); + + void addWarning( Throwable throwable, + I18n message, + String resource, + String location, + Object... params ); + + void addWarning( int code, + I18n message, + Object... params ); + + void addWarning( Throwable throwable, + int code, + I18n message, + Object... params ); + + void addWarning( int code, + I18n message, + String resource, + String location, + Object... params ); + + void addWarning( Throwable throwable, + int code, + I18n message, + String resource, + String location, + Object... params ); + + void addInfo( I18n message, + Object... params ); + + void addInfo( Throwable throwable, + I18n message, + Object... params ); + + void addInfo( I18n message, + String resource, + String location, + Object... params ); + + void addInfo( Throwable throwable, + I18n message, + String resource, + String location, + Object... params ); + + void addInfo( int code, + I18n message, + Object... params ); + + void addInfo( Throwable throwable, + int code, + I18n message, + Object... params ); + + void addInfo( int code, + I18n message, + String resource, + String location, + Object... params ); + + void addInfo( Throwable throwable, + int code, + I18n message, + String resource, + String location, + Object... params ); + + boolean hasProblems(); + + boolean hasErrors(); + + boolean hasWarnings(); + + boolean hasInfo(); + + boolean isEmpty(); + + int size(); + + /** + * <p> + * {@inheritDoc} + * </p> + * + * @see java.lang.Iterable#iterator() + */ + Iterator<Problem> iterator(); +} Property changes on: trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java ___________________________________________________________________ Name: svn:mime-type + text/plain Copied: trunk/dna-common/src/main/java/org/jboss/dna/common/collection/SimpleProblems.java (from rev 251, trunk/dna-common/src/main/java/org/jboss/dna/common/collection/Problems.java) =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/collection/SimpleProblems.java (rev 0) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/collection/SimpleProblems.java 2008-06-10 22:16:01 UTC (rev 260) @@ -0,0 +1,263 @@ +/* + * JBoss, Home of Professional Open Source. + * Copyright 2008, Red Hat Middleware LLC, and individual contributors + * as indicated by the @author tags. See the copyright.txt file in the + * distribution for a full listing of individual contributors. + * + * This is free software; you can redistribute it and/or modify it + * under the terms of the GNU Lesser General Public License as + * published by the Free Software Foundation; either version 2.1 of + * the License, or (at your option) any later version. + * + * This software is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this software; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA, or see the FSF site: http://www.fsf.org. + */ +package org.jboss.dna.common.collection; + +import java.util.Iterator; +import java.util.LinkedList; +import java.util.List; +import net.jcip.annotations.NotThreadSafe; +import org.jboss.dna.common.i18n.I18n; + +/** + * A list of problems for some execution context. The problems will be {@link #iterator() returned} in the order in which they + * were encountered (although this cannot be guaranteed in contexts involving multiple threads or processes). + * + * @author Randall Hauch + * @author John Verhaeg + */ +@NotThreadSafe +public class SimpleProblems implements Problems { + + private List<Problem> problems; + + public void addError( I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.ERROR, Problem.DEFAULT_CODE, message, params)); + } + + public void addError( Throwable throwable, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.ERROR, Problem.DEFAULT_CODE, message, null, null, throwable)); + } + + public void addError( I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.ERROR, Problem.DEFAULT_CODE, message, resource, location)); + } + + public void addError( Throwable throwable, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.ERROR, Problem.DEFAULT_CODE, message, resource, location, throwable)); + } + + public void addError( int code, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.ERROR, code, message)); + } + + public void addError( Throwable throwable, + int code, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.ERROR, code, message, null, null, throwable)); + } + + public void addError( int code, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.ERROR, code, message, resource, location)); + } + + public void addError( Throwable throwable, + int code, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.ERROR, code, message, resource, location, throwable)); + } + + public void addWarning( I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.WARNING, Problem.DEFAULT_CODE, message)); + } + + public void addWarning( Throwable throwable, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.WARNING, Problem.DEFAULT_CODE, message, null, null, throwable)); + } + + public void addWarning( I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.WARNING, Problem.DEFAULT_CODE, message, resource, location)); + } + + public void addWarning( Throwable throwable, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.WARNING, Problem.DEFAULT_CODE, message, resource, location, throwable)); + } + + public void addWarning( int code, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.WARNING, code, message)); + } + + public void addWarning( Throwable throwable, + int code, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.WARNING, code, message, null, null, throwable)); + } + + public void addWarning( int code, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.WARNING, code, message, resource, location)); + } + + public void addWarning( Throwable throwable, + int code, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.WARNING, code, message, resource, location, throwable)); + } + + public void addInfo( I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.INFO, Problem.DEFAULT_CODE, message)); + } + + public void addInfo( Throwable throwable, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.INFO, Problem.DEFAULT_CODE, message, null, null, throwable)); + } + + public void addInfo( I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.INFO, Problem.DEFAULT_CODE, message, resource, location)); + } + + public void addInfo( Throwable throwable, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.INFO, Problem.DEFAULT_CODE, message, resource, location, throwable)); + } + + public void addInfo( int code, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.INFO, code, message)); + } + + public void addInfo( Throwable throwable, + int code, + I18n message, + Object... params ) { + addProblem(new Problem(Problem.Status.INFO, code, message, null, null, throwable)); + } + + public void addInfo( int code, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.INFO, code, message, resource, location)); + } + + public void addInfo( Throwable throwable, + int code, + I18n message, + String resource, + String location, + Object... params ) { + addProblem(new Problem(Problem.Status.INFO, code, message, resource, location, throwable)); + } + + public boolean hasProblems() { + return this.problems != null && this.problems.size() > 0; + } + + public boolean hasErrors() { + if (this.problems == null) return false; + for (Problem problem : this.problems) { + if (problem.getStatus() == Problem.Status.ERROR) return true; + } + return false; + } + + public boolean hasWarnings() { + if (this.problems == null) return false; + for (Problem problem : this.problems) { + if (problem.getStatus() == Problem.Status.WARNING) return true; + } + return false; + } + + public boolean hasInfo() { + if (this.problems == null) return false; + for (Problem problem : this.problems) { + if (problem.getStatus() == Problem.Status.INFO) return true; + } + return false; + } + + public boolean isEmpty() { + return this.problems == null || this.problems.isEmpty(); + } + + public int size() { + if (this.problems == null) return 0; + return this.problems.size(); + } + + /** + * <p> + * {@inheritDoc} + * </p> + * + * @see org.jboss.dna.common.collection.Problems#iterator() + */ + public Iterator<Problem> iterator() { + return problems.iterator(); + } + + protected void addProblem( Problem problem ) { + if (problem == null) return; + if (problems == null) problems = new LinkedList<Problem>(); + problems.add(problem); + } +} Modified: trunk/dna-common/src/main/java/org/jboss/dna/common/collection/UnmodifiableProperties.java =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/collection/UnmodifiableProperties.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/collection/UnmodifiableProperties.java 2008-06-10 22:16:01 UTC (rev 260) @@ -106,7 +106,8 @@ * {@inheritDoc} */ @Override - public String getProperty( String key, String defaultValue ) { + public String getProperty( String key, + String defaultValue ) { return this.delegate.getProperty(key, defaultValue); } @@ -168,11 +169,13 @@ /** * {@inheritDoc} + * * @deprecated */ @Deprecated @Override - public void save( OutputStream out, String comments ) { + public void save( OutputStream out, + String comments ) { this.delegate.save(out, comments); } @@ -188,7 +191,8 @@ * {@inheritDoc} */ @Override - public void store( OutputStream out, String comments ) throws IOException { + public void store( OutputStream out, + String comments ) throws IOException { this.delegate.store(out, comments); } @@ -196,7 +200,9 @@ * {@inheritDoc} */ @Override - public void storeToXML( OutputStream os, String comment, String encoding ) throws IOException { + public void storeToXML( OutputStream os, + String comment, + String encoding ) throws IOException { this.delegate.storeToXML(os, comment, encoding); } @@ -204,7 +210,8 @@ * {@inheritDoc} */ @Override - public void storeToXML( OutputStream os, String comment ) throws IOException { + public void storeToXML( OutputStream os, + String comment ) throws IOException { this.delegate.storeToXML(os, comment); } @@ -268,7 +275,8 @@ * {@inheritDoc} */ @Override - public synchronized Object put( Object key, Object value ) { + public synchronized Object put( Object key, + Object value ) { throw new UnsupportedOperationException(); } @@ -292,7 +300,8 @@ * {@inheritDoc} */ @Override - public synchronized Object setProperty( String key, String value ) { + public synchronized Object setProperty( String key, + String value ) { throw new UnsupportedOperationException(); } Deleted: trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/NullProgressMonitor.java =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/NullProgressMonitor.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/NullProgressMonitor.java 2008-06-10 22:16:01 UTC (rev 260) @@ -1,100 +0,0 @@ -/* - * JBoss, Home of Professional Open Source. - * Copyright 2008, Red Hat Middleware LLC, and individual contributors - * as indicated by the @author tags. See the copyright.txt file in the - * distribution for a full listing of individual contributors. - * - * This is free software; you can redistribute it and/or modify it - * under the terms of the GNU Lesser General Public License as - * published by the Free Software Foundation; either version 2.1 of - * the License, or (at your option) any later version. - * - * This software is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - * Lesser General Public License for more details. - * - * You should have received a copy of the GNU Lesser General Public - * License along with this software; if not, write to the Free - * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA - * 02110-1301 USA, or see the FSF site: http://www.fsf.org. - */ - -package org.jboss.dna.common.monitor; - -import java.util.Locale; -import java.util.concurrent.atomic.AtomicBoolean; -import org.jboss.dna.common.CommonI18n; -import org.jboss.dna.common.i18n.I18n; -import net.jcip.annotations.ThreadSafe; - -/** - * Progress monitor that records nothing. - * @author Randall Hauch - */ -@ThreadSafe -public class NullProgressMonitor implements ProgressMonitor { - - private final AtomicBoolean cancelled = new AtomicBoolean(false); - private final String activityName; - - public NullProgressMonitor( String activityName ) { - this.activityName = activityName; - } - - /** - * {@inheritDoc} - */ - public String getActivityName() { - return this.activityName; - } - - /** - * {@inheritDoc} - */ - public void beginTask( double totalWork, I18n name, Object... params ) { - // do nothing - } - - /** - * {@inheritDoc} - */ - public ProgressMonitor createSubtask( double subtaskWork ) { - return this; - } - - /** - * {@inheritDoc} - */ - public void done() { - // do nothing - } - - /** - * {@inheritDoc} - */ - public boolean isCancelled() { - return cancelled.get(); - } - - /** - * {@inheritDoc} - */ - public void setCancelled( boolean value ) { - cancelled.set(value); - } - - /** - * {@inheritDoc} - */ - public void worked( double work ) { - // do nothing - } - - /** - * {@inheritDoc} - */ - public ProgressStatus getStatus( Locale locale ) { - return new ProgressStatus(this.activityName, CommonI18n.nullProgressMonitorTaskName.text(locale), 0.0d, cancelled.get()); - } -} Modified: trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/ProgressMonitor.java =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/ProgressMonitor.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/ProgressMonitor.java 2008-06-10 22:16:01 UTC (rev 260) @@ -23,63 +23,92 @@ package org.jboss.dna.common.monitor; import java.util.Locale; +import org.jboss.dna.common.collection.Problems; import org.jboss.dna.common.i18n.I18n; /** - * A basic progress monitor that facilitates the monitoring of an activity. + * A basic progress monitor that facilitates the updating and monitoring of progress towards the completion of an activity. + * Documentation hereafter will refer to the code in an application that updates progress as the <strong>Updater</strong>, and + * code that monitors progress as an <strong>Observer</strong>. * <p> - * The progress of each activity is started when {@link #beginTask(double, I18n, Object...)} is called, continues with a mixture - * of work ({@link #worked(double)}) and subtasks ({@link #createSubtask(double)}), and finishes when the activity is - * completed ({@link #done()}) or cancelled ({@link #setCancelled(boolean)}). + * The progress of each {@link #getActivityName() activity} is started when the <strong>Updater</strong> calls + * {@link #beginTask(double, I18n, Object...)}, continues with a mixture of work ({@link #worked(double)}) and subtasks ({@link #createSubtask(double)}), + * and finishes when the activity is completed ({@link #done()}) or cancelled ({@link #setCancelled(boolean)}). * </p> + * <p> + * If an activity is interrupted before its normal completion due to a cancellation request by an <strong>Observer</strong>, it + * is still the responsibility of the <strong>Updater</strong> to mark the activity as completed. Similarly, if an activity + * cannot be cancelled before its normal completion, the <strong>Updater</strong> must deny any previous cancellation request by + * calling {@link #setCancelled(boolean) setCancelled(false)}. + * </p> + * * @author Randall Hauch + * @author John Verhaeg */ public interface ProgressMonitor { /** * Get the name of the activity. This should never change for a progress monitor, and all * {@link #createSubtask(double) subtasks} should have the same name. + * * @return the activity's name */ String getActivityName(); /** - * Start work on the task, specifying the total amount of work that this task constitutes. + * Called by the <strong>Updater</strong> to indicate work has started on the task, specifying the total amount of work that + * this task constitutes. + * * @param totalWork the total number of work units for the task * @param name the name of the task * @param params the parameters for localization */ - void beginTask( double totalWork, I18n name, Object... params ); + void beginTask( double totalWork, + I18n name, + Object... params ); /** - * Report work completed for this task. + * Called by the <strong>Updater</strong> to report work completed for this task. + * * @param work the number of work units that have been worked */ void worked( double work ); /** - * Create a subtask with the given about of work. The resulting monitor must be started ({@link #beginTask(double, I18n, Object...)}) - * and finished ({@link #done()}). + * Called by the <strong>Updater</strong> to create a subtask with the given about of work. The resulting progress monitor + * must be started ({@link #beginTask(double, I18n, Object...)}) and finished ({@link #done()}). + * * @param subtaskWork the number of work units for this subtask * @return the progress monitor for the subtask */ ProgressMonitor createSubtask( double subtaskWork ); /** - * Mark this task as being completed. This method must be called for the task to be properly completed. + * Called by the <strong>Updater</strong> to mark this activity as complete. This method must be called, even if the activity + * has been cancelled. */ void done(); /** - * Set the cancelled state of this activity. Cancelling the activity must be considered a request that can be denied by - * setting the cancelled state to <code>false</code>. - * @param value true if requesting the activity be cancelled. + * Return whether this activity has completed. + * + * @return <code>true</code> if this activity has completed. */ + boolean isDone(); + + /** + * Called by an <strong>Observer</strong> to request the cancellation of this activity, or by the <strong>Updater</strong> + * to deny a prior cancellation request (i.e., when the activity {@link #done() completes} before the <strong>Updater</strong> + * recognizes a cancellation request by an <strong>Observer</strong>). + * + * @param value <code>true</code> if requesting the activity be cancelled. + */ void setCancelled( boolean value ); /** - * Returned whether this activity has been {@link #setCancelled(boolean) cancelled}. - * @return true if this activity has been requested to be cancelled, or false otherwise. + * Return whether a request was made by an <strong>Observer</strong> to {@link #setCancelled(boolean) cancel} this activity. + * + * @return <code>true</code> if this activity has been requested to be cancelled. */ boolean isCancelled(); @@ -87,9 +116,18 @@ * Return the current status of this activity, localized to the specified locale. This method returns an immutable but * consistent snapshot of the status for this activity. Note that if this instance is a {@link #createSubtask(double) subtask}, * this method returns the status of the subtask. + * * @param locale the locale in which the status is to be represented; if null, the {@link Locale#getDefault() default locale} - * will be used + * will be used * @return the status of this activity */ ProgressStatus getStatus( Locale locale ); + + /** + * Return the problems encountered during the {@link #getStatus(Locale) progress} made towards completing the associated + * {@link #getActivityName() activity}. + * + * @return the list of problems + */ + Problems getProblems(); } Modified: trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/ProgressMonitorWrapper.java =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/ProgressMonitorWrapper.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/ProgressMonitorWrapper.java 2008-06-10 22:16:01 UTC (rev 260) @@ -23,10 +23,14 @@ package org.jboss.dna.common.monitor; import java.util.Locale; +import org.jboss.dna.common.collection.Problems; import org.jboss.dna.common.i18n.I18n; /** + * The thread safety of this class is determined by the delegate. + * * @author Randall Hauch + * @author John Verhaeg */ public class ProgressMonitorWrapper implements ProgressMonitor { @@ -36,67 +40,61 @@ this.delegate = delegate; } - /** - * @return the wrapped progress monitor - */ public ProgressMonitor getWrappedMonitor() { return this.delegate; } - /** - * {@inheritDoc} - */ - public void beginTask( double totalWork, I18n name, Object... params ) { + public void beginTask( double totalWork, + I18n name, + Object... params ) { this.delegate.beginTask(totalWork, name, params); } - /** - * {@inheritDoc} - */ public ProgressMonitor createSubtask( double subtaskWork ) { return this.delegate.createSubtask(subtaskWork); } - /** - * {@inheritDoc} - */ public void done() { this.delegate.done(); } - /** - * {@inheritDoc} - */ public String getActivityName() { return this.delegate.getActivityName(); } - /** - * {@inheritDoc} - */ public ProgressStatus getStatus( Locale locale ) { return this.delegate.getStatus(locale); } /** + * <p> * {@inheritDoc} + * </p> + * + * @see org.jboss.dna.common.monitor.ProgressMonitor#getProblems() */ + public Problems getProblems() { + return delegate.getProblems(); + } + public boolean isCancelled() { return this.delegate.isCancelled(); } /** * {@inheritDoc} + * + * @see org.jboss.dna.common.monitor.ProgressMonitor#isDone() */ + public boolean isDone() { + return delegate.isDone(); + } + public void setCancelled( boolean value ) { this.delegate.setCancelled(value); } - /** - * {@inheritDoc} - */ public void worked( double work ) { this.delegate.worked(work); } - } Modified: trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/SimpleProgressMonitor.java =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/SimpleProgressMonitor.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/SimpleProgressMonitor.java 2008-06-10 22:16:01 UTC (rev 260) @@ -27,14 +27,21 @@ import java.util.concurrent.locks.ReadWriteLock; import java.util.concurrent.locks.ReentrantReadWriteLock; import net.jcip.annotations.GuardedBy; -import net.jcip.annotations.ThreadSafe; +import org.jboss.dna.common.collection.Problems; +import org.jboss.dna.common.collection.SimpleProblems; import org.jboss.dna.common.i18n.I18n; /** - * A basic progress monitor + * A basic progress monitor. + * <p> + * This class is thread-safe except when accessing or adding {@link #getProblems() problems}. Problems must only be added by the + * {@link ProgressMonitor <strong>Updater</strong>}, and accessed by {@link ProgressMonitor Observers} only after the activity + * has been {@link #done() completed}. + * </p> + * * @author Randall Hauch + * @author John Verhaeg */ -@ThreadSafe public class SimpleProgressMonitor implements ProgressMonitor { @GuardedBy( "lock" ) @@ -45,12 +52,11 @@ private double totalWork; @GuardedBy( "lock" ) private double worked; - @GuardedBy( "lock" ) - private boolean done; private final String activityName; private final ReadWriteLock lock = new ReentrantReadWriteLock(); private final AtomicBoolean cancelled = new AtomicBoolean(false); + private final Problems problems = new SimpleProblems(); public SimpleProgressMonitor( String activityName ) { this.activityName = activityName != null ? activityName.trim() : ""; @@ -68,7 +74,9 @@ /** * {@inheritDoc} */ - public void beginTask( double totalWork, I18n name, Object... params ) { + public void beginTask( double totalWork, + I18n name, + Object... params ) { assert totalWork > 0; try { this.lock.writeLock().lock(); @@ -89,13 +97,17 @@ } /** + * <p> * {@inheritDoc} + * </p> + * + * @see org.jboss.dna.common.monitor.ProgressMonitor#done() */ public void done() { boolean alreadyDone = false; try { this.lock.writeLock().lock(); - if (!this.done) { + if (this.worked < this.totalWork) { this.worked = this.totalWork; } else { alreadyDone = true; @@ -115,7 +127,21 @@ /** * {@inheritDoc} + * + * @see org.jboss.dna.common.monitor.ProgressMonitor#isDone() */ + public boolean isDone() { + lock.readLock().lock(); + try { + return worked >= totalWork; + } finally { + lock.readLock().unlock(); + } + } + + /** + * {@inheritDoc} + */ public void setCancelled( boolean value ) { this.cancelled.set(value); } @@ -162,4 +188,17 @@ protected void notifyProgress() { // do nothing } + + /** + * {@inheritDoc} + * <p> + * Problems must only be added by the {@link ProgressMonitor <strong>Updater</strong>}, and accessed by + * {@link ProgressMonitor Observers} only after the activity has been {@link #done() completed}. + * </p> + * + * @see org.jboss.dna.common.monitor.ProgressMonitor#getProblems() + */ + public Problems getProblems() { + return problems; + } } Modified: trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/SubProgressMonitor.java =================================================================== --- trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/SubProgressMonitor.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/main/java/org/jboss/dna/common/monitor/SubProgressMonitor.java 2008-06-10 22:16:01 UTC (rev 260) @@ -25,14 +25,17 @@ import java.util.Locale; import java.util.concurrent.locks.ReadWriteLock; import java.util.concurrent.locks.ReentrantReadWriteLock; +import net.jcip.annotations.GuardedBy; +import org.jboss.dna.common.collection.Problems; import org.jboss.dna.common.i18n.I18n; -import net.jcip.annotations.GuardedBy; -import net.jcip.annotations.NotThreadSafe; /** + * This class is thread-safe except when accessing or adding {@link #getProblems() problems}. Problems must only be added by the + * {@link ProgressMonitor <strong>Updater</strong>}, and accessed by {@link ProgressMonitor Observers} only after the activity + * has been {@link #done() completed}. + * * @author Randall Hauch */ -@NotThreadSafe public class SubProgressMonitor implements ProgressMonitor { @GuardedBy( "lock" ) @@ -50,7 +53,8 @@ private final ProgressMonitor parent; private final ReadWriteLock lock = new ReentrantReadWriteLock(); - public SubProgressMonitor( final ProgressMonitor parent, final double subtaskTotalInParent ) { + public SubProgressMonitor( final ProgressMonitor parent, + final double subtaskTotalInParent ) { assert subtaskTotalInParent > 0; assert parent != null; this.parent = parent; @@ -74,7 +78,9 @@ /** * {@inheritDoc} */ - public void beginTask( double totalWork, I18n name, Object... params ) { + public void beginTask( double totalWork, + I18n name, + Object... params ) { assert totalWork > 0; try { this.lock.writeLock().lock(); @@ -120,7 +126,16 @@ /** * {@inheritDoc} + * + * @see org.jboss.dna.common.monitor.ProgressMonitor#isDone() */ + public boolean isDone() { + return parent.isDone(); + } + + /** + * {@inheritDoc} + */ public void setCancelled( boolean value ) { this.parent.setCancelled(value); } @@ -150,9 +165,19 @@ public ProgressStatus getStatus( Locale locale ) { try { this.lock.readLock().lock(); - return new ProgressStatus(this.getActivityName(), this.taskName.text(locale, this.params), this.submittedToParent, this.subtaskTotalInParent, this.isCancelled()); + return new ProgressStatus(this.getActivityName(), this.taskName.text(locale, this.params), this.submittedToParent, + this.subtaskTotalInParent, this.isCancelled()); } finally { this.lock.readLock().unlock(); } } + + /** + * {@inheritDoc} + * + * @see org.jboss.dna.common.monitor.ProgressMonitor#getProblems() + */ + public Problems getProblems() { + return parent.getProblems(); + } } Modified: trunk/dna-common/src/test/java/org/jboss/dna/common/component/ComponentLibraryTest.java =================================================================== --- trunk/dna-common/src/test/java/org/jboss/dna/common/component/ComponentLibraryTest.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/test/java/org/jboss/dna/common/component/ComponentLibraryTest.java 2008-06-10 22:16:01 UTC (rev 260) @@ -28,13 +28,15 @@ import static org.hamcrest.core.IsSame.sameInstance; import static org.junit.Assert.assertThat; import java.util.List; -import org.jboss.dna.common.monitor.NullProgressMonitor; import org.jboss.dna.common.monitor.ProgressMonitor; import org.junit.Before; import org.junit.Test; +import org.mockito.MockitoAnnotations; +import org.mockito.MockitoAnnotations.Mock; /** * @author Randall Hauch + * @author John Verhaeg */ public class ComponentLibraryTest { @@ -44,10 +46,12 @@ private SampleComponentConfig configA2; private String validDescription; private String[] validClasspath; - private ProgressMonitor nullMonitor = new NullProgressMonitor(ComponentLibraryTest.class.getName()); + @Mock + private ProgressMonitor nullMonitor; @Before - public void beforeEach() throws Exception { + public void beforeEach() { + MockitoAnnotations.initMocks(this); this.library = new ComponentLibrary<SampleComponent, SampleComponentConfig>(); this.validDescription = "a Component"; this.validClasspath = new String[] {"com.acme:configA:1.0,com.acme:configB:1.0"}; Modified: trunk/dna-common/src/test/java/org/jboss/dna/common/monitor/SimpleProgressMonitorTest.java =================================================================== --- trunk/dna-common/src/test/java/org/jboss/dna/common/monitor/SimpleProgressMonitorTest.java 2008-06-10 22:05:23 UTC (rev 259) +++ trunk/dna-common/src/test/java/org/jboss/dna/common/monitor/SimpleProgressMonitorTest.java 2008-06-10 22:16:01 UTC (rev 260) @@ -22,14 +22,14 @@ package org.jboss.dna.common.monitor; -import java.util.Locale; -import java.util.Set; import static org.hamcrest.core.Is.is; import static org.hamcrest.core.IsInstanceOf.instanceOf; import static org.hamcrest.core.IsNull.notNullValue; import static org.hamcrest.core.IsSame.sameInstance; import static org.hamcrest.number.IsCloseTo.closeTo; import static org.junit.Assert.assertThat; +import java.util.Locale; +import java.util.Set; import org.jboss.dna.common.CommonI18n; import org.jboss.dna.common.i18n.I18n; import org.jboss.dna.common.i18n.MockI18n; @@ -38,6 +38,7 @@ /** * @author Randall Hauch + * @author John Verhaeg */ public class SimpleProgressMonitorTest { @@ -46,7 +47,7 @@ private String validTaskName; @Before - public void beforeEach() throws Exception { + public void beforeEach() { this.validActivityName = "Reading from file X"; this.validTaskName = "Checking for file"; this.monitor = new SimpleProgressMonitor(this.validActivityName); @@ -246,7 +247,10 @@ @Test public void shouldNotBeMarkedAsDoneAfterCancel() { - + monitor.beginTask(100, MockI18n.passthrough, validTaskName); + monitor.setCancelled(true); + assertThat(monitor.isCancelled(), is(true)); + assertThat(monitor.isDone(), is(false)); } @Test @@ -317,6 +321,14 @@ assertThat(monitor.isCancelled(), is(true)); } + @Test + public void shouldRecordProblems() { + monitor.beginTask(1000, MockI18n.passthrough, validTaskName); + monitor.getProblems().addWarning(MockI18n.passthrough); + monitor.done(); + assertThat(monitor.getProblems().hasWarnings(), is(true)); + } + public static class I18nMessages { public static I18n testTaskName;