KickJava   Java API By Example, From Geeks To Geeks.

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


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 import org.apache.avalon.framework.logger.AbstractLogEnabled;
55
56 /**
57  * Utility class to ease the construction of components that can be instrumented
58  * but must also implement LogEnabled.
59  * <p>
60  * Subclasses should call <code>addInstrument</code> or
61  * <code>addChildInstrumentable</code> as part of the component's
62  * initialization.
63  *
64  * @author <a HREF="mailto:ryan.shaw@stanfordalumni.org">Ryan Shaw</a>
65  * @author <a HREF="mailto:leif@tanukisoftware.com">Leif Mortenson</a>
66  */
67 public abstract class AbstractLogEnabledInstrumentable
68     extends AbstractLogEnabled
69     implements Instrumentable
70 {
71     /** Name of the instrumentable. */
72     private String JavaDoc m_instrumentableName;
73
74     /** Stores the instruments during initialization. */
75     private ArrayList JavaDoc m_instrumentList;
76
77     /** Stores the child instrumentables during initialization. */
78     private ArrayList JavaDoc m_childList;
79
80     /** Flag which is to used to keep track of when the Instrumentable has been registered. */
81     private boolean m_registered;
82
83     /*---------------------------------------------------------------
84      * Constructors
85      *-------------------------------------------------------------*/
86     /**
87      * Creates a new AbstractLogEnabledInstrumentable.
88      */
89     protected AbstractLogEnabledInstrumentable()
90     {
91         m_registered = false;
92         m_instrumentList = new ArrayList JavaDoc();
93         m_childList = new ArrayList JavaDoc();
94     }
95
96     /*---------------------------------------------------------------
97      * Methods
98      *-------------------------------------------------------------*/
99     /**
100      * Adds an Instrument to the list of Instruments published by the component.
101      * This method may not be called after the Instrumentable has been
102      * registered with the InstrumentManager.
103      *
104      * @param instrument Instrument to publish.
105      */
106     protected void addInstrument( Instrument instrument )
107     {
108         if( m_registered )
109         {
110             throw new IllegalStateException JavaDoc( "Instruments can not be added after the "
111                                              + "Instrumentable is registered with the InstrumentManager." );
112         }
113         m_instrumentList.add( instrument );
114     }
115
116     /**
117      * Adds a child Instrumentable to the list of child Instrumentables
118      * published by the component. This method may not be called after the
119      * Instrumentable has been registered with the InstrumentManager.
120      * <p>
121      * Note that Child Instrumentables must be named by the caller using the
122      * setInstrumentableName method.
123      *
124      * @param child Child Instrumentable to publish.
125      */
126     protected void addChildInstrumentable( Instrumentable child )
127     {
128         if( m_registered )
129         {
130             throw new IllegalStateException JavaDoc( "Child Instrumentables can not be added after the "
131                                              + "Instrumentable is registered with the InstrumentManager." );
132         }
133         m_childList.add( child );
134     }
135
136     /*---------------------------------------------------------------
137      * Instrumentable Methods
138      *-------------------------------------------------------------*/
139     /**
140      * Gets the name of the Instrumentable.
141      *
142      * @return The name used to identify a Instrumentable.
143      */
144     public final String JavaDoc getInstrumentableName()
145     {
146         return m_instrumentableName;
147     }
148
149     /**
150      * Sets the name for the Instrumentable. The Instrumentable Name is used
151      * to uniquely identify the Instrumentable during the configuration of
152      * the InstrumentManager and to gain access to an InstrumentableDescriptor
153      * through the InstrumentManager. The value should be a string which does
154      * not contain spaces or periods.
155      * <p>
156      * This value may be set by a parent Instrumentable, or by the
157      * InstrumentManager using the value of the 'instrumentable' attribute in
158      * the configuration of the component.
159      *
160      * @param name The name used to identify a Instrumentable.
161      */
162     public final void setInstrumentableName( String JavaDoc name )
163     {
164         m_instrumentableName = name;
165     }
166
167     /**
168      * Any Object which implements Instrumentable can also make use of other
169      * Instrumentable child objects. This method is used to tell the
170      * InstrumentManager about them.
171      *
172      * @return An array of child Instrumentables. This method should never
173      * return null. If there are no child Instrumentables, then
174      * EMPTY_INSTRUMENTABLE_ARRAY can be returned.
175      */
176     public final Instrumentable[] getChildInstrumentables()
177     {
178         m_registered = true;
179         if( m_childList.size() == 0 )
180         {
181             return Instrumentable.EMPTY_INSTRUMENTABLE_ARRAY;
182         }
183         else
184         {
185             Instrumentable[] children = new Instrumentable[ m_childList.size() ];
186             m_childList.toArray( children );
187             return children;
188         }
189     }
190
191     /**
192      * Obtain a reference to all the Instruments that the Instrumentable object
193      * wishes to expose. All sampling is done directly through the
194      * Instruments as opposed to the Instrumentable interface.
195      *
196      * @return An array of the Instruments available for profiling. Should
197      * never be null. If there are no Instruments, then
198      * EMPTY_INSTRUMENT_ARRAY can be returned. This should never be
199      * the case though unless there are child Instrumentables with
200      * Instruments.
201      */
202     public final Instrument[] getInstruments()
203     {
204         m_registered = true;
205         if( m_instrumentList.size() == 0 )
206         {
207             return Instrumentable.EMPTY_INSTRUMENT_ARRAY;
208         }
209         else
210         {
211             Instrument[] instruments = new Instrument[ m_instrumentList.size() ];
212             m_instrumentList.toArray( instruments );
213             return instruments;
214         }
215     }
216 }
217
Popular Tags