001: /* ====================================================================
002: The Jicarilla Software License
003:
004: Copyright (c) 2003 Leo Simons.
005: All rights reserved.
006:
007: Permission is hereby granted, free of charge, to any person obtaining
008: a copy of this software and associated documentation files (the
009: "Software"), to deal in the Software without restriction, including
010: without limitation the rights to use, copy, modify, merge, publish,
011: distribute, sublicense, and/or sell copies of the Software, and to
012: permit persons to whom the Software is furnished to do so, subject to
013: the following conditions:
014:
015: The above copyright notice and this permission notice shall be
016: included in all copies or substantial portions of the Software.
017:
018: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
019: EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
020: MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
021: IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
022: CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
023: TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
024: SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
025: ==================================================================== */
026: package org.jicarilla.container;
027:
028: /**
029: * <p>A resolver provides basic means to query, retrieve and return object
030: * instances from "something". This "something" is usually an implementation
031: * of the {@link ResolverProvider} interface, such as a {@link Container},
032: * but this does not have to be the case.</p>
033: *
034: * <p>In Jicarilla, the resolver is the central communication mechanism between
035: * the container and the adapters that it contains. In addition, resolvers are
036: * frequently passed on from adapters to {@link Factory} implementations. They
037: * are internally used by adapters and factories to provide the instances they
038: * manage with their dependencies and possibly with their configuration.</p>
039: *
040: * <p>However, the most important use of the resolver is by clients of the
041: * {@link Container}. After having filled the container with adapters, a client
042: * application retrieves a resolver from the container, which it then uses to
043: * gain access to the components it needs. Thus, the <code>Resolver</code>
044: * interface is usually your primary interface to the container. This is
045: * especially true if you use the
046: * {@link org.jicarilla.container.builder.DefaultBuilder} or another subclass
047: * of {@link org.jicarilla.container.builder.AbstractBuilder} to construct
048: * your container. In that case, you never retrieve a reference to the
049: * actual <code>Container</code> at all!</p>
050: *
051: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
052: * @version $Id: Resolver.java,v 1.3 2004/01/08 14:51:59 lsimons Exp $
053: */
054: public interface Resolver {
055: /**
056: * Retrieve an instance from this resolver. You should normally return this
057: * instance through {@link #releaseInstance(Object)} at some point before
058: * your program exits. For some instances, this may not be neccessary. For
059: * example, if this resolver was retrieved from a {@link Container} and the
060: * container in turn got the instance from an {@link Adapter} which does
061: * not require instances to be released, you do not need to call
062: * <code>releaseInstance()</code>. When in doubt, it is best to always call
063: * <code>releaseInstance()</code>.
064: *
065: * @param key the criterion that the resolver should use to determine
066: * what instance to return.
067: *
068: * @return an instance associated with the specified key. The provided
069: * reference shall never be <code>null</code>.
070: *
071: * @throws ResolutionException if no instance can be found for the
072: * provided key. To avoid this exception, use the
073: * {@link#contains(Object)} method to verify that the resolver
074: * believes to be able to provide an instance for a key.
075: * @throws JicarillaIllegalAccessException if the implementation
076: * has a problem accessing some external resource and is thus
077: * unable to return an instance.
078: * @throws JicarillaInvocationTargetException if the implementation
079: * has a problem invoking some external resource and is thus
080: * unable to return an instance.
081: * @throws JicarillaInstantiationException if the implementation
082: * has a problem creating the instance to return.
083: * @throws JicarillaClassNotFoundException if the implementation
084: * tries to load a class to create an instance of, but the class
085: * cannot be loaded.
086: * @throws InitializationException if a miscellaneous problem occurs
087: * trying to create the instance to return.
088: * @throws JicarillaException if a miscellaneous exception occurs (an
089: * internal adapter error or an assertion failure, for example).
090: */
091: Object get(Object key) throws ResolutionException,
092: JicarillaIllegalAccessException,
093: JicarillaInvocationTargetException,
094: JicarillaInstantiationException,
095: JicarillaClassNotFoundException, InitializationException,
096: JicarillaException;
097:
098: /**
099: * Retrieve multiple instances from this resolver. You should normally
100: * return these instances through {@link #releaseInstance(Object)} at some
101: * point before your program exits. For some instances, this may not be
102: * neccessary. For example, if this resolver was retrieved from a
103: * {@link Container} and the container in turn got these instances from
104: * {@link Adapter adapters} which do not require instances to be released,
105: * you do not need to call <code>releaseInstance()</code>. When in doubt,
106: * it is best to always call <code>releaseInstance()</code>.
107: *
108: * @param key the criterion that the resolver should use to determine
109: * what instances to return.
110: *
111: * @return all instances associated with the provided key. The provided
112: * references shall never be <code>null</code>, though the length
113: * of the returned array could be zero.
114: *
115: * @throws JicarillaIllegalAccessException if the implementation
116: * has a problem accessing some external resource and is thus
117: * unable to return an instance.
118: * @throws JicarillaInvocationTargetException if the implementation
119: * has a problem invoking some external resource and is thus
120: * unable to return an instance.
121: * @throws JicarillaInstantiationException if the implementation
122: * has a problem creating the instance to return.
123: * @throws JicarillaClassNotFoundException if the implementation
124: * tries to load a class to create an instance of, but the class
125: * cannot be loaded.
126: * @throws InitializationException if a miscellaneous problem occurs
127: * trying to create the instance to return.
128: * @throws JicarillaException if a miscellaneous exception occurs (an
129: * internal adapter error or an assertion failure, for example).
130: */
131: Object[] getAll(Object key) throws JicarillaIllegalAccessException,
132: JicarillaInvocationTargetException,
133: JicarillaInstantiationException,
134: JicarillaClassNotFoundException, InitializationException,
135: JicarillaException;
136:
137: /**
138: * <p>Determine whether the resolver believes it can provide an instance
139: * for the specified key. Note that if this method is true, that is not an
140: * absolute guarantee that {@link #get(Object)} or {@link #getAll(Object)}
141: * will not throw an exception, as other errors may occur as well. However,
142: * those other errors are much rarer.</p>
143: *
144: * <p>Also note that this method could potentially return false at one
145: * point and then true a brief moment later (or the other way around), and
146: * that {@link ResolutionException}s can still be thrown from
147: * <code>get()</code> and/or <code>getAll()</code> even if it does return
148: * true. However, such an event will be extremely rare.</p>
149: *
150: * @param key the criterion you wish to use as an argument to
151: * <code>get()</code> or <code>getAll()</code>
152: * @return true if the resolver believes it can provide an instance for
153: * the specified key, false otherwise
154: */
155: boolean contains(Object key);
156:
157: /**
158: * Return the instance to this resolver. You should normally return
159: * all instances you retrieve from this adapter, but see the
160: * {@link #get(Object) note} in the documentation for the
161: * <code>get()</code> method for more information.
162: *
163: * @param instance the instance to release.
164: *
165: * @throws Exception if any kind of problem occurs releasing the instance.
166: * It is often considered safe to recover from this exception and
167: * continue normal application flow, but these exceptions should
168: * never be discarded lightly.
169: */
170: void releaseInstance(Object instance) throws Exception;
171: }
|