1 // Copyright (C) 2005 - 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.statistics;
23
24
25 /**
26 * Factory for StatisticExpressions.
27 *
28 * @author Philip Aston
29 */
30 public interface StatisticExpressionFactory {
31
32 /**
33 * Apply standard formatting to an expression.
34 *
35 * @param expression The expression.
36 * @return The formatted expression.
37 * @exception StatisticsException If the expression is invalid.
38 */
39 String normaliseExpressionString(String expression)
40 throws StatisticsException;
41
42 /**
43 * Parse an expression.
44 *
45 * @param expression The expression.
46 * @return The parsed expression.
47 * @exception StatisticsException If the expression is invalid.
48 */
49 StatisticExpression createExpression(String expression)
50 throws StatisticsException;
51
52 /**
53 * Create a constant long expression.
54 *
55 * @param value The value.
56 * @return The <code>StatisticExpression</code>.
57 */
58 StatisticExpression createConstant(long value);
59
60 /**
61 * Create a constant float expression.
62 *
63 * @param value The value.
64 * @return The <code>StatisticExpression</code>.
65 */
66 StatisticExpression createConstant(double value);
67
68 /**
69 * Create a primitive double expression.
70 *
71 * @param index The expression index.
72 * @return The <code>StatisticExpression</code>.
73 */
74 StatisticExpression createPrimitive(StatisticsIndexMap.DoubleIndex index);
75
76 /**
77 * Create a primitive long expression.
78 *
79 * @param index The expression index.
80 * @return The <code>StatisticExpression</code>.
81 */
82 StatisticExpression createPrimitive(StatisticsIndexMap.LongIndex index);
83
84 /**
85 * Create a sum.
86 *
87 * @param operands The things to add.
88 * @return The resulting expression.
89 */
90 StatisticExpression createSum(StatisticExpression[] operands);
91
92 /**
93 * Create a negation.
94 *
95 * @param operand The thing to negate.
96 * @return The resulting expression.
97 */
98 StatisticExpression createNegation(StatisticExpression operand);
99
100 /**
101 * Create a minus expression. The result is the first argument less the
102 * sum of the remaining arguments.
103 *
104 * @param firstOperand The first argument.
105 * @param otherOperands The remaining arguments.
106 * @return The resulting expression.
107 */
108 StatisticExpression createMinus(StatisticExpression firstOperand,
109 StatisticExpression[] otherOperands);
110
111 /**
112 * Create a product.
113 *
114 * @param operands The things to multiply.
115 * @return The resulting expression.
116 */
117 StatisticExpression createProduct(StatisticExpression[] operands);
118
119 /**
120 * Create a division.
121 *
122 * @param numerator The numerator.
123 * @param denominator The denominator.
124 * @return The resulting expression.
125 */
126 StatisticExpression createDivision(StatisticExpression numerator,
127 StatisticExpression denominator);
128
129 /**
130 * Create a square root.
131 *
132 * @param operand The operand.
133 * @return The resulting expression.
134 */
135 StatisticExpression createSquareRoot(StatisticExpression operand);
136
137 /**
138 * Create a peak double statistic.
139 *
140 * @param peakIndex Index of a slot to store peak information in.
141 * @param monitoredStatistic Statistic to monitor.
142 * @return The resulting expression.
143 */
144 PeakStatisticExpression createPeak(StatisticsIndexMap.DoubleIndex peakIndex,
145 StatisticExpression monitoredStatistic);
146
147 /**
148 * Create a peak long statistic.
149 *
150 * @param peakIndex Index of a slot to store peak information in.
151 * @param monitoredStatistic Statistic to monitor.
152 * @return The resulting expression.
153 */
154 PeakStatisticExpression createPeak(StatisticsIndexMap.LongIndex peakIndex,
155 StatisticExpression monitoredStatistic);
156
157 /**
158 * Creates a new <code>ExpressionView</code> instance.
159 *
160 * @param displayName
161 * A display name. In the console, this is converted to a key for an
162 * internationalised resource bundle look up by prefixing the string
163 * with "statistic." and replacing any whitespace with underscores.
164 * @param expressionString
165 * An expression string, used to create the
166 * {@link StatisticExpression} for the <code>ExpressionView</code>.
167 * @param showForCompositeStatistics
168 * Whether the expression applies to composite statistics.
169 * @exception StatisticsException
170 * If the expression is invalid.
171 * @return The ExpressionView.
172 */
173 ExpressionView createExpressionView(String displayName,
174 String expressionString,
175 boolean showForCompositeStatistics)
176 throws StatisticsException;
177
178 /**
179 * Creates a new <code>ExpressionView</code> instance.
180 *
181 * <p>
182 * This method takes a {@link StatisticExpression}, and is used to by
183 * the console to construct a view around expressions that have no string
184 * representation (namely, those involving peak statistics).
185 * </p>
186 *
187 * @param displayName
188 * A common display name.
189 * @param expression
190 * A {@link StatisticExpression}.
191 * @return The ExpressionView.
192 */
193 ExpressionView createExpressionView(String displayName,
194 StatisticExpression expression);
195 }