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 pooling interface.
021: * <p>
022: * <code>ObjectPool</code> defines a trivially simple pooling interface. The only
023: * required methods are {@link #borrowObject borrowObject} and {@link #returnObject returnObject}.
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: *
029: * <font color="#0000CC">try</font> {
030: * obj = pool.borrowObject();
031: * <font color="#00CC00">//...use the object...</font>
032: * } <font color="#0000CC">catch</font>(Exception e) {
033: * <font color="#00CC00">//...handle any exceptions...</font>
034: * } <font color="#0000CC">finally</font> {
035: * <font color="#00CC00">// make sure the object is returned to the pool</font>
036: * <font color="#0000CC">if</font>(<font color="#0000CC">null</font> != obj) {
037: * pool.returnObject(obj);
038: * }
039: * }</pre></td></tr></table>
040: * See {@link org.apache.commons.pool.BaseObjectPool BaseObjectPool} for a simple base implementation.
041: *
042: * @author Rodney Waldhoff
043: * @version $Revision: 155430 $ $Date: 2005-02-26 08:13:28 -0500 (Sat, 26 Feb 2005) $
044: *
045: */
046: public interface ObjectPool {
047: /**
048: * Obtain an instance from my pool.
049: * By contract, clients MUST return
050: * the borrowed instance using
051: * {@link #returnObject(java.lang.Object) returnObject}
052: * or a related method as defined in an implementation
053: * or sub-interface.
054: * <p>
055: * The behaviour of this method when the pool has been exhausted
056: * is not specified (although it may be specified by implementations).
057: *
058: * @return an instance from my pool.
059: */
060: Object borrowObject() throws Exception;
061:
062: /**
063: * Return an instance to my pool.
064: * By contract, <i>obj</i> MUST have been obtained
065: * using {@link #borrowObject() borrowObject}
066: * or a related method as defined in an implementation
067: * or sub-interface.
068: *
069: * @param obj a {@link #borrowObject borrowed} instance to be returned.
070: */
071: void returnObject(Object obj) throws Exception;
072:
073: /**
074: * Invalidates an object from the pool
075: * By contract, <i>obj</i> MUST have been obtained
076: * using {@link #borrowObject() borrowObject}
077: * or a related method as defined in an implementation
078: * or sub-interface.
079: * <p>
080: * This method should be used when an object that has been borrowed
081: * is determined (due to an exception or other problem) to be invalid.
082: * If the connection should be validated before or after borrowing,
083: * then the {@link PoolableObjectFactory#validateObject} method should be
084: * used instead.
085: *
086: * @param obj a {@link #borrowObject borrowed} instance to be returned.
087: */
088: void invalidateObject(Object obj) throws Exception;
089:
090: /**
091: * Create an object using my {@link #setFactory factory} or other
092: * implementation dependent mechanism, and place it into the pool.
093: * addObject() is useful for "pre-loading" a pool with idle objects.
094: * (Optional operation).
095: */
096: void addObject() throws Exception;
097:
098: /**
099: * Return the number of instances
100: * currently idle in my pool (optional operation).
101: * This may be considered an approximation of the number
102: * of objects that can be {@link #borrowObject borrowed}
103: * without creating any new instances.
104: *
105: * @return the number of instances currently idle in my pool
106: * @throws UnsupportedOperationException if this implementation does not support the operation
107: */
108: int getNumIdle() throws UnsupportedOperationException;
109:
110: /**
111: * Return the number of instances
112: * currently borrowed from my pool
113: * (optional operation).
114: *
115: * @return the number of instances currently borrowed in my pool
116: * @throws UnsupportedOperationException if this implementation does not support the operation
117: */
118: int getNumActive() throws UnsupportedOperationException;
119:
120: /**
121: * Clears any objects sitting idle in the pool, releasing any
122: * associated resources (optional operation).
123: *
124: * @throws UnsupportedOperationException if this implementation does not support the operation
125: */
126: void clear() throws Exception, UnsupportedOperationException;
127:
128: /**
129: * Close this pool, and free any resources associated with it.
130: */
131: void close() throws Exception;
132:
133: /**
134: * Sets the {@link PoolableObjectFactory factory} I use
135: * to create new instances (optional operation).
136: * @param factory the {@link PoolableObjectFactory} I use to create new instances.
137: *
138: * @throws IllegalStateException when the factory cannot be set at this time
139: * @throws UnsupportedOperationException if this implementation does not support the operation
140: */
141: void setFactory(PoolableObjectFactory factory)
142: throws IllegalStateException, UnsupportedOperationException;
143: }
|