1 // Copyright (C) 2006 - 2008 Philip Aston
2 // All rights reserved.
3 //
4 // This file is part of The Grinder software distribution. Refer to
5 // the file LICENSE which is part of The Grinder distribution for
6 // licensing details. The Grinder distribution is available on the
7 // Internet at http://grinder.sourceforge.net/
8 //
9 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
10 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
11 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
12 // FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
13 // COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
14 // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
15 // (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
16 // SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
17 // HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
18 // STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
19 // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
20 // OF THE POSSIBILITY OF SUCH DAMAGE.
21
22 package net.grinder.engine.process;
23
24 import net.grinder.common.Test;
25 import net.grinder.engine.common.EngineException;
26 import net.grinder.script.Statistics.StatisticsForTest;
27
28 import org.slf4j.Marker;
29
30
31 /**
32 * Access state related to a particular dispatch of a test by a worker thread.
33 *
34 * @author Philip Aston
35 */
36 interface DispatchContext {
37
38 /**
39 * The test.
40 *
41 * @return The test that this dispatch is for.
42 */
43 Test getTest();
44
45 /**
46 * Return an SLF4J marker indicating the test.
47 *
48 * @return The marker.
49 */
50 Marker getLogMarker();
51
52 /**
53 * Creates a {@link net.grinder.script.Statistics.StatisticsForTest} through
54 * which the script can query and update the statistics. The statistics are
55 * only mutable update until the next time {@link #report()} is called; after
56 * that time the {@link net.grinder.script.Statistics.StatisticsForTest} is
57 * disassociated from this {@link DispatchContext} and the statistics are
58 * read-only.
59 *
60 * @return The handle the script uses to update the statistics, or
61 * <code>null</code> if there currently is no test in progress.
62 */
63 StatisticsForTest getStatisticsForTest();
64
65 /**
66 * Report any pending statistics.
67 *
68 * @throws DispatchStateException If there are no statistics to report.
69 */
70 void report() throws DispatchStateException;
71
72 /**
73 * Return a {@link StopWatch} which can be started and stopped around
74 * code that should not contribute to the elapsed time measurement.
75 *
76 * @return The stop watch.
77 */
78 StopWatch getPauseTimer();
79
80 /**
81 * If there is a test in progress, return the elapsed time since the
82 * start of the test. If a test has been completed, but not reported, return
83 * the test time. Otherwise return -1.
84 *
85 * @return The elapsed time for the test.
86 */
87 long getElapsedTime();
88
89 /**
90 * Set that this <code>DispatchContext</code> has nested contexts.
91 */
92 void setHasNestedContexts();
93
94 /**
95 * Exception that indicates the dispatcher was in an invalid state for
96 * the called method .
97 */
98 static class DispatchStateException extends EngineException {
99 DispatchStateException(String message) {
100 super(message);
101 }
102 }
103 }