01: /* ====================================================================
02: The Jicarilla Software License
03:
04: Copyright (c) 2003 Leo Simons.
05: All rights reserved.
06:
07: Permission is hereby granted, free of charge, to any person obtaining
08: a copy of this software and associated documentation files (the
09: "Software"), to deal in the Software without restriction, including
10: without limitation the rights to use, copy, modify, merge, publish,
11: distribute, sublicense, and/or sell copies of the Software, and to
12: permit persons to whom the Software is furnished to do so, subject to
13: the following conditions:
14:
15: The above copyright notice and this permission notice shall be
16: included in all copies or substantial portions of the Software.
17:
18: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
19: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
20: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
21: IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
22: CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
23: TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
24: SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
25: ==================================================================== */
26: package org.jicarilla.container.builder;
27:
28: import org.jicarilla.container.Resolver;
29:
30: /**
31: * Provides a convenient way to construct and initialize a
32: * {@link org.jicarilla.container.Container}.
33: *
34: * @todo better javadocs
35: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
36: * @version $Id: Builder.java,v 1.3 2004/03/23 15:59:51 lsimons Exp $
37: */
38: public interface Builder {
39: /**
40: * Retrieve a new instance.
41: *
42: * @return a new instance.
43: */
44: //public Builder newInstance();
45: /**
46: * Retrieve a new instance.
47: *
48: * @param containerClass the implementation class to use as the
49: * container. It shoul implement both the
50: * {@link org.jicarilla.container.Container} and the
51: * {@link org.jicarilla.container.KeyRelayingContainer}
52: * interfaces.
53: * @return a new instance.
54: */
55: //public Builder newInstance( final Class containerClass );
56: /**
57: * Retrieve a new instance.
58: *
59: * @param container the container to populate. It should implement
60: * the {@link org.jicarilla.container.Container} interface.
61: * @return a new instance.
62: */
63: //public Builder newInstance( final KeyRelayingContainer container );
64: /**
65: * Actually create the container instance and populate it with all
66: * the providers you have fed to the builder. You may not call any
67: * more methods on a <code>Builder</code> instance after you have
68: * called this method.
69: *
70: * @return a {@link Resolver} retrieved from the constructed container.
71: * @throws Exception if a problem occurs during the creation or population
72: * of the container or during the retrieval of the resolver from the
73: * container, or if the builder itself is in an illegal state.
74: */
75: Resolver create() throws Exception;
76:
77: /**
78: * Add a new component provider to the container.
79: *
80: * @param provider the provider to add.
81: * @return the current builder instance.
82: */
83: Builder addComponent(Object provider);
84:
85: /**
86: * Add a new component provider to the container.
87: *
88: * @param selectionCriterion the criterion to apply to the provider when
89: * determining what instances it can provide.
90: * @param provider the provider to add.
91: * @return the current builder instance.
92: */
93: Builder addComponent(Object selectionCriterion, Object provider);
94:
95: Resolver getResolver();
96: }
|