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;
27:
28: import org.jicarilla.lang.Selector;
29:
30: /**
31: * A container holds {@link Adapter adapters}, and provides a
32: * {@link Resolver resolver} to retrieve components from those adapters,
33: * and return them to those adapters.
34: *
35: * @see KeyRelayingContainer for a variant on this interface that
36: * supports the addition of {@link KeyAwareAdapter}s
37: * @see org.jicarilla.container.builder.DefaultBuilder for a helper class
38: * that makes it easier to create and populate container instances
39: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
40: * @version $Id: Container.java,v 1.7 2004/03/23 13:37:51 lsimons Exp $
41: */
42: public interface Container extends ResolverProvider {
43: /**
44: * Add a new {@link Adapter} to this container.
45: *
46: * @param selector the {@link Selector} that will be used to test
47: * whether the provided adapter can be used to provide an instance
48: * for a key requested from the {@link Resolver} returned from
49: * this container its {@link ResolverProvider#getResolver()}
50: * method.
51: * @param adapter an {@link Adapter} that will be used to help this
52: * container fulfill its {@link ResolverProvider} contract.
53: *
54: * @return this container.
55: *
56: * @throws IllegalSelectorException if the provided selector is not
57: * supported by this container (if it is null, for example, or
58: * if it is not a
59: * {@link org.jicarilla.lang.CriterionExposingSelector} and
60: * the container requires it to be).
61: * @throws IllegalAdapterException if the provided adapter is not
62: * supported by this container (if it is null, for example, or
63: * if it is not of some subtype that this container requires).
64: * @throws KeyAlreadyRegisteredException if the criterion exposed by a
65: * provided selector or a provided key itself is already registered and
66: * the container does not support duplicate keys.
67: * @throws JicarillaException if a miscellaneous exception occurs (an
68: * internal container error or an assertion failure, for example).
69: */
70: Container registerAdapter(Selector selector, Adapter adapter)
71: throws IllegalSelectorException, IllegalAdapterException,
72: KeyAlreadyRegisteredException, JicarillaException;
73:
74: /**
75: * Add a new {@link Adapter} to this container.
76: *
77: * @param key the criterion that will be used to test whether the
78: * provided adapter can be used to provide an instance
79: * for a requested key.
80: * @param adapter an {@link Adapter} that will be used to help this
81: * container fulfill its {@link ResolverProvider} contract.
82: *
83: * @return this container.
84: *
85: * @throws IllegalAdapterException if the provided adapter is not
86: * supported by this container (if it is null, for example, or
87: * if it is not of some subtype that this container requires).
88: * @throws KeyAlreadyRegisteredException if the criterion exposed by a
89: * provided selector or a provided key itself is already registered and
90: * the container does not support duplicate keys.
91: * @throws JicarillaException if a miscellaneous exception occurs (an
92: * internal container error or an assertion failure, for example).
93: */
94: Container registerAdapter(Object key, Adapter adapter)
95: throws IllegalAdapterException,
96: KeyAlreadyRegisteredException, JicarillaException;
97: }
|