Performance


1   /*******************************************************************************
2    * Copyright (c) 2000, 2004 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.test.performance;
12  
13  import junit.framework.TestCase;
14  
15  import org.eclipse.core.runtime.Platform;
16  
17  import org.eclipse.test.internal.performance.InternalDimensions;
18  import org.eclipse.test.internal.performance.InternalPerformanceMeter;
19  import org.eclipse.test.internal.performance.NullPerformanceMeter;
20  import org.eclipse.test.internal.performance.OSPerformanceMeterFactory;
21  import org.eclipse.test.internal.performance.PerformanceMeterFactory;
22  import org.eclipse.test.internal.performance.PerformanceTestPlugin;
23  import org.eclipse.test.internal.performance.data.Dim;
24  import org.eclipse.test.internal.performance.eval.AbsoluteBandChecker;
25  import org.eclipse.test.internal.performance.eval.AssertChecker;
26  import org.eclipse.test.internal.performance.eval.Evaluator;
27  import org.eclipse.test.internal.performance.eval.IEvaluator;
28  import org.eclipse.test.internal.performance.eval.RelativeBandChecker;
29  import org.osgi.framework.Bundle;
30  
31  /**
32   * Helper for performance measurements. Currently provides performance meter
33   * creation and checking of measurements.
34   * 
35   * This class is not intended to be subclassed by clients.
36   * 
37   * @since 3.1
38   */
39  public class Performance {
40      
41      /**
42       *  A comment kind of a comment that explains a performance degradation.
43       */
44      public static final int EXPLAINS_DEGRADATION_COMMENT= 1;
45  
46      private static final String   PERFORMANCE_METER_FACTORY= "/option/performanceMeterFactory"; //$NON-NLS-1$
47      private static final String   PERFORMANCE_METER_FACTORY_PROPERTY= "PerformanceMeterFactory"; //$NON-NLS-1$
48  
49      private static Performance fgDefault;
50      
51      private PerformanceMeterFactory fPerformanceMeterFactory;
52      private IEvaluator fDefaultEvaluator;
53  
54      /** Null performance meter singleton */
55      private NullPerformanceMeter fNullPeformanceMeter;
56      
57  
58      /**
59       * Private constructor to block instance creation.
60       */
61      private Performance() {
62          // empty
63      }
64      
65      /**
66       * Returns the singleton of <code>Performance</code>
67       * 
68       * @return the singleton of <code>Performance</code>
69       */
70      public static Performance getDefault() {
71          if (fgDefault == null)
72              fgDefault= new Performance();
73          return fgDefault;
74      }
75      
76      /**
77       * Asserts default properties of the measurements captured by the given
78       * performance meter.
79       * 
80       * @param performanceMeter the performance meter
81       * @throws RuntimeException if the properties do not hold
82       */
83      public void assertPerformance(PerformanceMeter performanceMeter) {
84          if (fDefaultEvaluator == null) {
85              fDefaultEvaluator= new Evaluator();
86              fDefaultEvaluator.setAssertCheckers(new AssertChecker[] {
87                      new RelativeBandChecker(InternalDimensions.ELAPSED_PROCESS, 0.0f, 1.10f),
88                      //new RelativeBandChecker(InternalDimensions.CPU_TIME, 0.0f, 1.10f),
89                      //new RelativeBandChecker(InternalDimensions.WORKING_SET, 0.0f, 3.00f),
90                      //new RelativeBandChecker(InternalDimensions.USED_JAVA_HEAP, 0.0f, 2.00f),
91                      //new RelativeBandChecker(InternalDimensions.SYSTEM_TIME, 0.0f, 1.10f)
92              });
93          }
94          fDefaultEvaluator.evaluate(performanceMeter);
95      }
96  
97      /**
98       * Asserts that the measurement specified by the dimension captured in the given
99       * performance meter is within a certain range with respect to some reference value.
100      * If the performance meter doesn't provide the specified dimension, the call has no effect.
101      * 
102      * @param performanceMeter the performance meter
103      * @param dim the Dimension to check
104      * @param lowerPercentage a negative number indicating the percentage the measured value is allowed to be smaller than some reference value
105      * @param upperPercentage a positive number indicating the percentage the measured value is allowed to be greater than some reference value
106      * @throws RuntimeException if the properties do not hold
107      */
108     public void assertPerformanceInRelativeBand(PerformanceMeter performanceMeter, Dimension dim, int lowerPercentage, int upperPercentage) {
109         Evaluator e= new Evaluator();
110         e.setAssertCheckers(new AssertChecker[] {
111                 new RelativeBandChecker((Dim) dim, 1.0+(lowerPercentage / 100.0), 1.0+(upperPercentage / 100.0)),
112         });
113         e.evaluate(performanceMeter);
114     }
115 
116     /**
117      * Asserts that the measurement specified by the dimension captured in the given
118      * performance meter is within a certain range with respect to some reference value.
119      * If the performance meter doesn't provide the specified dimension, the call has no effect.
120      * 
121      * @param performanceMeter the performance meter
122      * @param dim the Dimension to check
123      * @param lowerBand a negative number indicating the absolute amount the measured value is allowed to be smaller than some reference value
124      * @param upperBand a positive number indicating the absolute amount the measured value is allowed to be greater than some reference value
125      * @throws RuntimeException if the properties do not hold
126      */
127     public void assertPerformanceInAbsoluteBand(PerformanceMeter performanceMeter, Dimension dim, int lowerBand, int upperBand) {
128         Evaluator e= new Evaluator();
129         e.setAssertCheckers(new AssertChecker[] {
130                 new AbsoluteBandChecker((Dim) dim, lowerBand, upperBand),
131         });
132         e.evaluate(performanceMeter);
133     }
134 
135     /**
136      * Creates a performance meter for the given scenario id.
137      * 
138      * @param scenarioId the scenario id
139      * @return a performance meter for the given scenario id
140      * @throws IllegalArgumentException if a performance meter for the given
141      *                 scenario id has already been created
142      */
143     public PerformanceMeter createPerformanceMeter(String   scenarioId) {
144         return getPeformanceMeterFactory().createPerformanceMeter(scenarioId);
145     }
146 
147     /**
148      * Returns the null performance meter singleton.
149      * 
150      * @return the null performance meter singleton
151      */
152     public PerformanceMeter getNullPerformanceMeter() {
153         if (fNullPeformanceMeter == null)
154             fNullPeformanceMeter= new NullPerformanceMeter();
155         return fNullPeformanceMeter;
156     }
157 
158     /**
159      * Returns a default scenario id for the given test. The test's name
160      * must have been set, such that <code>test.getName()</code> is not
161      * <code>null</code>.
162      * 
163      * @param test the test
164      * @return the default scenario id for the test
165      */
166     public String   getDefaultScenarioId(TestCase test) {
167         return test.getClass().getName() + '#' + test.getName() + "()"; //$NON-NLS-1$
168     }
169     
170     /**
171      * Returns a default scenario id for the given test and id. The test's
172      * name must have been set, such that <code>test.getName()</code> is
173      * not <code>null</code>. The id distinguishes multiple scenarios in
174      * the same test.
175      * 
176      * @param test the test
177      * @param id the id
178      * @return the default scenario id for the test and the id
179      */
180     public String   getDefaultScenarioId(TestCase test, String   id) {
181         return getDefaultScenarioId(test) + '-' + id;
182     }
183 
184     private PerformanceMeterFactory getPeformanceMeterFactory() {
185         if (fPerformanceMeterFactory == null)
186             fPerformanceMeterFactory= createPerformanceMeterFactory();
187         return fPerformanceMeterFactory;
188     }
189     
190     private PerformanceMeterFactory createPerformanceMeterFactory() {
191         PerformanceMeterFactory factory;
192         factory= tryInstantiate(System.getProperty(PERFORMANCE_METER_FACTORY_PROPERTY));
193         if (factory != null)
194             return factory;
195         
196         factory= tryInstantiate(Platform.getDebugOption(PerformanceTestPlugin.PLUGIN_ID + PERFORMANCE_METER_FACTORY));
197         if (factory != null)
198             return factory;
199         
200         return createDefaultPerformanceMeterFactory();
201     }
202     
203     private PerformanceMeterFactory tryInstantiate(String   className) {
204         PerformanceMeterFactory instance= null;
205         if (className != null && className.length() > 0) {
206             try {
207                 int separator= className.indexOf(':');
208                 Bundle bundle= null;
209                 if (separator == -1) {
210                     bundle= PerformanceTestPlugin.getDefault().getBundle();
211                 } else {
212                     String   bundleName= className.substring(0, separator);
213                     className= className.substring(separator + 1);
214                     bundle= Platform.getBundle(bundleName);
215                 }
216                 Class   c= bundle.loadClass(className);
217                 instance= (PerformanceMeterFactory) c.newInstance();
218             } catch (ClassNotFoundException   e) {
219                 PerformanceTestPlugin.log(e);
220             } catch (InstantiationException   e) {
221                 PerformanceTestPlugin.log(e);
222             } catch (IllegalAccessException   e) {
223                 PerformanceTestPlugin.log(e);
224             } catch (ClassCastException   e) {
225                 PerformanceTestPlugin.log(e);
226             }
227         }
228         return instance;
229     }
230 
231     private PerformanceMeterFactory createDefaultPerformanceMeterFactory() {
232         return new OSPerformanceMeterFactory();
233     }
234     
235     /**
236      * Mark the scenario represented by the given PerformanceMeter
237      * to be included into the global and the component performance summary. The summary shows
238      * the given dimension of the scenario and labels the scenario with the short name.
239      * 
240      * @param pm the PerformanceMeter
241      * @param shortName a short (shorter than 40 characters) descriptive name of the scenario
242      * @param dimension the dimension to show in the summary
243      */
244     public void tagAsGlobalSummary(PerformanceMeter pm, String   shortName, Dimension dimension) {
245         tagAsGlobalSummary(pm, shortName, new Dimension[] { dimension } );
246     }
247 
248     /**
249      * Mark the scenario represented by the given PerformanceMeter
250      * to be included into the global and the component performance summary. The summary shows
251      * the given dimensions of the scenario and labels the scenario with the short name.
252      * 
253      * @param pm the PerformanceMeter
254      * @param shortName a short (shorter than 40 characters) descriptive name of the scenario
255      * @param dimensions an array of dimensions to show in the summary
256      */
257     public void tagAsGlobalSummary(PerformanceMeter pm, String   shortName, Dimension[] dimensions) {
258         if (pm instanceof InternalPerformanceMeter) {
259             InternalPerformanceMeter ipm= (InternalPerformanceMeter) pm;
260             ipm.tagAsSummary(true, shortName, dimensions);
261         }
262     }
263 
264     
265     /**
266      * Mark the scenario represented by the given PerformanceMeter
267      * to be included into the component performance summary. The summary shows
268      * the given dimension of the scenario and labels the scenario with the short name.
269      * 
270      * @param pm the PerformanceMeter
271      * @param shortName a short (shorter than 40 characters) descriptive name of the scenario
272      * @param dimension the dimension to show in the summary
273      */
274     public void tagAsSummary(PerformanceMeter pm, String   shortName, Dimension dimension) {
275         tagAsSummary(pm, shortName, new Dimension[] { dimension } );
276     }
277 
278     /**
279      * Mark the scenario represented by the given PerformanceMeter
280      * to be included into the component performance summary. The summary shows
281      * the given dimensions of the scenario and labels the scenario with the short name.
282      * 
283      * @param pm the PerformanceMeter
284      * @param shortName a short (shorter than 40 characters) descriptive name of the scenario
285      * @param dimensions an array of dimensions to show in the summary
286      */
287     public void tagAsSummary(PerformanceMeter pm, String   shortName, Dimension[] dimensions) {
288         if (pm instanceof InternalPerformanceMeter) {
289             InternalPerformanceMeter ipm= (InternalPerformanceMeter) pm;
290             ipm.tagAsSummary(false, shortName, dimensions);
291         }
292     }
293 
294     /**
295      * Set a comment for the scenario represented by the given PerformanceMeter.
296      * Currently only comments with a commentKind of EXPLAINS_DEGRADATION_COMMENT are used.
297      * Their commentText is shown in a hover of the performance summaries graph if a performance
298      * degradation exists.
299      * 
300      * @param pm the PerformanceMeter
301      * @param commentKind kind of comment. Must be EXPLAINS_DEGRADATION_COMMENT to have an effect.
302      * @param commentText the comment (shorter than 400 characters)
303      */
304     public void setComment(PerformanceMeter pm, int commentKind, String   commentText) {
305         if (commentKind == EXPLAINS_DEGRADATION_COMMENT) {
306             if (pm instanceof InternalPerformanceMeter) {
307                 InternalPerformanceMeter ipm= (InternalPerformanceMeter) pm;
308                 ipm.setComment(commentKind, commentText);
309             }
310         }
311     }
312 }
313
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags