MentaContainer

Rev

Rev 45 | Rev 57 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 soliveira 1
package org.mentacontainer;
2
 
3
/**
4
 * A very simple container that provides:
5
 * <ul>
6
 *   <li> Bean instantiation (duh!)</li>
7
 *   <li> Constructor injection for bean setup</li>
8
 *   <li> Setter injection for bean setup</li>
9
 *   <li> Auto-wiring based on name and type</li>
10
 *   <li> Singleton</li>
20 soliveira 11
 *   <li> Wiring of external beans with the beans configured in this container</li>
25 soliveira 12
 *   <li> Annotation and XML free (programmatic configuration is the way to go!)
2 soliveira 13
 * </ul>
14
 *
15
 * It does not get much simpler than that.
16
 *
17
 * @author sergio.oliveira.jr@gmail.com
18
 *
19
 */
20
public interface Container {
21
 
22
        /**
23
         * Get an instance from the container.
24
         *
25
         * The instance will be fully initialized (constructor and/or setters) and fully wired.
26
         *
27
         * @param key The key representing the bean to return. The name of the bean in the container.
28
         * @return The fully initialized and wired bean.
29
         */
41 soliveira 30
        public <T> T get(String key);
2 soliveira 31
 
32
        /**
33
         * Configure a bean to be returned with the given implementation when {@link #get(String)} is called.
34
         *
35
         * @param key The key representing the bean to return. The name of the bean in the container.
36
         * @param klass The class used to instantiate the bean, in other words, its implementation.
37
         * @param singleton A boolean to indicate if this bean will be a singleton.
45 soliveira 38
         * @return The component created as a ConfigurableComponent. (Fluent API)
2 soliveira 39
         */
45 soliveira 40
        public ConfigurableComponent ioc(String key, Class<? extends Object> klass, boolean singleton);
2 soliveira 41
 
42
        /**
21 soliveira 43
         * Same as {@link #ioc(String, Class, boolean)} except that it assumes
2 soliveira 44
         * singleton is false.
45
         *
46
         * @param key
47
         * @param klass
45 soliveira 48
         * @return The component created as a ConfigurableComponent. (Fluent API)
2 soliveira 49
         */
45 soliveira 50
        public ConfigurableComponent ioc(String key, Class<?extends Object> klass);
2 soliveira 51
 
52
        /**
20 soliveira 53
         * Set up IoC based on the component passed.
2 soliveira 54
         *
39 soliveira 55
         * @param key The key representing the bean to return. The name of the bean in the container.
20 soliveira 56
         * @param component The component for the IoC.
45 soliveira 57
         * @return The component passed as a parameter.
21 soliveira 58
         * @see Component
20 soliveira 59
         */
39 soliveira 60
        public Component ioc(String key, Component component);
20 soliveira 61
 
62
        /**
51 soliveira 63
         * Set up IoC based on the component passed. Specify whether this will be a singleton component.
64
         *
65
         * @param key The key representing the bean to return. The name of the bean in the container.
66
         * @param component The component for the IoC.
67
         * @param isSingleton Should this component be treated as a singleton?
68
         * @return The component passed as a parameter.
69
         * @see Component
70
         */
71
        public Component ioc(String key, Component component, boolean isSingleton);
72
 
73
        /**
20 soliveira 74
         * Configure a bean dependency to be auto-wired by the container. In general you want the
75
         * type of the dependency to be an interface, for loosely couple dependencies. It works like that:<br/><br/>
76
         *
2 soliveira 77
         * Whenever the container returns a bean, it checks to see if it has a property named <i>property</i>
78
         * and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named
79
         * <i>source</i> and injects it inside the first bean it is returning. This approach is recursive
80
         * so all properties are checked up the class hierarchy, until it reaches Object.
81
         *
82
         * @param property a bean property that will require another bean, in other words, the required
83
         *                                 bean will be injected in the property of the bean been requested from the container. (auto-wiring by name)
20 soliveira 84
         * @param klass the type of the dependency, in other words, the type of the auto-wiring. (auto-wiring by type)
2 soliveira 85
         * @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean
86
         * @return The container itself. (Fluent API)
87
         */
20 soliveira 88
        public Dependency autowire(String property, Class<? extends Object> klass, String source);
2 soliveira 89
 
90
        /**
21 soliveira 91
         * Same as {@link #autowire(String, Class, String)} except that it assumes that the property name will be the source name, in other words,
2 soliveira 92
         * the property name is the same as the bean name that will be injected as the dependency.
93
         *
94
         * @param property
95
         * @param klass
96
         * @return The container itself. (Fluent API)
97
         */
20 soliveira 98
        public Dependency autowire(String property, Class<? extends Object> klass);
2 soliveira 99
 
100
        /**
21 soliveira 101
         * Setup a dependency.
2 soliveira 102
         *
21 soliveira 103
         * @param dependency The dependency to setup
104
         * @return The dependency itself. (Fluent API)
105
         * @see Dependency
2 soliveira 106
         */
20 soliveira 107
        public Dependency autowire(Dependency dependency);
2 soliveira 108
 
109
        /**
110
         * Take a given bean and populate its properties with other beans coming from this container. Perhaps you can call this auto-wiring.
111
         * You basically checking properties of the given bean and looking for values (by name and type!) inside the container. And injecting
112
         * in the given bean, in other words, populating it.
113
         *
114
         * @param bean The bean to be populated with other beans from the container.
115
         * @return The container itself. (Fluent API)
116
         */
40 soliveira 117
        public Container populate(Object bean);
4 soliveira 118
 
119
        /**
120
         * Check whether the container is configured to provide a bean with name 'key'.
121
         *
122
         * @param key The key representing the bean inside the container.
123
         * @return true if the container contains this bean.
124
         */
125
        public boolean contains(String key);
2 soliveira 126
}