Rev 4 | Go to most recent revision | Details | 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> |
||
| 11 | * <li> Injection</li> |
||
| 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. |
||
| 37 | * @return The container itself. (Fluent API) |
||
| 38 | */ |
||
| 39 | public Container ioc(String key, Class<? extends Object> klass, boolean singleton); |
||
| 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 |
||
| 47 | * @return The container itself. (Fluent API) |
||
| 48 | */ |
||
| 49 | public Container ioc(String key, Class<?extends Object> klass); |
||
| 50 | |||
| 51 | /** |
||
| 52 | * Configure a bean dependency to be auto-wired by the container. The dependency should be |
||
| 53 | * an interface otherwise an exception is thrown. It works like that: |
||
| 54 | * |
||
| 55 | * Whenever the container returns a bean, it checks to see if it has a property named <i>property</i> |
||
| 56 | * and if the type of the property is <i>klass</i>. If it does, then it looks for a bean named |
||
| 57 | * <i>source</i> and injects it inside the first bean it is returning. This approach is recursive |
||
| 58 | * so all properties are checked up the class hierarchy, until it reaches Object. |
||
| 59 | * |
||
| 60 | * @param property a bean property that will require another bean, in other words, the required |
||
| 61 | * bean will be injected in the property of the bean been requested from the container. (auto-wiring by name) |
||
| 62 | * @param klass an interface, not an implementation, defining the type of the auto-wiring. (auto-wiring by type) |
||
| 63 | * @param source The dependency itself, coming from the container as well, in other words, the bean that will be injected in the original bean |
||
| 64 | * @return The container itself. (Fluent API) |
||
| 65 | */ |
||
| 66 | public Container autowire(String property, Class<? extends Object> klass, String source); |
||
| 67 | |||
| 68 | /** |
||
| 69 | * Same as {@link #get(String)} except that it passes the property name as the source name, in other words, |
||
| 70 | * the property name is the same as the bean name that will be injected as the dependency. |
||
| 71 | * |
||
| 72 | * @param property |
||
| 73 | * @param klass |
||
| 74 | * @return The container itself. (Fluent API) |
||
| 75 | */ |
||
| 76 | public Container autowire(String property, Class<? extends Object> klass); |
||
| 77 | |||
| 78 | /** |
||
| 79 | * Add a constructor parameter that will be used by the container to instantiate the bean. The container keeps the order of the parameters |
||
| 80 | * in case this method gets called more than once for the same bean, in other words, it assumes that the bean constructor takes more than |
||
| 81 | * one parameter. |
||
| 82 | * |
||
| 83 | * @param key The key representing the bean to return. The name of the bean in the container. |
||
| 84 | * @param obj The constructor parameter value. |
||
| 85 | * @return The container itself. (Fluent API) |
||
| 86 | */ |
||
| 87 | public Container init(String key, Object obj); |
||
| 88 | |||
| 89 | /** |
||
| 90 | * Add a property that will be injected by the container in the bean it instantiates. To be not confused with auto-wiring. Here we are just passing |
||
| 91 | * static values to be injected in the bean. Auto-wiring wires anything because it is based on interfaces and NOT on implementations. |
||
| 92 | * |
||
| 93 | * @param key The key representing the bean to return. The name of the bean in the container. |
||
| 94 | * @param name The name of the bean property (bean must provide a property setter) |
||
| 95 | * @param obj The value of the property that will be injected. |
||
| 96 | * @return The container itself. (Fluent API) |
||
| 97 | */ |
||
| 98 | public Container set(String key, String name, Object obj); |
||
| 99 | |||
| 100 | /** |
||
| 101 | * Take a given bean and populate its properties with other beans coming from this container. Perhaps you can call this auto-wiring. |
||
| 102 | * You basically checking properties of the given bean and looking for values (by name and type!) inside the container. And injecting |
||
| 103 | * in the given bean, in other words, populating it. |
||
| 104 | * |
||
| 105 | * @param bean The bean to be populated with other beans from the container. |
||
| 106 | * @return The container itself. (Fluent API) |
||
| 107 | */ |
||
| 108 | public Container populate(Object bean); |
||
| 109 | } |