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ø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. 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 }