KickJava   Java API By Example, From Geeks To Geeks.

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


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 import java.io.File JavaDoc;
11 import java.io.IOException JavaDoc;
12
13 /**
14  * The Profiler is used to determine numeric values for specific parts of the
15  * Avalon environment. The idea is to add references to Profilable objects to
16  * the Profiler. The Profiler takes periodic snapshots of the running system
17  * so that performance or resource usage can be assertained. The sample duration
18  * is dependant on the Profiler's settings, and should never change during the
19  * time the Profiler is running.
20  *
21  * <p>
22  * Please do respect that for more accurate statistical information, the first
23  * and last sample must be thrown out. The first sample may have residual
24  * information from before the test, and the last sample may be from an
25  * incomplete timeslice. For instance, if the Profiler obtains a sample once
26  * every second, and it stops itself 500ms after the previous sample, the last
27  * sample will only represent 1/2 the typical timeslice.
28  * </p>
29  * <p>
30  * Please also bear in mind that Java has a non-deterministic scheduler, and
31  * samples may not be taken exactly on the specified interval. This sample
32  * <em>jitter</em> is acceptable when averaged over a longer period of time.
33  * </p>
34  *
35  * @author <a HREF="mailto:bloritsch@apache.org">Berin Loritsch</a>
36  */
37 public interface Profiler
38 {
39     /**
40      * Adds a target to profile, along with a name for the target. Good names
41      * include what the expected samples are. For instance "ThreadController:
42      * number of threads" or "EventQueue: events processed per second". The real
43      * results come from the Profilable object itself, but the name is so humans
44      * have a reference for the values. NOTE: if the Profilable class does
45      * not expose any ProfilePoints, it is excluded from the list of Profilable
46      * classes that are notified when the Profiler is active.
47      *
48      * @parameter profileSource The actual source of the samples
49      */
50     void add( Profilable profileSource );
51
52     /**
53      * Reports the results of the profiling to a ProfileReport. The actual
54      * format depends on the ProfileReport given. It can be simple Comma
55      * Separated Values (CSV) with the columns representing a unique Profilable.
56      * Most spreadsheet programs can import this and generate meaningful graphs
57      * from it. Another alternative is to output the information in a tool
58      * specific format. The actual format depends on the ProfileReport in
59      * question, and the Profiler merely needs to reference to the object.
60      *
61      * @parameter outputInfo The handle of the file the profiler serializes the
62      * results to.
63      *
64      * @throws <code>NullPointerException</code> If the ProfileReport is null.
65      */
66     void report( ProfileReport outputInfo );
67 }
68
Popular Tags