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>An adapter is used to plug "something" into a {@link Container}. This
030: * "something" can actually be anything (since {@link #getInstance()} returns
031: * an {@link Object} and {@link #releaseInstance(Object)} is not required to
032: * do anything. The use of the word "adapter" refers to an analogy between
033: * your software design and home electronics. Just like many home electronics
034: * devices need a custom power adapter to be plugged into a power socket,
035: * your objects need an adapter to be plugged into a container.</p>
036: *
037: * <p>There's several common kinds of adapters:</p>
038: * <ul>
039: * <li><b>factories</b>. These will usually create a new instance when
040: * <code>getInstance()</code> is called, and will destroy the instance
041: * when <code>releaseInstance()</code> is called.</li>
042: * <li><b>directories</b>. These will not create a new instance
043: * themselves, but rather look one up in some kind of registry or
044: * directory, for example from a {@link Resolver} or
045: * <a href="http://java.sun.com/products/jndi/">JNDI</a>.</li>
046: * <li><b>adapter-adapters</b>. These will usually not do much, but they will
047: * provide an interface to some other adapter that the container can use.
048: * In the home electronics analogy, you may want to use a home
049: * electronics device whose plug doesn't fit in your power socket
050: * (like European plugs in an American power socket). In that case, you
051: * will usually put in place a small power plug adapter between the
052: * power plug and the power socket.</li>
053: * </ul>
054: *
055: * <p>Of course, other types of adapters from those mentioned may exist.</p>
056: *
057: * <p>Adapters are normally associated with some kind of selection
058: * mechanism inside the container. In the case of the {@link Container}
059: * interface. that selection mechanism is either a key (similar to the keys
060: * used in {@link java.util.Map maps} or an instance of a
061: * {@link org.jicarilla.lang.Selector}.</p>
062: *
063: * <p>Note that it is usually possible to use an adapter without using a
064: * container. When doing so, observe these contracts:</p>
065: *
066: * <ul>
067: * <li><b>method call ordering</b>. You may not call
068: * <code>releaseInstance()</code> until you have called
069: * <code>getInstance()</code> at least once.</li>
070: * <li><b>method call pairing</b>. You should call
071: * <code>releaseInstance()</code> once for every time you call
072: * <code>getInstance()</code>, and the parameter to
073: * <code>releaseInstance()</code> must be the object you received
074: * from <code>getInstance()</code>.</li>
075: * </ul>
076: * <p><i>(note that it is legal to call <code>getInstance()</code>
077: * multiple times in a row and then call <code>releaseInstance()</code>
078: * multiple times in a row.)</i></p>
079: *
080: * <p>Also note that some <code>Adapter</code> implementations may be less
081: * strict about these rules. See the documentation for those implementations
082: * to be sure.</p>
083: *
084: * @see KeyAwareAdapter for a variant of this interface that alters its
085: * behaviour based on what is requested from it
086: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
087: * @version $Id: Adapter.java,v 1.3 2004/03/23 13:37:51 lsimons Exp $
088: */
089: public interface Adapter {
090: /**
091: * Retrieve an instance from this adapter. You should return this instance
092: * through {@link #releaseInstance(Object)} at some point before your
093: * program exits.
094: *
095: * @return the instance. The provided reference shall never be
096: * <code>null</code>.
097: *
098: * @throws JicarillaIllegalAccessException if the adapter implementation
099: * has a problem accessing some external resource and is thus
100: * unable to return an instance.
101: * @throws JicarillaInvocationTargetException if the adapter implementation
102: * has a problem invoking some external resource and is thus
103: * unable to return an instance.
104: * @throws JicarillaInstantiationException if the adapter implementation
105: * has a problem creating the instance to return.
106: * @throws JicarillaClassNotFoundException if the adapter implementation
107: * tries to load a class to create an instance of, but the class
108: * cannot be loaded.
109: * @throws InitializationException if a miscellaneous problem occurs
110: * trying to create the instance to return.
111: * @throws JicarillaException if a miscellaneous exception occurs (an
112: * internal adapter error or an assertion failure, for example).
113: */
114: Object getInstance() throws JicarillaIllegalAccessException,
115: JicarillaInvocationTargetException,
116: JicarillaInstantiationException,
117: JicarillaClassNotFoundException, InitializationException,
118: JicarillaException;
119:
120: /**
121: * Return the instance to this adapter. You should only return instances
122: * to this adapter if you have received them through
123: * {@link #getInstance()}.
124: *
125: * @param instance the instance to release.
126: *
127: * @throws Exception if any kind of problem occurs releasing the instance.
128: * It is often considered safe to recover from this exception and
129: * continue normal application flow, but these exceptions should
130: * never be discarded lightly.
131: */
132: void releaseInstance(Object instance) throws Exception;
133: }
|