KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > avalon > excalibur > profile > ProfileReport


1 /*
2  * Copyright (C) The Apache Software Foundation. All rights reserved.
3  *
4  * This software is published under the terms of the Apache Software License
5  * version 1.1, a copy of which has been included with this distribution in
6  * the LICENSE.txt file.
7  */
8 package org.apache.avalon.excalibur.profile;
9
10
11 /**
12  * The ProfileReport interface is an event based reporting mechanism. It is
13  * modeled after the Simple API for XML (SAX), and is effectively simple itself.
14  * The ProfileReport may or may not serialize information to a persistent source,
15  * but this is how the Profiler publishes it's information.
16  *
17  * @author <a HREF="mailto:bloritsch@apache.org">Berin Loritsch</a>
18  */
19 public interface ProfileReport {
20
21     /**
22      * The report is started with this method. This is called once at the
23      * beginning of a profile run, and signifies to the ProfileReport object
24      * that it should prepare to handle more requests.
25      */
26     void startReport();
27
28     /**
29      * The addGroup method is called when using cascading Profilables. The
30      * algorithm is that each group is fully evaluated until there are no more
31      * subgroups (i.e. the column names). In order to grasp how it should be
32      * called, please reference the following group heirarchy:
33      *
34      * <p><center><img SRC="doc-files/call-order.png"/></center></p>
35      *
36      * <p>
37      * In this hierarchy, the call order would be like this:
38      * </p>
39      * <pre>
40      * report.addGroup("G1", {"C1", "C2"});
41      * report.addGroup("G2", {"C3", "C4"});
42      * </pre>
43      * <p>
44      * In the event that there are subgroups before we get to the column name,
45      * the tree is fully evaluated to the end. For instance, let us assume
46      * that "C2" has two column names "C2a" and "C2b". The call order would
47      * be like this:
48      * </p>
49      * <pre>
50      * report.addGroup("G1", {"C1", "C2"});
51      * // no sub groups for "C1"
52      * report.addGroup("C2", {"C2a", "C2b"});
53      * report.addGroup("G2", {"C3", "C4"});
54      * </pre>
55      * <p>
56      * When you align the last line of names, this is the order of samples
57      * passed in the sample() method. In this last example, the order would
58      * be "C1", "C2a", "C2b", "C3", "C4". It is imperitive that the samples
59      * gathered are in this precise order.
60      * </p>
61      */
62     void addGroup( String JavaDoc groupName, String JavaDoc[] subgroupNames );
63
64     /**
65      * This method is called each time the Profiler takes a sample. It has the
66      * timestamp that the samples were called, and an array of the actual
67      * values.
68      */
69     void sample( long timestamp, int[] values );
70
71     /**
72      * This method is called once at the end of a profile run, and signifies
73      * that the ProfileReport object may close it's resources, and no other
74      * events will be called.
75      */
76     void endReport();
77 }
Popular Tags