KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > excalibur > instrument > AbstractInstrumentable


1 /*
2
3  ============================================================================
4                    The Apache Software License, Version 1.1
5  ============================================================================
6  
7  Copyright (C) 1999-2003 The Apache Software Foundation. All rights reserved.
8  
9  Redistribution and use in source and binary forms, with or without modifica-
10  tion, are permitted provided that the following conditions are met:
11  
12  1. Redistributions of source code must retain the above copyright notice,
13     this list of conditions and the following disclaimer.
14  
15  2. Redistributions in binary form must reproduce the above copyright notice,
16     this list of conditions and the following disclaimer in the documentation
17     and/or other materials provided with the distribution.
18  
19  3. The end-user documentation included with the redistribution, if any, must
20     include the following acknowledgment: "This product includes software
21     developed by the Apache Software Foundation (http://www.apache.org/)."
22     Alternately, this acknowledgment may appear in the software itself, if
23     and wherever such third-party acknowledgments normally appear.
24  
25  4. The names "Jakarta", "Avalon", "Excalibur" and "Apache Software Foundation"
26     must not be used to endorse or promote products derived from this software
27     without prior written permission. For written permission, please contact
28     apache@apache.org.
29  
30  5. Products derived from this software may not be called "Apache", nor may
31     "Apache" appear in their name, without prior written permission of the
32     Apache Software Foundation.
33  
34  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
35  INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
36  FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
37  APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
38  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU-
39  DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
40  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
41  ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
42  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
43  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
44  
45  This software consists of voluntary contributions made by many individuals
46  on behalf of the Apache Software Foundation. For more information on the
47  Apache Software Foundation, please see <http://www.apache.org/>.
48  
49 */
50 package org.apache.excalibur.instrument;
51
52 import java.util.ArrayList JavaDoc;
53
54 /**
55  * Utility class to ease the construction of components that can be instrumented.
56  * <p>
57  * Subclasses should call <code>addInstrument</code> or
58  * <code>addChildInstrumentable</code> as part of the component's
59  * initialization.
60  *
61  * @author <a HREF="mailto:ryan.shaw@stanfordalumni.org">Ryan Shaw</a>
62  * @author <a HREF="mailto:leif@tanukisoftware.com">Leif Mortenson</a>
63  */
64 public abstract class AbstractInstrumentable
65     implements Instrumentable
66 {
67     /** Name of the instrumentable. */
68     private String JavaDoc m_instrumentableName;
69
70     /** Stores the instruments during initialization. */
71     private ArrayList JavaDoc m_instrumentList;
72
73     /** Stores the child instrumentables during initialization. */
74     private ArrayList JavaDoc m_childList;
75
76     /** Flag which is to used to keep track of when the Instrumentable has been registered. */
77     private boolean m_registered;
78
79     /*---------------------------------------------------------------
80      * Constructors
81      *-------------------------------------------------------------*/
82     /**
83      * Creates a new AbstractInstrumentable.
84      */
85     protected AbstractInstrumentable()
86     {
87         m_registered = false;
88         m_instrumentList = new ArrayList JavaDoc();
89         m_childList = new ArrayList JavaDoc();
90     }
91
92     /*---------------------------------------------------------------
93      * Methods
94      *-------------------------------------------------------------*/
95     /**
96      * Adds an Instrument to the list of Instruments published by the component.
97      * This method may not be called after the Instrumentable has been
98      * registered with the InstrumentManager.
99      *
100      * @param instrument Instrument to publish.
101      */
102     protected void addInstrument( Instrument instrument )
103     {
104         if( m_registered )
105         {
106             throw new IllegalStateException JavaDoc( "Instruments can not be added after the "
107                                              + "Instrumentable is registered with the InstrumentManager." );
108         }
109         m_instrumentList.add( instrument );
110     }
111
112     /**
113      * Adds a child Instrumentable to the list of child Instrumentables
114      * published by the component. This method may not be called after the
115      * Instrumentable has been registered with the InstrumentManager.
116      * <p>
117      * Note that Child Instrumentables must be named by the caller using the
118      * setInstrumentableName method.
119      *
120      * @param child Child Instrumentable to publish.
121      */
122     protected void addChildInstrumentable( Instrumentable child )
123     {
124         if( m_registered )
125         {
126             throw new IllegalStateException JavaDoc( "Child Instrumentables can not be added after the "
127                                              + "Instrumentable is registered with the InstrumentManager." );
128         }
129         m_childList.add( child );
130     }
131
132     /*---------------------------------------------------------------
133      * Instrumentable Methods
134      *-------------------------------------------------------------*/
135     /**
136      * Gets the name of the Instrumentable.
137      *
138      * @return The name used to identify a Instrumentable.
139      */
140     public final String JavaDoc getInstrumentableName()
141     {
142         return m_instrumentableName;
143     }
144
145     /**
146      * Sets the name for the Instrumentable. The Instrumentable Name is used
147      * to uniquely identify the Instrumentable during the configuration of
148      * the InstrumentManager and to gain access to an InstrumentableDescriptor
149      * through the InstrumentManager. The value should be a string which does
150      * not contain spaces or periods.
151      * <p>
152      * This value may be set by a parent Instrumentable, or by the
153      * InstrumentManager using the value of the 'instrumentable' attribute in
154      * the configuration of the component.
155      *
156      * @param name The name used to identify a Instrumentable.
157      */
158     public final void setInstrumentableName( String JavaDoc name )
159     {
160         m_instrumentableName = name;
161     }
162
163     /**
164      * Any Object which implements Instrumentable can also make use of other
165      * Instrumentable child objects. This method is used to tell the
166      * InstrumentManager about them.
167      *
168      * @return An array of child Instrumentables. This method should never
169      * return null. If there are no child Instrumentables, then
170      * EMPTY_INSTRUMENTABLE_ARRAY can be returned.
171      */
172     public final Instrumentable[] getChildInstrumentables()
173     {
174         m_registered = true;
175         if( m_childList.size() == 0 )
176         {
177             return Instrumentable.EMPTY_INSTRUMENTABLE_ARRAY;
178         }
179         else
180         {
181             Instrumentable[] children = new Instrumentable[ m_childList.size() ];
182             m_childList.toArray( children );
183             return children;
184         }
185     }
186
187     /**
188      * Obtain a reference to all the Instruments that the Instrumentable object
189      * wishes to expose. All sampling is done directly through the
190      * Instruments as opposed to the Instrumentable interface.
191      *
192      * @return An array of the Instruments available for profiling. Should
193      * never be null. If there are no Instruments, then
194      * EMPTY_INSTRUMENT_ARRAY can be returned. This should never be
195      * the case though unless there are child Instrumentables with
196      * Instruments.
197      */
198     public final Instrument[] getInstruments()
199     {
200         m_registered = true;
201         if( m_instrumentList.size() == 0 )
202         {
203             return Instrumentable.EMPTY_INSTRUMENT_ARRAY;
204         }
205         else
206         {
207             Instrument[] instruments = new Instrument[ m_instrumentList.size() ];
208             m_instrumentList.toArray( instruments );
209             return instruments;
210         }
211     }
212 }
213
Popular Tags