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
011package org.picocontainer;
012
013import java.lang.reflect.Constructor;
014import java.lang.reflect.Member;
015import 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øy
024 * @author Mauro Talevi
025 */
026public 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. Implementers 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}