KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > excalibur > instrument > manager > impl > InstrumentSample


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.impl;
21
22 import java.io.PrintWriter JavaDoc;
23
24 import org.apache.avalon.framework.configuration.Configuration;
25 import org.apache.avalon.framework.configuration.ConfigurationException;
26 import org.apache.avalon.framework.logger.LogEnabled;
27
28 import org.apache.excalibur.instrument.manager.InstrumentSampleDescriptor;
29 import org.apache.excalibur.instrument.manager.InstrumentSampleListener;
30 import org.apache.excalibur.instrument.manager.InstrumentSampleSnapshot;
31
32 /**
33  * InstrumentSamples are used to provide an Instrument with state. Samples
34  * have a sample interval, which is the period over which data is grouped.
35  * <p>
36  * InstrmentSamples can be created when the InstrumentManager is created as
37  * part of the configuration process, or as a result of a request from an
38  * InstrumentClient.
39  *
40  * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
41  * @version CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:25 $
42  * @since 4.1
43  */
44 interface InstrumentSample
45     extends LogEnabled
46 {
47     /**
48      * Returns the InstrumentProxy which owns the InstrumentSample.
49      *
50      * @return The InstrumentProxy which owns the InstrumentSample.
51      */
52     InstrumentProxy getInstrumentProxy();
53     
54     /**
55      * Returns true if the InstrumentSample was configured in the instrumentables
56      * section of the configuration.
57      *
58      * @return True if configured.
59      */
60     boolean isConfigured();
61     
62     /**
63      * Returns the name of the sample.
64      *
65      * @return The name of the sample.
66      */
67     String JavaDoc getName();
68     
69     /**
70      * Returns the sample interval. The period of each sample in millisends.
71      *
72      * @return The sample interval.
73      */
74     long getInterval();
75     
76     /**
77      * Returns the number of samples in the sample history.
78      *
79      * @return The size of the sample history.
80      */
81     int getSize();
82     
83     /**
84      * Returns the description of the sample.
85      *
86      * @return The description of the sample.
87      */
88     String JavaDoc getDescription();
89     
90     /**
91      * Returns the type of the Instrument Sample. Possible values include
92      * DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_COUNTER,
93      * DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MAXIMUM,
94      * DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MEAN, or
95      * DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MINIMUM.
96      *
97      * @return The type of the Instrument Sample.
98      */
99     int getType();
100     
101     /**
102      * Returns a Descriptor for the InstrumentSample.
103      *
104      * @return A Descriptor for the InstrumentSample.
105      */
106     InstrumentSampleDescriptor getDescriptor();
107     
108     /**
109      * Obtain the value of the sample. All samples are integers, so the profiled
110      * objects must measure quantity (numbers of items), rate (items/period), time in
111      * milliseconds, etc.
112      *
113      * @return The sample value.
114      */
115     int getValue();
116     
117     /**
118      * Obtain the UNIX time of the beginning of the sample.
119      *
120      * @return The UNIX time of the beginning of the sample.
121      */
122     long getTime();
123     
124     /**
125      * Returns the Type of the Instrument which can use the sample. This
126      * should be the same for all instances of a class.
127      * <p>
128      * Should be one of the following:
129      * DefaultInstrumentManager.INSTRUMENT_TYPE_COUNTER
130      * or DefaultInstrumentManager.INSTRUMENT_TYPE_VALUE
131      *
132      * @return The Type of the Instrument which can use the sample.
133      */
134     int getInstrumentType();
135     
136     /**
137      * Returns the time that the current lease expires. Permanent samples will
138      * return a value of 0.
139      *
140      * @return The time that the current lease expires.
141      */
142     long getLeaseExpirationTime();
143     
144     /**
145      * Extends the lease to be lease milliseconds from the current time.
146      *
147      * @param lease The length of the lease in milliseconds.
148      *
149      * @return The new lease expiration time. Returns 0 if the sample is
150      * permanent.
151      */
152     long extendLease( long lease );
153     
154     /**
155      * Tells the sample that its lease has expired. No new references to
156      * the sample will be made available, but clients which already have
157      * access to the sample may continue to use it.
158      */
159     void expire();
160     
161     /**
162      * Obtains a static snapshot of the InstrumentSample.
163      *
164      * @return A static snapshot of the InstrumentSample.
165      */
166     InstrumentSampleSnapshot getSnapshot();
167     
168     /**
169      * Returns the stateVersion of the sample. The state version will be
170      * incremented each time any of the configuration of the sample is
171      * modified.
172      * Clients can use this value to tell whether or not anything has
173      * changed without having to do an exhaustive comparison.
174      *
175      * @return The state version of the sample.
176      */
177     int getStateVersion();
178     
179     /**
180      * Registers a InstrumentSampleListener with a InstrumentSample given a name.
181      *
182      * @param listener The listener which should start receiving updates from the
183      * InstrumentSample.
184      */
185     void addInstrumentSampleListener( InstrumentSampleListener listener );
186     
187     /**
188      * Unregisters a InstrumentSampleListener from a InstrumentSample given a name.
189      *
190      * @param listener The listener which should stop receiving updates from the
191      * InstrumentSample.
192      */
193     void removeInstrumentSampleListener( InstrumentSampleListener listener );
194     
195     /**
196      * Writes the current state to a PrintWriter as XML.
197      *
198      * @param out The PrintWriter to which the state should be written.
199      */
200     void writeState( PrintWriter JavaDoc out );
201     
202     /**
203      * Loads the state into the InstrumentSample.
204      *
205      * @param state Configuration object to load state from.
206      *
207      * @throws ConfigurationException If there were any problems loading the
208      * state.
209      */
210     void loadState( Configuration state ) throws ConfigurationException;
211 }
212
Popular Tags