KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > excalibur > instrument > manager > InstrumentSampleDescriptor


1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
14  * implied.
15  *
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18  */
19
20 package org.apache.excalibur.instrument.manager;
21
22 /**
23  * Describes an InstrumentSample and acts as a Proxy to protect the original
24  * InstrumentSample object.
25  *
26  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
27  */
28 public interface InstrumentSampleDescriptor
29 {
30     /**
31      * Returns true if the InstrumentSample was configured in the instrumentables
32      * section of the configuration.
33      *
34      * @return True if configured.
35      */
36     boolean isConfigured();
37     
38     /**
39      * Returns the name of the sample.
40      *
41      * @return The name of the sample.
42      */
43     String JavaDoc getName();
44     
45     /**
46      * Returns the sample interval. The period of each sample in millisends.
47      *
48      * @return The sample interval.
49      */
50     long getInterval();
51     
52     /**
53      * Returns the number of samples in the sample history.
54      *
55      * @return The size of the sample history.
56      */
57     int getSize();
58     
59     /**
60      * Returns the description of the sample.
61      *
62      * @return The description of the sample.
63      */
64     String JavaDoc getDescription();
65     
66     /**
67      * Returns the type of the Instrument Sample. Possible values include
68      * DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_COUNTER,
69      * DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MAXIMUM,
70      * DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MEAN, or
71      * DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MINIMUM.
72      *
73      * @return The type of the Instrument Sample.
74      */
75     int getType();
76     
77     /**
78      * Obtain the value of the sample. All samples are integers, so the profiled
79      * objects must measure quantity (numbers of items), rate (items/period), time in
80      * milliseconds, etc.
81      *
82      * @return The sample value.
83      */
84     int getValue();
85     
86     /**
87      * Obtain the UNIX time of the beginning of the sample.
88      *
89      * @return The UNIX time of the beginning of the sample.
90      */
91     long getTime();
92     
93     /**
94      * Returns the Type of the Instrument which can use the sample. This
95      * should be the same for all instances of a class.
96      * <p>
97      * Should be one of the following: InstrumentManager.PROFILE_POINT_TYPE_COUNTER
98      * or InstrumentManager.PROFILE_POINT_TYPE_VALUE
99      *
100      * @return The Type of the Instrument which can use the sample.
101      */
102     int getInstrumentType();
103     
104     /**
105      * Returns a reference to the descriptor of the Instrument of the sample.
106      *
107      * @return A reference to the descriptor of the Instrument of the sample.
108      */
109     InstrumentDescriptor getInstrumentDescriptor();
110     
111     /**
112      * Registers a InstrumentSampleListener with a InstrumentSample given a name.
113      *
114      * @param listener The listener which should start receiving updates from the
115      * InstrumentSample.
116      */
117     void addInstrumentSampleListener( InstrumentSampleListener listener );
118     
119     /**
120      * Unregisters a InstrumentSampleListener from a InstrumentSample given a name.
121      *
122      * @param listener The listener which should stop receiving updates from the
123      * InstrumentSample.
124      */
125     void removeInstrumentSampleListener( InstrumentSampleListener listener );
126     
127     /**
128      * Returns the time that the current lease expires. Permanent samples will
129      * return a value of 0.
130      *
131      * @return The time that the current lease expires.
132      */
133     long getLeaseExpirationTime();
134     
135     /**
136      * Extends the lease to be lease milliseconds from the current time.
137      *
138      * @param lease The length of the lease in milliseconds.
139      *
140      * @return The new lease expiration time. Returns 0 if the sample is
141      * permanent.
142      */
143     long extendLease( long lease );
144     
145     /**
146      * Obtains a static snapshot of the InstrumentSample.
147      *
148      * @return A static snapshot of the InstrumentSample.
149      */
150     InstrumentSampleSnapshot getSnapshot();
151     
152     /**
153      * Returns the stateVersion of the sample. The state version will be
154      * incremented each time any of the configuration of the sample is
155      * modified.
156      * Clients can use this value to tell whether or not anything has
157      * changed without having to do an exhaustive comparison.
158      *
159      * @return The state version of the sample.
160      */
161     int getStateVersion();
162 }
163
164
Popular Tags