    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 java.lang.reflect.Constructor;
    014    import java.lang.reflect.Member;
    015    import java.lang.reflect.Method;
    016
    017    /**
    018     * A component monitor is responsible for monitoring the component instantiation
    019     * and method invocation.
    020     *
    021     * @author Paul Hammant
    022     * @author Obie Fernandez
    023     * @author Aslak Helles&oslash;y
    024     * @author Mauro Talevi
    025     */
    026    public interface ComponentMonitor {
    027
    028        Object KEEP = new Object();
    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         * @param args
    080         */
    081        Object invoking(PicoContainer container, ComponentAdapter<?> componentAdapter, Member member, Object instance, Object[] args);
    082
    083        /**
    084         * Event thrown after the component method has been invoked on the given instance
    085         *
    086         * @param container
    087         * @param componentAdapter
    088         * @param member
    089         * @param instance the component instance
    090         * @param duration
    091         * @param args
    092         * @param retVal
    093         */
    094        void invoked(PicoContainer container,
    095                     ComponentAdapter<?> componentAdapter,
    096                     Member member,
    097                     Object instance,
    098                     long duration, Object[] args, Object retVal);
    099
    100        /**
    101         * Event thrown if the component method invocation failed on the given instance
    102         *
    103         * @param member
    104         * @param instance the component instance
    105         * @param cause the Exception detailing the cause of the failure
    106         */
    107        void invocationFailed(Member member, Object instance, Exception cause);
    108
    109        /**
    110         * Event thrown if a lifecycle method invocation - start, stop or dispose -
    111         * failed on the given instance
    112         *
    113         * @param container
    114         * @param componentAdapter
    115         * @param method the lifecycle Method invoked on the component instance
    116         * @param instance the component instance
    117         * @param cause the RuntimeException detailing the cause of the failure
    118         */
    119         void lifecycleInvocationFailed(MutablePicoContainer container,
    120                                       ComponentAdapter<?> componentAdapter, Method method,
    121                                       Object instance,
    122                                       RuntimeException cause);
    123
    124        /**
    125         * No Component has been found for the key in question. Implementors of this have a last chance opportunity to
    126         * specify something for the need.  This is only relevant to component dependencies, and not to
    127         * container.getComponent(<key>) in your user code.
    128         *
    129         * @param container
    130         * @param componentKey
    131         */
    132        Object noComponentFound(MutablePicoContainer container, Object componentKey);
    133
    134        /**
    135         * A mechanism to monitor or override the Injectors being made for components.
    136         *
    137         * @param injector
    138         * @return an Injector. For most implementations, the same one as was passed in.
    139         */
    140        Injector newInjector(Injector injector);
    141
    142        /**
    143         * A mechanism to monitor or override the Behaviors being made for components.
    144         *
    145         * @param behavior
    146         * @return an Behavior. For most implementations, the same one as was passed in.
    147         */
    148        Behavior newBehavior(Behavior behavior);
    149    }