1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.di;
17
18 /**
19 * <p>
20 * Definition of an interface that provides access to dependencies defined by a
21 * {@link BeanProvider}.
22 * </p>
23 * <p>
24 * This interface is used by a {@link BeanProvider}
25 * implementation for resolving its dependencies to other beans. An
26 * implementation of this interface is passed to the bean provider's
27 * <code>getBean()</code> method, allowing access to the required
28 * dependencies. By extending the <code>ClassLoaderProvider</code> interface
29 * functionality for dealing with dynamic class loading is also available through
30 * this interface.
31 * </p>
32 * <p>
33 * Note that this interface is used internally by the framework. Clients
34 * probably won't have to deal with it directly. It is only of importance for
35 * custom implementations of the {@link BeanProvider} interface.
36 * </p>
37 *
38 * @author Oliver Heger
39 * @version $Id: DependencyProvider.java 205 2012-01-29 18:29:57Z oheger $
40 */
41 public interface DependencyProvider extends ClassLoaderProvider
42 {
43 /**
44 * Returns the dependency bean for the specified dependency. This dependency
45 * must have been part of the collection of dependencies returned by the
46 * bean provider's <code>getDependencies()</code> method.
47 *
48 * @param dependency the dependency pointing to the bean in question
49 * @return the bean for this dependency
50 * @throws InjectionException if the bean cannot be resolved
51 */
52 Object getDependentBean(Dependency dependency);
53
54 /**
55 * Checks whether the bean specified by the given <code>Dependency</code>
56 * is currently available. This method can be used by complex bean providers
57 * to find out whether an initialization of their managed bean is now
58 * possible. Because of cyclic dependencies it may be the case that a
59 * required dependency cannot be resolved now. The affected bean provider
60 * can then register itself as an <em>initializer</em> and try again after
61 * the creation phase has completed.
62 *
63 * @param dependency the dependency pointing to the bean in question
64 * @return a flag whether this bean is currently available
65 * @throws InjectionException if the dependency cannot be resolved
66 * @see #addInitializer(BeanInitializer)
67 */
68 boolean isBeanAvailable(Dependency dependency);
69
70 /**
71 * Registers a <code>BeanInitializer</code>. This object will be called
72 * at the end of the transaction when all beans have been created. This
73 * gives complex bean providers an opportunity of trying some
74 * initializations again that were not possible before because of cyclic
75 * dependencies. A concrete implementation has to ensure that the
76 * initializers registered here are always called before the current
77 * transaction ends - no matter whether it succeeds or fails.
78 *
79 * @param initializer the initializer to register
80 */
81 void addInitializer(BeanInitializer initializer);
82
83 /**
84 * Notifies this {@code DependencyProvider} about the creation of a bean.
85 * This method has to be called by {@code BeanProvider} implementations when
86 * a new bean has been completely created. It allows the framework to
87 * perform some post processing, e.g. enhanced initialization of the new
88 * bean or notification of context listeners.
89 *
90 * @param bean the newly created bean
91 * @param provider the {@code BeanProvider} responsible for this bean
92 */
93 void beanCreated(Object bean, BeanProvider provider);
94
95 /**
96 * Sets the {@link BeanContext} that is responsible for a
97 * {@link BeanCreationEvent} notification. This method can be used by
98 * implementations of the {@code BeanContext} interface that wrap other
99 * contexts, e.g. a combined bean context. Such wrapping contexts usually
100 * delegate to other contexts when a bean is requested. If such a request
101 * causes a new bean to be created, the corresponding {@code
102 * BeanCreationEvent} per default has the wrapped context as its source, and
103 * also a {@link BeanContextClient} object will be initialized with this
104 * context. However, it may be appropriate to set the wrapping context as
105 * source. This can be achieved by registering a
106 * {@link BeanCreationListener} at the wrapped contexts. In the event
107 * handling method the {@code setCreationBeanContext()} can be called with
108 * the wrapping context as parameter. Then correct creation context is known
109 * and can also be passed to a {@link BeanContextClient}.
110 *
111 * @param context the {@code BeanContext} responsible for a bean creation
112 */
113 void setCreationBeanContext(BeanContext context);
114
115 /**
116 * Returns a reference to the current {@link InvocationHelper} object. This
117 * helper object can be used by bean providers for more advanced operations
118 * related to reflection, e.g. method invocations or data type conversions.
119 * Especially the data type conversion facilities provided by
120 * {@link InvocationHelper} may be of interest. The object returned by an
121 * implementation should be a central instance, i.e. the same instance that
122 * has been used for registering custom converter implementations.
123 *
124 * @return the current {@code InvocationHelper} object
125 */
126 InvocationHelper getInvocationHelper();
127 }