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 import java.util.Set;
19
20 /**
21 * <p>
22 * Definition of an interface for objects that provide access to bean
23 * definitions.
24 * </p>
25 * <p>
26 * A <code>BeanStore</code> maintains an arbitrary number of bean definitions,
27 * which are identified by unique names. It is possible to list the names of all
28 * available bean definitions, and to access a specific bean definition by its
29 * name.
30 * </p>
31 * <p>
32 * <code>BeanStore</code>s are hierarchical structures: they can have a
33 * parent. A typical search algorithm an a {@code BeanStore}
34 * will first query the local store, and then - if the specified bean
35 * definition could not be found - delegate to its parent store. This allows for
36 * complex scenarios where global objects can be defined on the application
37 * level, while certain sub contexts have the opportunity of overriding some
38 * definitions and define their own local data.
39 * </p>
40 * <p>
41 * This interface is kept quite simple. It should be easy to implement it, e.g.
42 * using a map or another context-like object.
43 * </p>
44 *
45 * @author Oliver Heger
46 * @version $Id: BeanStore.java 205 2012-01-29 18:29:57Z oheger $
47 */
48 public interface BeanStore
49 {
50 /**
51 * Returns the <code>BeanProvider</code> that is registered under the
52 * given name or <b>null</b> if cannot be found.
53 *
54 * @param name the name of the <code>BeanProvider</code>
55 * @return the provider registered under this name or <b>null</b>
56 */
57 BeanProvider getBeanProvider(String name);
58
59 /**
60 * Returns a set with the names of all <code>BeanProvider</code> objects
61 * that are registered in this bean store.
62 *
63 * @return a set with the names of the contained <code>BeanProvider</code>s
64 */
65 Set<String> providerNames();
66
67 /**
68 * Returns a name for this bean store. The name is mainly used for grouping
69 * and accessing bean stores. It does not have a direct impact on bean
70 * creation or dependency injection.
71 *
72 * @return a name for this bean store
73 */
74 String getName();
75
76 /**
77 * Returns a reference to the parent <code>BeanStore</code>. Bean stores
78 * can be organized in a hierarchical manner: if a bean provider cannot be
79 * found in a specific bean store, the framework will also search its parent
80 * bean store (and recursively the parent's parent, and so on). This makes
81 * it possible to create different scopes of beans. The root store should
82 * return <b>null</b>.
83 *
84 * @return the parent bean store or <b>null</b> if this is the root store
85 */
86 BeanStore getParent();
87
88 /**
89 * Returns a {@code ConversionHelper} object for performing type conversions
90 * on the beans contained in this {@code BeanStore}. To the hierarchy of
91 * {@code BeanStore} objects also {@code ConversionHelper} objects can be
92 * added. This is useful when dealing with specialized beans for which
93 * custom converters have to be provided. A {@code ConversionHelper} is
94 * optional, so an implementation can return <b>null</b>. It is then up to
95 * the caller whether it uses a default {@code ConversionHelper} instance or
96 * tries to query the parent bean store.
97 *
98 * @return a {@code ConversionHelper} instance for performing type
99 * conversions related to the beans contained in this store
100 */
101 ConversionHelper getConversionHelper();
102 }