001: /*
002: * Copyright 1999-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.commons.pool;
018:
019: /**
020: * A "keyed" pooling interface.
021: * <p>
022: * A keyed pool pools instances of multiple types. Each
023: * type may be accessed using an arbitrary key.
024: * <p>
025: * Example of use:
026: * <table border="1" cellspacing="0" cellpadding="3" align="center" bgcolor="#FFFFFF"><tr><td><pre>
027: * Object obj = <font color="#0000CC">null</font>;
028: * Object key = <font color="#CC0000">"Key"</font>;
029: *
030: * <font color="#0000CC">try</font> {
031: * obj = pool.borrowObject(key);
032: * <font color="#00CC00">//...use the object...</font>
033: * } <font color="#0000CC">catch</font>(Exception e) {
034: * <font color="#00CC00">//...handle any exceptions...</font>
035: * } <font color="#0000CC">finally</font> {
036: * <font color="#00CC00">// make sure the object is returned to the pool</font>
037: * <font color="#0000CC">if</font>(<font color="#0000CC">null</font> != obj) {
038: * pool.returnObject(key,obj);
039: * }
040: * }</pre></td></tr></table>
041: *
042: * <p>
043: * {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
044: * one instance per key value, or may choose to maintain a pool of instances
045: * for each key (essentially creating a {@link java.util.Map Map} of
046: * {@link ObjectPool pools}).
047: * </p>
048: *
049: * @see KeyedPoolableObjectFactory
050: * @see KeyedObjectPoolFactory
051: * @see ObjectPool
052: *
053: * @author Rodney Waldhoff
054: * @version $Revision: 155430 $ $Date: 2005-02-26 08:13:28 -0500 (Sat, 26 Feb 2005) $
055: */
056: public interface KeyedObjectPool {
057: /**
058: * Obtain an instance from my pool
059: * for the specified <i>key</i>.
060: * By contract, clients MUST return
061: * the borrowed object using
062: * {@link #returnObject(java.lang.Object,java.lang.Object) <tt>returnObject</tt>},
063: * or a related method as defined in an implementation
064: * or sub-interface,
065: * using a <i>key</i> that is equivalent to the one used to
066: * borrow the instance in the first place.
067: *
068: * @param key the key used to obtain the object
069: * @return an instance from my pool.
070: */
071: Object borrowObject(Object key) throws Exception;
072:
073: /**
074: * Return an instance to my pool.
075: * By contract, <i>obj</i> MUST have been obtained
076: * using {@link #borrowObject(java.lang.Object) <tt>borrowObject</tt>}
077: * or a related method as defined in an implementation
078: * or sub-interface
079: * using a <i>key</i> that is equivalent to the one used to
080: * borrow the <tt>Object</tt> in the first place.
081: *
082: * @param key the key used to obtain the object
083: * @param obj a {@link #borrowObject(java.lang.Object) borrowed} instance to be returned.
084: */
085: void returnObject(Object key, Object obj) throws Exception;
086:
087: /**
088: * Invalidates an object from the pool
089: * By contract, <i>obj</i> MUST have been obtained
090: * using {@link #borrowObject borrowObject}
091: * or a related method as defined in an implementation
092: * or sub-interface
093: * using a <i>key</i> that is equivalent to the one used to
094: * borrow the <tt>Object</tt> in the first place.
095: * <p>
096: * This method should be used when an object that has been borrowed
097: * is determined (due to an exception or other problem) to be invalid.
098: * If the connection should be validated before or after borrowing,
099: * then the {@link PoolableObjectFactory#validateObject} method should be
100: * used instead.
101: *
102: * @param obj a {@link #borrowObject borrowed} instance to be returned.
103: */
104: void invalidateObject(Object key, Object obj) throws Exception;
105:
106: /**
107: * Create an object using my {@link #setFactory factory} or other
108: * implementation dependent mechanism, and place it into the pool.
109: * addObject() is useful for "pre-loading" a pool with idle objects.
110: * (Optional operation).
111: */
112: void addObject(Object key) throws Exception;
113:
114: /**
115: * Returns the number of instances
116: * corresponding to the given <i>key</i>
117: * currently idle in my pool (optional operation).
118: * Throws {@link UnsupportedOperationException}
119: * if this information is not available.
120: *
121: * @param key the key
122: * @return the number of instances corresponding to the given <i>key</i> currently idle in my pool
123: * @throws UnsupportedOperationException when this implementation doesn't support the operation
124: */
125: int getNumIdle(Object key) throws UnsupportedOperationException;
126:
127: /**
128: * Returns the number of instances
129: * currently borrowed from but not yet returned
130: * to my pool corresponding to the
131: * given <i>key</i> (optional operation).
132: * Throws {@link UnsupportedOperationException}
133: * if this information is not available.
134: *
135: * @param key the key
136: * @return the number of instances corresponding to the given <i>key</i> currently borrowed in my pool
137: * @throws UnsupportedOperationException when this implementation doesn't support the operation
138: */
139: int getNumActive(Object key) throws UnsupportedOperationException;
140:
141: /**
142: * Returns the total number of instances
143: * currently idle in my pool (optional operation).
144: * Throws {@link UnsupportedOperationException}
145: * if this information is not available.
146: *
147: * @return the total number of instances currently idle in my pool
148: * @throws UnsupportedOperationException when this implementation doesn't support the operation
149: */
150: int getNumIdle() throws UnsupportedOperationException;
151:
152: /**
153: * Returns the total number of instances
154: * current borrowed from my pool but not
155: * yet returned (optional operation).
156: * Throws {@link UnsupportedOperationException}
157: * if this information is not available.
158: *
159: * @return the total number of instances currently borrowed from my pool
160: * @throws UnsupportedOperationException when this implementation doesn't support the operation
161: */
162: int getNumActive() throws UnsupportedOperationException;
163:
164: /**
165: * Clears my pool, removing all pooled instances
166: * (optional operation).
167: * Throws {@link UnsupportedOperationException}
168: * if the pool cannot be cleared.
169: * @throws UnsupportedOperationException when this implementation doesn't support the operation
170: */
171: void clear() throws Exception, UnsupportedOperationException;
172:
173: /**
174: * Clears the specified pool, removing all
175: * pooled instances corresponding to
176: * the given <i>key</i> (optional operation).
177: * Throws {@link UnsupportedOperationException}
178: * if the pool cannot be cleared.
179: * @param key the key to clear
180: * @throws UnsupportedOperationException when this implementation doesn't support the operation
181: */
182: void clear(Object key) throws Exception,
183: UnsupportedOperationException;
184:
185: /**
186: * Close this pool, and free any resources associated with it.
187: */
188: void close() throws Exception;
189:
190: /**
191: * Sets the {@link KeyedPoolableObjectFactory factory} I use
192: * to create new instances (optional operation).
193: * @param factory the {@link KeyedPoolableObjectFactory} I use to create new instances.
194: * @throws IllegalStateException when the factory cannot be set at this time
195: * @throws UnsupportedOperationException when this implementation doesn't support the operation
196: */
197: void setFactory(KeyedPoolableObjectFactory factory)
198: throws IllegalStateException, UnsupportedOperationException;
199: }
|