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 factory is responsible for creating new instances of "something".
030: * Factories are commonly used in the implementation of {@link Adapter
031: * adapters}.</p>
032: *
033: * <p>Note that while the interfaces for adapters and factories are nearly the
034: * same, the two don't do quite the same thing. Whereas an adapter is intended
035: * to be associated with a {@link Container} through the use of a
036: * {@link org.jicarilla.lang.Selector} and is not required to always
037: * return a new instance from its {@link Adapter#getInstance()} method, the
038: * factory must always return a <i>new</i> instance on every call to its
039: * {@link #newInstance()} method, and is never directly associated with a
040: * container.</p>
041: *
042: * <p>If you do wish to add a factory implementation to a container, you should
043: * use one of {@link org.jicarilla.containers.adapters several available} to
044: * wrap the factory.</p>
045: *
046: * <p>Note that it is usually quite possible to use a factory without using an
047: * adapter or a container. When you do, observe these contracts:</p>
048: *
049: * <ul>
050: * <li><b>method call ordering</b>. You may not call
051: * <code>releaseInstance()</code> until you have called
052: * <code>newInstance()</code> at least once.</li>
053: * <li><b>method call pairing</b>. You should call
054: * <code>releaseInstance()</code> once for every time you call
055: * <code>newInstance()</code>, and the parameter to
056: * <code>releaseInstance()</code> must be the object you received
057: * from <code>newInstance()</code>.</li>
058: * </ul>
059: * <p><i>(note that it is legal to call <code>newInstance()</code>
060: * multiple times in a row and then call <code>releaseInstance()</code>
061: * multiple times in a row.)</i></p>
062: *
063: * <p>Also note that some <code>Factory</code> implementations may be less
064: * strict about these rules. See the documentation for those implementations
065: * to be sure.</p>
066: *
067: * @author <a href="lsimons at jicarilla dot org">Leo Simons</a>
068: * @version $Id: Factory.java,v 1.4 2004/03/23 13:37:51 lsimons Exp $
069: */
070: public interface Factory {
071: /**
072: * Retrieve a new instance from this factory. You should return this
073: * instance through {@link #releaseInstance(Object)} at some point before
074: * your program exits.
075: *
076: * @return the instance. The provided reference shall never be
077: * <code>null</code>.
078: *
079: * @throws JicarillaIllegalAccessException if the factory implementation
080: * has a problem accessing some external resource and is thus
081: * unable to return an instance.
082: * @throws JicarillaInvocationTargetException if the factory implementation
083: * has a problem invoking some external resource and is thus
084: * unable to return an instance.
085: * @throws JicarillaInstantiationException if the factory implementation
086: * has a problem creating the instance to return.
087: * @throws JicarillaClassNotFoundException if the factory implementation
088: * tries to load a class to create an instance of, but the class
089: * cannot be loaded.
090: * @throws InitializationException if a miscellaneous problem occurs
091: * trying to create the instance to return.
092: * @throws JicarillaException if a miscellaneous exception occurs (an
093: * internal factory error or an assertion failure, for example).
094: */
095: Object newInstance() throws JicarillaIllegalAccessException,
096: JicarillaInvocationTargetException,
097: JicarillaInstantiationException,
098: JicarillaClassNotFoundException, InitializationException,
099: JicarillaException;
100:
101: /**
102: * Return the instance to this factory. Any pending cleanup on the object
103: * will be done and then it will be dereferenced (so it can be
104: * garbage-collected). The factory is guaranteed to not keep a reference
105: * to the instance around any longer than neccessary to dispose of it.
106: * You should only return instances to this adapter if you have received
107: * them through {@link #newInstance()}.
108: *
109: * @param instance the instance to release.
110: *
111: * @throws Exception if any kind of problem occurs releasing the instance.
112: * It is often considered safe to recover from this exception and
113: * continue normal application flow, but these exceptions should
114: * never be discarded lightly.
115: */
116: void releaseInstance(Object instance) throws Exception;
117: }
|