MentaContainer

Rev

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