LifecycleHelper


1   /* ====================================================================
2    * Loom Software License, version 1.1
3    *
4    * Copyright (c) 2003, Loom Group. All rights reserved.
5    * Redistribution and use in source and binary forms, with or without
6    * modification, are permitted provided that the following conditions
7    * are met:
8    *
9    * 1. Redistributions of source code must retain the above copyright
10   *    notice, this list of conditions and the following disclaimer.
11   *
12   * 2. Redistributions in binary form must reproduce the above copyright
13   *    notice, this list of conditions and the following disclaimer in
14   *    the documentation and/or other materials provided with the
15   *    distribution.
16   *
17   * 3. Neither the name of the Loom Group nor the name "Loom" nor
18   *    the names of its contributors may be used to endorse or promote
19   *    products derived from this software without specific prior
20   *    written permission.
21   *
22   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
25   * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
26   * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
27   * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28   * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
29   * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
30   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31   * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
32   * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33   * POSSIBILITY OF SUCH DAMAGE.
34   *
35   * ====================================================================
36   *
37   * Loom includes code from the Apache Software Foundation
38   *
39   * ====================================================================
40   * The Apache Software License, Version 1.1
41   *
42   * Copyright (c) 1997-2003 The Apache Software Foundation. All rights
43   * reserved.
44   *
45   * Redistribution and use in source and binary forms, with or without
46   * modification, are permitted provided that the following conditions
47   * are met:
48   *
49   * 1. Redistributions of source code must retain the above copyright
50   *    notice, this list of conditions and the following disclaimer.
51   *
52   * 2. Redistributions in binary form must reproduce the above copyright
53   *    notice, this list of conditions and the following disclaimer in
54   *    the documentation and/or other materials provided with the
55   *    distribution.
56   *
57   * 3. The end-user documentation included with the redistribution,
58   *    if any, must include the following acknowledgment:
59   *    "This product includes software developed by the
60   *    Apache Software Foundation (http://www.apache.org/)."
61   *    Alternately, this acknowledgment may appear in the software
62   *    itself, if and wherever such third-party acknowledgments
63   *    normally appear.
64   *
65   * 4. The names "Jakarta", "Avalon", and "Apache Software Foundation"
66   *    must not be used to endorse or promote products derived from this
67   *    software without prior written permission. For written
68   *    permission, please contact apache@apache.org.
69   *
70   * 5. Products derived from this software may not be called "Apache",
71   *    nor may "Apache" appear in their name, without prior written
72   *    permission of the Apache Software Foundation.
73   *
74   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
75   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
76   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
77   * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
78   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
79   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
80   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
81   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
82   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
83   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
84   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
85   * SUCH DAMAGE.
86   */
87  package org.codehaus.loom.components.util.lifecycle;
88  
89  import org.apache.avalon.framework.activity.Disposable;
90  import org.apache.avalon.framework.activity.Initializable;
91  import org.apache.avalon.framework.activity.Startable;
92  import org.apache.avalon.framework.component.ComponentManager;
93  import org.apache.avalon.framework.component.Composable;
94  import org.apache.avalon.framework.configuration.Configurable;
95  import org.apache.avalon.framework.configuration.Configuration;
96  import org.apache.avalon.framework.container.ContainerUtil;
97  import org.apache.avalon.framework.context.Context;
98  import org.apache.avalon.framework.context.Contextualizable;
99  import org.apache.avalon.framework.logger.LogEnabled;
100 import org.apache.avalon.framework.logger.Logger;
101 import org.apache.avalon.framework.parameters.Parameterizable;
102 import org.apache.avalon.framework.parameters.Parameters;
103 import org.apache.avalon.framework.service.ServiceManager;
104 import org.apache.avalon.framework.service.Serviceable;
105 import org.apache.excalibur.instrument.InstrumentManageable;
106 import org.apache.excalibur.instrument.InstrumentManager;
107 import org.apache.excalibur.instrument.Instrumentable;
108 import org.codehaus.loom.interfaces.LoomException;
109 import org.codehaus.spice.salt.i18n.ResourceManager;
110 import org.codehaus.spice.salt.i18n.Resources;
111 import org.codehaus.dna.AbstractLogEnabled;
112 
113 /**
114  * This is a class to help an Application manage the lifecycle of a component.
115  * The implementation provides support for the processing of a component through
116  * each lifecycle stage, and manage errors in a consistent way.
117  *
118  * @author Peter Donald
119  * @author <a HREF="mailto:mcconnell@apache.org">Stephen McConnell</a>
120  */
121 public class LifecycleHelper
122     extends AbstractLogEnabled
123 {
124     private static final Resources REZ =
125         ResourceManager.getPackageResources( LifecycleHelper.class );
126 
127     //Constants to designate stages
128     private static final int STAGE_CREATE = 0;
129     private static final int STAGE_LOGGER = 1;
130     private static final int STAGE_INSTRUMENTMGR = 2;
131     private static final int STAGE_CONTEXT = 3;
132     private static final int STAGE_COMPOSE = 4;
133     private static final int STAGE_CONFIG = 5;
134     private static final int STAGE_PARAMETER = 6;
135     private static final int STAGE_INIT = 7;
136     private static final int STAGE_INSTRUMENTABLE = 8;
137     private static final int STAGE_START = 9;
138     private static final int STAGE_STOP = 10;
139     private static final int STAGE_DISPOSE = 11;
140     private static final int STAGE_DESTROY = 12;
141 
142     /**
143      * Method to run a component through it's startup phase. Errors that occur
144      * during startup will be logged appropriately and cause exceptions with
145      * useful messages to be raised.
146      *
147      * @param name the name of the component
148      * @param entry the entry representing object
149      * @param provider the resource provider
150      * @return the newly created component
151      * @throws LoomException if an error occurs when the component passes
152      * through a specific lifecycle stage
153      */
154     public Object   startup( final String   name,
155                            final Object   entry,
156                            final ResourceProvider provider )
157         throws LoomException
158     {
159         int stage = 0;
160         try
161         {
162             //Creation stage
163             stage = STAGE_CREATE;
164             notice( name, stage );
165             final Object   object = provider.createObject( entry );
166             final InstrumentManager instrumentManager = provider.createInstrumentManager(
167                 entry );
168 
169             //LogEnabled stage
170             stage = STAGE_LOGGER;
171             if( object instanceof LogEnabled )
172             {
173                 notice( name, stage );
174                 final Logger logger = provider.createLogger( entry );
175                 ContainerUtil.enableLogging( object, logger );
176             }
177 
178             //InstrumentManageable stage
179             stage = STAGE_INSTRUMENTMGR;
180             if( object instanceof InstrumentManageable )
181             {
182                 notice( name, stage );
183 
184                 ( (InstrumentManageable)object ).setInstrumentManager(
185                     instrumentManager );
186             }
187 
188             //Contextualize stage
189             stage = STAGE_CONTEXT;
190             if( object instanceof Contextualizable )
191             {
192                 notice( name, stage );
193                 final Context context = provider.createContext( entry );
194                 ContainerUtil.contextualize( object, context );
195             }
196 
197             //Composition stage
198             stage = STAGE_COMPOSE;
199             if( object instanceof Serviceable )
200             {
201                 notice( name, stage );
202                 final ServiceManager manager =
203                     provider.createServiceManager( entry );
204                 ContainerUtil.service( object, manager );
205             }
206             else if( object instanceof Composable )
207             {
208                 notice( name, stage );
209                 final ComponentManager componentManager =
210                     provider.createComponentManager( entry );
211                 ContainerUtil.compose( object, componentManager );
212             }
213 
214             //Configuring stage
215             stage = STAGE_CONFIG;
216             if( object instanceof Configurable )
217             {
218                 notice( name, stage );
219                 final Configuration configuration =
220                     provider.createConfiguration( entry );
221                 ContainerUtil.configure( object, configuration );
222             }
223 
224             //Parameterizing stage
225             stage = STAGE_PARAMETER;
226             if( object instanceof Parameterizable )
227             {
228                 notice( name, stage );
229                 final Parameters parameters =
230                     provider.createParameters( entry );
231                 ContainerUtil.parameterize( object, parameters );
232             }
233 
234             //Initialize stage
235             stage = STAGE_INIT;
236             if( object instanceof Initializable )
237             {
238                 notice( name, stage );
239                 ContainerUtil.initialize( object );
240             }
241 
242             //InstrumentManageable stage
243             stage = STAGE_INSTRUMENTABLE;
244             if( object instanceof Instrumentable )
245             {
246                 notice( name, stage );
247                 final String   instrumentableName = provider.createInstrumentableName(
248                     entry );
249                 final Instrumentable instrumentable = (Instrumentable)object;
250                 instrumentable.setInstrumentableName( instrumentableName );
251                 instrumentManager.registerInstrumentable( instrumentable,
252                                                           instrumentableName );
253             }
254 
255             //Start stage
256             stage = STAGE_START;
257             if( object instanceof Startable )
258             {
259                 notice( name, stage );
260                 ContainerUtil.start( object );
261             }
262 
263             return object;
264         }
265         catch( final Throwable   t )
266         {
267             fail( name, stage, t );
268 
269             //fail() throws an exception so next
270             //line will never be executed
271             return null;
272         }
273     }
274 
275     /**
276      * Method to run a component through it's shutdown phase. Errors that occur
277      * during shutdown will be logged appropraitely.
278      *
279      * @param name the name of the component
280      * @param object the component to shutdown
281      * @throws LoomException if unable to process component
282      */
283     public void shutdown( final String   name,
284                           final Object   object )
285         throws LoomException
286     {
287         //Stage at which failure occured
288         int stage = 0;
289 
290         //Failure exception
291         Throwable   failure = null;
292 
293         //Stoppable stage
294         if( object instanceof Startable )
295         {
296             notice( name, STAGE_STOP );
297             try
298             {
299                 ContainerUtil.stop( object );
300             }
301             catch( final Throwable   t )
302             {
303                 safeFail( name, STAGE_STOP, t );
304                 failure = t;
305                 stage = STAGE_STOP;
306             }
307         }
308 
309         //Disposable stage
310         if( object instanceof Disposable )
311         {
312             notice( name, STAGE_DISPOSE );
313             try
314             {
315                 ContainerUtil.dispose( object );
316             }
317             catch( final Throwable   t )
318             {
319                 safeFail( name, STAGE_DISPOSE, t );
320                 failure = t;
321                 stage = STAGE_DISPOSE;
322             }
323         }
324 
325         notice( name, STAGE_DESTROY );
326 
327         if( null != failure )
328         {
329             fail( name, stage, failure );
330         }
331     }
332 
333     /**
334      * Utility method to report that a lifecycle stage is about to be
335      * processed.
336      *
337      * @param name the name of component that is the subject of the notice
338      * @param stage the lifecycle processing stage
339      */
340     private void notice( final String   name, final int stage )
341     {
342         if( getLogger().isDebugEnabled() )
343         {
344             final String   message =
345                 REZ.format( "lifecycle.stage.notice",
346                             name,
347                             new Integer  ( stage ) );
348             getLogger().debug( message );
349         }
350     }
351 
352     /**
353      * Utility method to report that there was an error processing specified
354      * lifecycle stage.
355      *
356      * @param name the name of component that caused failure
357      * @param stage the lefecycle stage
358      * @param t the exception thrown
359      */
360     private void safeFail( final String   name,
361                            final int stage,
362                            final Throwable   t )
363     {
364         //final String reason = t.getMessage();
365         final String   reason = t.toString();
366         final String   message =
367             REZ.format( "lifecycle.fail.error",
368                         name,
369                         new Integer  ( stage ),
370                         reason );
371         getLogger().error( message );
372     }
373 
374     /**
375      * Utility method to report that there was an error processing specified
376      * lifecycle stage. It will also re-throw an exception with a better error
377      * message.
378      *
379      * @param name the name of block that caused failure
380      * @param stage the stage
381      * @param t the exception thrown
382      * @throws LoomException containing error
383      */
384     private void fail( final String   name,
385                        final int stage,
386                        final Throwable   t )
387         throws LoomException
388     {
389         //final String reason = t.getMessage();
390         final String   reason = t.toString();
391         final String   message =
392             REZ.format( "lifecycle.fail.error",
393                         name,
394                         new Integer  ( stage ), reason );
395         getLogger().error( message );
396         throw new LoomException( message, t );
397     }
398 }
399
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags