InstrumentDescriptor


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 a Instrument and acts as a Proxy to protect the original
24   *  Instrument.
25   *
26   * @author <a HREF="mailto:dev@avalon.apache.org">Avalon Development Team</a>
27   */
28  public interface InstrumentDescriptor
29  {
30      /**
31       * Returns true if the Instrument was configured in the instrumentables
32       *  section of the configuration.
33       *
34       * @return True if configured.
35       */
36      boolean isConfigured();
37  
38      /**
39       * Returns true if the Instrument was registered with the Instrument
40       *  Manager.
41       *
42       * @return True if registered.
43       */
44      boolean isRegistered();
45  
46      
47      /**
48       * Gets the name for the Instrument.  The Instrument Name is used to
49       *  uniquely identify the Instrument during the configuration of the
50       *  Profiler.  The value should be a string which does not contain spaces
51       *  or periods.
52       *
53       * @return The name used to identify a Instrument.
54       */
55      String   getName();
56      
57      /**
58       * Gets the description of the Instrument.
59       *
60       * @return The description of the Instrument.
61       */
62      String   getDescription();
63      
64      /**
65       * Returns the type of the Instrument.  Possible values include
66       *  DefaultInstrumentManager.INSTRUMENT_TYPE_COUNTER,
67       *  DefaultInstrumentManager.INSTRUMENT_TYPE_VALUE or
68       *  DefaultInstrumentManager.INSTRUMENT_TYPE_NONE, if the type was never set.
69       *
70       * @return The type of the Instrument.
71       */
72      int getType();
73      
74      /**
75       * Returns a reference to the descriptor of the Instrumentable of the
76       *  instrument.
77       *
78       * @return A reference to the descriptor of the Instrumentable of the
79       *  instrument.
80       */
81      InstrumentableDescriptor getInstrumentableDescriptor();
82      
83      /**
84       * Adds a CounterInstrumentListener to the list of listeners which will
85       *  receive updates of the value of the Instrument.
86       *
87       * @param listener CounterInstrumentListener which will start receiving
88       *                 profile updates.
89       *
90       * @throws IllegalStateException If the Instrument's type is not
91       *         DefaultInstrumentManager.INSTRUMENT_TYPE_COUNTER.
92       */
93      void addCounterInstrumentListener( CounterInstrumentListener listener );
94      
95      /**
96       * Removes a InstrumentListener from the list of listeners which will
97       *  receive profile events.
98       *
99       * @param listener InstrumentListener which will stop receiving profile
100      *                 events.
101      *
102      * @throws IllegalStateException If the Instrument's type is not
103      *         DefaultInstrumentManager.PROFILE_POINT_TYPE_COUNTER.
104      */
105     void removeCounterInstrumentListener( CounterInstrumentListener listener );
106     
107     /**
108      * Adds a ValueInstrumentListener to the list of listeners which will
109      *  receive updates of the value of the Instrument.
110      *
111      * @param listener ValueInstrumentListener which will start receiving
112      *                 profile updates.
113      *
114      * @throws IllegalStateException If the Instrument's type is not
115      *         DefaultInstrumentManager.INSTRUMENT_TYPE_VALUE.
116      */
117     void addValueInstrumentListener( ValueInstrumentListener listener );
118         
119     /**
120      * Removes a InstrumentListener from the list of listeners which will
121      *  receive profile events.
122      *
123      * @param listener InstrumentListener which will stop receiving profile
124      *                 events.
125      *
126      * @throws IllegalStateException If the Instrument's type is not
127      *         DefaultInstrumentManager.INSTRUMENT_TYPE_VALUE.
128      */
129     void removeValueInstrumentListener( ValueInstrumentListener listener );
130 
131     /**
132      * Returns a InstrumentSampleDescriptor based on its name.
133      *
134      * @param instrumentSampleName Name of the InstrumentSample being requested.
135      *
136      * @return A Descriptor of the requested InstrumentSample.
137      *
138      * @throws NoSuchInstrumentSampleException If the specified InstrumentSample
139      *                                      does not exist.
140      */
141     InstrumentSampleDescriptor getInstrumentSampleDescriptor( String   instrumentSampleName )
142         throws NoSuchInstrumentSampleException;
143     
144     /**
145      * Returns a InstrumentSampleDescriptor based on its name.  If the requested
146      *  sample is invalid in any way, then an expired Descriptor will be
147      *  returned.
148      *
149      * @param sampleDescription Description to assign to the new Sample.
150      * @param sampleInterval Sample interval to use in the new Sample.
151      * @param sampleLease Requested lease time for the new Sample in
152      *                    milliseconds.  The InstrumentManager may grant a
153      *                    lease which is shorter or longer than the requested
154      *                    period.
155      * @param sampleType Type of sample to request.  Must be one of the
156      *                   following:  DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_COUNTER,
157      *                   DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MINIMUM,
158      *                   DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MAXIMUM,
159      *                   DefaultInstrumentManager.INSTRUMENT_SAMPLE_TYPE_MEAN.
160      *
161      * @return A Descriptor of the requested InstrumentSample.
162      */
163     InstrumentSampleDescriptor createInstrumentSample( String   sampleDescription,
164                                                        long sampleInterval,
165                                                        int sampleSize,
166                                                        long sampleLease,
167                                                        int sampleType );
168     
169     /**
170      * Returns an array of Descriptors for the InstrumentSamples configured for this
171      *  Instrument.
172      *
173      * @return An array of Descriptors for the InstrumentSamples configured for this
174      *  Instrument.
175      */
176     InstrumentSampleDescriptor[] getInstrumentSampleDescriptors();
177     
178     /**
179      * Returns the stateVersion of the instrument.  The state version will be
180      *  incremented each time any of the configuration of the instrument or
181      *  any of its children is modified.
182      * Clients can use this value to tell whether or not anything has
183      *  changed without having to do an exhaustive comparison.
184      *
185      * @return The state version of the instrument.
186      */
187     int getStateVersion();
188 }
189
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags