001    /*****************************************************************************
002     * Copyright (C) PicoContainer Organization. All rights reserved.            *
003     * ------------------------------------------------------------------------- *
004     * The software in this package is published under the terms of the BSD      *
005     * style license a copy of which has been included with this distribution in *
006     * the LICENSE.txt file.                                                     *
007     *                                                                           *
008     * Original code by Paul Hammant & Obie Fernandez & Aslak                    *
009     *****************************************************************************/
010    
011    package org.picocontainer;
012    
013    import org.picocontainer.injectors.AbstractInjector;
014    
015    import java.lang.reflect.Constructor;
016    import java.lang.reflect.Member;
017    import java.lang.reflect.Method;
018    
019    /**
020     * A component monitor is responsible for monitoring the component instantiation
021     * and method invocation.
022     * 
023     * @author Paul Hammant
024     * @author Obie Fernandez
025     * @author Aslak Hellesøy
026     * @author Mauro Talevi
027     */
028    public interface ComponentMonitor {
029    
030        /**
031         * Event thrown as the component is being instantiated using the given constructor
032         *
033         * @param container
034         * @param componentAdapter
035         * @param constructor the Constructor used to instantiate the addComponent @return the constructor to use in instantiation (nearly always the same one as passed in)
036         */
037        <T> Constructor<T> instantiating(PicoContainer container, ComponentAdapter<T> componentAdapter,
038                                  Constructor<T> constructor
039        );
040    
041        /**
042         * Event thrown after the component has been instantiated using the given constructor.
043         * This should be called for both Constructor and Setter DI.
044         *
045         * @param container
046         * @param componentAdapter
047         * @param constructor the Constructor used to instantiate the addComponent
048         * @param instantiated the component that was instantiated by PicoContainer
049         * @param injected the components during instantiation.
050         * @param duration the duration in milliseconds of the instantiation
051         */
052    
053        <T> void instantiated(PicoContainer container, ComponentAdapter<T> componentAdapter,
054                          Constructor<T> constructor,
055                          Object instantiated,
056                          Object[] injected,
057                          long duration);
058    
059        /**
060         * Event thrown if the component instantiation failed using the given constructor
061         * 
062         * @param container
063         * @param componentAdapter
064         * @param constructor the Constructor used to instantiate the addComponent
065         * @param cause the Exception detailing the cause of the failure
066         */
067        <T> void instantiationFailed(PicoContainer container,
068                                 ComponentAdapter<T> componentAdapter,
069                                 Constructor<T> constructor,
070                                 Exception cause);
071    
072        /**
073         * Event thrown as the component method is being invoked on the given instance
074         * 
075         * @param container
076         * @param componentAdapter
077         * @param member
078         * @param instance the component instance
079         */
080        void invoking(PicoContainer container, ComponentAdapter<?> componentAdapter, Member member, Object instance);
081    
082        /**
083         * Event thrown after the component method has been invoked on the given instance
084         * 
085         * @param container
086         * @param componentAdapter
087         * @param method the Method invoked on the component instance
088         * @param instance the component instance
089         * @param duration the duration in millis of the invocation
090         */
091        void invoked(PicoContainer container,
092                     ComponentAdapter<?> componentAdapter,
093                     Method method,
094                     Object instance,
095                     long duration);
096    
097        /**
098         * Event thrown if the component method invocation failed on the given instance
099         * 
100         * @param member
101         * @param instance the component instance
102         * @param cause the Exception detailing the cause of the failure
103         */
104        void invocationFailed(Member member, Object instance, Exception cause);
105    
106        /**
107         * Event thrown if a lifecycle method invocation - start, stop or dispose - 
108         * failed on the given instance
109         *
110         * @param container
111         * @param componentAdapter
112         * @param method the lifecycle Method invoked on the component instance
113         * @param instance the component instance
114         * @param cause the RuntimeException detailing the cause of the failure
115         */
116         void lifecycleInvocationFailed(MutablePicoContainer container,
117                                       ComponentAdapter<?> componentAdapter, Method method,
118                                       Object instance,
119                                       RuntimeException cause);
120    
121    
122        /**
123         * No Component has been found for the key in question. Implementors of this have a last ditch opportunity to
124         * specify something for the need.
125         *
126         * @param container
127         * @param componentKey
128         */
129        Object noComponentFound(MutablePicoContainer container, Object componentKey);
130    
131        /**
132         * A mechanism to monitor or override the AbstractInjectors being made for components.
133         *
134         * @param abstractInjector the abstract injector the container intends to use for the component currently being added.
135         * @return an abstract Injector. For most implementations, the same one as was passed in.
136         */
137        AbstractInjector newInjectionFactory(AbstractInjector abstractInjector);
138    }