    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.behaviors.Cached;
    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&oslash;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 Injectors being made for components.
    133         *
    134         * @param injector
    135         * @return an Injector. For most implementations, the same one as was passed in.
    136         */
    137        Injector newInjector(Injector injector);
    138
    139        /**
    140         * A mechanism to monitor or override the Behaviors being made for components.
    141         *
    142         * @param behavior
    143         * @return an Behavior. For most implementations, the same one as was passed in.
    144         */
    145        Behavior newBehavior(Behavior behavior);
    146    }