1 /*
   2  * $Id$
   3  *
   4  * Copyright (c) 1996, 2009, Oracle and/or its affiliates. All rights reserved.
   5  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6  *
   7  * This code is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License version 2 only, as
   9  * published by the Free Software Foundation.  Oracle designates this
  10  * particular file as subject to the "Classpath" exception as provided
  11  * by Oracle in the LICENSE file that accompanied this code.
  12  *
  13  * This code is distributed in the hope that it will be useful, but WITHOUT
  14  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  15  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16  * version 2 for more details (a copy is included in the LICENSE file that
  17  * accompanied this code).
  18  *
  19  * You should have received a copy of the GNU General Public License version
  20  * 2 along with this work; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  22  *
  23  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  24  * or visit www.oracle.com if you need additional information or have any
  25  * questions.
  26  */
  27 package com.sun.javatest;
  28 
  29 import java.util.Iterator;
  30 
  31 import com.sun.javatest.util.BackupPolicy;
  32 
  33 /**
  34  * TestRunner is the abstract base class providing the ability to
  35  * control how tests are run. A default is provided that executes
  36  * each test by means of a script class.
  37  * <p>If a test suite does not wish tom use the default test runner,
  38  * it should provide its own implementation of this class. The primary
  39  * method which should be implemented is {@link #runTests}.
  40  */
  41 public abstract class TestRunner
  42 {
  43     /**
  44      * Set the work directory used to store the test results generated
  45      * by this test runner.
  46      * @param wd the work directory used to store the test results generated
  47      * by this test runner
  48      * @see #getWorkDirectory
  49      */
  50     void setWorkDirectory(WorkDirectory wd) {
  51         workDir = wd;
  52     }
  53 
  54     /**
  55      * Get the work directory to be used to store the test results generated
  56      * by this test runner.
  57      * @return the work directory used to store the test results generated
  58      * by this test runner
  59      */
  60     public WorkDirectory getWorkDirectory() {
  61         return workDir;
  62     }
  63 
  64     /**
  65      * Get the test suite containing the tests to be run by this test runner.
  66      * @return  the test suite containing the tests to be run by this test runner
  67      */
  68     public TestSuite getTestSuite() {
  69         return workDir.getTestSuite();
  70     }
  71 
  72     /**
  73      * Set the backup policy to be used when creating the test result files
  74      * generated by this test runner.
  75      * @param backupPolicy the backup policy to be used when creating the
  76      * test result files generated by this test runner
  77      * @see #getBackupPolicy
  78      * @see TestResult#writeResults(WorkDirectory, BackupPolicy)
  79      */
  80     void setBackupPolicy(BackupPolicy backupPolicy) {
  81         this.backupPolicy = backupPolicy;
  82     }
  83 
  84     /**
  85      * Get the backup policy to be used when creating the test result files
  86      * generated by this test runner.
  87      * @return the backup policy to be used when creating the
  88      * test result files generated by this test runner
  89      * @see TestResult#writeResults(WorkDirectory, BackupPolicy)
  90      */
  91     public BackupPolicy getBackupPolicy() {
  92         return backupPolicy;
  93     }
  94 
  95     /**
  96      * Set the test environment to be used to execute the tests that will
  97      * be run by this test runner.
  98      * @param env the test environment to be used to execute the tests that will
  99      * be run by this test runner
 100      * @see #getEnvironment
 101      */
 102     void setEnvironment(TestEnvironment env) {
 103         this.env = env;
 104     }
 105 
 106     /**
 107      * Get the test environment to be used to execute the tests that will
 108      * be run by this test runner.
 109      * @return the test environment to be used to execute the tests that will
 110      * be run by this test runner
 111      * @see #getEnvironment
 112      */
 113     public TestEnvironment getEnvironment() {
 114         return env;
 115     }
 116 
 117     /**
 118      * Set the exclude list to be used to identify the test cases to be
 119      * excluded when running tests.
 120      * @param excludeList the exclude list to be used to identify the test cases to be
 121      * excluded when running tests
 122      * @see #getExcludeList
 123      * @see #getExcludedTestCases
 124      */
 125     void setExcludeList(ExcludeList excludeList) {
 126         this.excludeList = excludeList;
 127     }
 128 
 129     /**
 130      * Get the exclude list to be used to identify the test cases to be
 131      * excluded when running tests.
 132      * @return the exclude list to be used to identify the test cases to be
 133      * excluded when running tests
 134      * @see #getExcludedTestCases
 135      */
 136     public ExcludeList getExcludeList() {
 137         return excludeList;
 138     }
 139 
 140     /**
 141      * Get the names of the test cases to be excluded when running a specific test.
 142      * @param td the test for which the excluded test cases should be obtained
 143      * @return the names of the test cases to be excluded when running a specific test.
 144      * The result is null if the test is not found or is
 145      * completely excluded without specifying test cases.  This may be
 146      * a mix of single TC strings or a comma separated list of them.
 147      */
 148     public String[] getExcludedTestCases(TestDescription td) {
 149         return excludeList.getTestCases(td);
 150     }
 151 
 152     /**
 153      * Set the concurrency to be used when running the tests, if applicable.
 154      * @param conc the concurrency to be used when running the tests, if applicable
 155      * @see #getConcurrency
 156      */
 157     void setConcurrency(int conc) {
 158         concurrency = conc;
 159     }
 160 
 161     /**
 162      * Get the concurrency to be used when running the tests, if applicable.
 163      * @return the concurrency to be used when running the tests, if applicable
 164      * @see #getConcurrency
 165      */
 166     public int getConcurrency() {
 167         return concurrency;
 168     }
 169 
 170 
 171     /**
 172      * Set the notifier to be used when running the tests.
 173      * @param notifier the notifier to be used when running the tests
 174      * @see #notifyStartingTest
 175      * @see #notifyFinishedTest
 176      */
 177     void setNotifier(Harness.Observer notifier) {
 178         this.notifier = notifier;
 179     }
 180 
 181     /**
 182      * Delegate the notifier to be used when running the tests to the Script
 183      * @param script the script to be used to execute the test
 184      */
 185     void delegateNotifier(Script script) {
 186         script.setNotifier(this.notifier);
 187     }
 188 
 189     /**
 190      * Run the tests obtained from an iterator. The iterator returns
 191      * TestDescription objects for the tests that have been selected to be run.
 192      * The iterator supports the standard hasNext() and next() methods;
 193      * it does not support remove(), which throws UnsupportedOperationException.
 194      * Each test description gives the details of the test to be run.
 195      * As each test is started, the implementation of this method must create
 196      * a new TestResult object and call {@link #notifyStartingTest}.
 197      * When the test completes (however it completes) the implementation of
 198      * this method must call {@link #notifyFinishedTest}.
 199      * @param testIter the iterator to be used to obtain the tests to be run
 200      * @return true if and only if all the tests executed successfully and passed
 201      * @throws InterruptedException if the test run was interrupted
 202      */
 203     protected abstract boolean runTests(Iterator<TestDescription> testIter) throws InterruptedException;
 204 
 205     /**
 206      * This method must be called as each test is started, to notify any
 207      * registered observers.
 208      * @param tr the TestResult object for the test that has been started
 209      * @see Harness.Observer
 210      */
 211     protected void notifyStartingTest(TestResult tr) {
 212         notifier.startingTest(tr);
 213     }
 214 
 215     /**
 216      * This method must be called when each test is finished, to notify any
 217      * registered observers.
 218      * @param tr the TestResult object for the test that has been started
 219      * @see Harness.Observer
 220      */
 221     protected void notifyFinishedTest(TestResult tr) {
 222         // this must do the following:
 223         // numTestsDone++;
 224         // resultTable.update(result);
 225         // notify observers
 226         notifier.finishedTest(tr);
 227     }
 228 
 229     private WorkDirectory workDir;
 230     private BackupPolicy backupPolicy;
 231     private TestEnvironment env;
 232     private ExcludeList excludeList;
 233     private int concurrency;
 234     private Harness.Observer notifier;
 235 }