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: /**
29: * <p>A variant on the {@link Adapter} interface designed to plug into a
30: * {@link KeyRelayingContainer} that will return different instances from
31: * {@link #getInstance(Object)} based on the <code>key</code> argument passed
32: * to it.</p>
33: *
34: * <p>Other than this minor difference, the {@link Adapter same underlying
35: * concepts and the same contracts} that apply to <code>Adapters</code> apply
36: * to <code>KeyAwareAdapters</code> as well.</p>
37: *
38: * @author <a href="mail at leosimons dot com">Leo Simons</a>
39: * @version $Id: KeyAwareAdapter.java,v 1.2 2004/01/08 14:51:59 lsimons Exp $
40: */
41: public interface KeyAwareAdapter {
42: /**
43: * Retrieve an instance from this adapter. You should return this instance
44: * through {@link #releaseInstance(Object)} at some point before your
45: * program exits.
46: *
47: * @param key the criterion that the adapter should use to determine
48: * what instance to return.
49: *
50: * @return the instance. The provided reference shall never be
51: * <code>null</code>.
52: *
53: * @throws JicarillaIllegalAccessException if the adapter implementation
54: * has a problem accessing some external resource and is thus
55: * unable to return an instance.
56: * @throws JicarillaInvocationTargetException if the adapter implementation
57: * has a problem invoking some external resource and is thus
58: * unable to return an instance.
59: * @throws JicarillaInstantiationException if the adapter implementation
60: * has a problem creating the instance to return.
61: * @throws JicarillaClassNotFoundException if the adapter implementation
62: * tries to load a class to create an instance of, but the class
63: * cannot be loaded.
64: * @throws InitializationException if a miscellaneous problem occurs
65: * trying to create the instance to return.
66: * @throws JicarillaException if a miscellaneous exception occurs (an
67: * internal adapter error or an assertion failure, for example).
68: */
69: Object getInstance(Object key)
70: throws JicarillaIllegalAccessException,
71: JicarillaInvocationTargetException,
72: JicarillaInstantiationException,
73: JicarillaClassNotFoundException, InitializationException,
74: JicarillaException;
75:
76: /**
77: * Return the instance to this adapter. You should only return instances
78: * to this adapter if you have received them through
79: * {@link #getInstance(Object)}.
80: *
81: * @param instance the instance to release.
82: *
83: * @throws Exception if any kind of problem occurs releasing the instance.
84: * It is often considered safe to recover from this exception and
85: * continue normal application flow, but these exceptions should
86: * never be discarded lightly.
87: */
88: void releaseInstance(Object instance) throws Exception;
89: }
|