Source code

; Sun, 31 May 2015 22:24:08 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r953350 [26/37] - in /websites/production/commons/content/proper/commons-pool: api-2.4.1/ api-2.4.1/org/ api-2.4.1/org/apache/ api-2.4.1/org/apache/commons/ api-2.4.1/org/apache/commons/pool2/ api-2.4.1/org/apache/commons/pool2/class-use/ a... Date: Sun, 31 May 2015 22:24:05 -0000 To: notifications@commons.apache.org From: psteitz@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20150531222408.5EB72AC0B8F@hades.apache.org> Added: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/BaseObjectPool.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/BaseObjectPool.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/BaseObjectPool.html Sun May 31 22:24:03 2015 @@ -0,0 +1,193 @@ + + + +Source code + + + +

001/*
+002 * Licensed to the Apache Software Foundation (ASF) under one or more
+003 * contributor license agreements.  See the NOTICE file distributed with
+004 * this work for additional information regarding copyright ownership.
+005 * The ASF licenses this file to You under the Apache License, Version 2.0
+006 * (the "License"); you may not use this file except in compliance with
+007 * the License.  You may obtain a copy of the License at
+008 *
+009 *      http://www.apache.org/licenses/LICENSE-2.0
+010 *
+011 * Unless required by applicable law or agreed to in writing, software
+012 * distributed under the License is distributed on an "AS IS" BASIS,
+013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+014 * See the License for the specific language governing permissions and
+015 * limitations under the License.
+016 */
+017package org.apache.commons.pool2;
+018
+019/**
+020 * A simple base implementation of {@link ObjectPool}.
+021 * Optional operations are implemented to either do nothing, return a value
+022 * indicating it is unsupported or throw {@link UnsupportedOperationException}.
+023 * <p>
+024 * This class is intended to be thread-safe.
+025 *
+026 * @param <T> Type of element pooled in this pool.
+027 *
+028 * @version $Revision: 1566605 $
+029 *
+030 * @since 2.0
+031 */
+032public abstract class BaseObjectPool<T> implements ObjectPool<T> {
+033
+034    @Override
+035    public abstract T borrowObject() throws Exception;
+036
+037    @Override
+038    public abstract void returnObject(T obj) throws Exception;
+039
+040    @Override
+041    public abstract void invalidateObject(T obj) throws Exception;
+042
+043    /**
+044     * Not supported in this base implementation.
+045     *
+046     * @return a negative value.
+047     */
+048    @Override
+049    public int getNumIdle() {
+050        return -1;
+051    }
+052
+053    /**
+054     * Not supported in this base implementation.
+055     *
+056     * @return a negative value.
+057     */
+058    @Override
+059    public int getNumActive() {
+060        return -1;
+061    }
+062
+063    /**
+064     * Not supported in this base implementation.
+065     *
+066     * @throws UnsupportedOperationException if the pool does not implement this
+067     *          method
+068     */
+069    @Override
+070    public void clear() throws Exception, UnsupportedOperationException {
+071        throw new UnsupportedOperationException();
+072    }
+073
+074    /**
+075     * Not supported in this base implementation. Subclasses should override
+076     * this behavior.
+077     *
+078     * @throws UnsupportedOperationException if the pool does not implement this
+079     *          method
+080     */
+081    @Override
+082    public void addObject() throws Exception, UnsupportedOperationException {
+083        throw new UnsupportedOperationException();
+084    }
+085
+086    /**
+087     * {@inheritDoc}
+088     * <p>
+089     * This affects the behavior of <code>isClosed</code> and
+090     * <code>assertOpen</code>.
+091     */
+092    @Override
+093    public void close() {
+094        closed = true;
+095    }
+096
+097    /**
+098     * Has this pool instance been closed.
+099     *
+100     * @return <code>true</code> when this pool has been closed.
+101     */
+102    public final boolean isClosed() {
+103        return closed;
+104    }
+105
+106    /**
+107     * Throws an <code>IllegalStateException</code> when this pool has been
+108     * closed.
+109     *
+110     * @throws IllegalStateException when this pool has been closed.
+111     *
+112     * @see #isClosed()
+113     */
+114    protected final void assertOpen() throws IllegalStateException {
+115        if (isClosed()) {
+116            throw new IllegalStateException("Pool not open");
+117        }
+118    }
+119
+120    private volatile boolean closed = false;
+121}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + Propchange: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/BaseObjectPool.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/BasePooledObjectFactory.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/BasePooledObjectFactory.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/BasePooledObjectFactory.html Sun May 31 22:24:03 2015 @@ -0,0 +1,175 @@ + + + +Source code + + + +

001/*
+002 * Licensed to the Apache Software Foundation (ASF) under one or more
+003 * contributor license agreements.  See the NOTICE file distributed with
+004 * this work for additional information regarding copyright ownership.
+005 * The ASF licenses this file to You under the Apache License, Version 2.0
+006 * (the "License"); you may not use this file except in compliance with
+007 * the License.  You may obtain a copy of the License at
+008 *
+009 *      http://www.apache.org/licenses/LICENSE-2.0
+010 *
+011 * Unless required by applicable law or agreed to in writing, software
+012 * distributed under the License is distributed on an "AS IS" BASIS,
+013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+014 * See the License for the specific language governing permissions and
+015 * limitations under the License.
+016 */
+017package org.apache.commons.pool2;
+018
+019/**
+020 * A base implementation of <code>PoolableObjectFactory</code>.
+021 * <p>
+022 * All operations defined here are essentially no-op's.
+023 * <p>
+024 * This class is immutable, and therefore thread-safe
+025 *
+026 * @param <T> Type of element managed in this factory.
+027 *
+028 * @see PooledObjectFactory
+029 * @see BaseKeyedPooledObjectFactory
+030 *
+031 * @version $Revision: 1333925 $
+032 *
+033 * @since 2.0
+034 */
+035public abstract class BasePooledObjectFactory<T> implements PooledObjectFactory<T> {
+036    /**
+037     * Creates an object instance, to be wrapped in a {@link PooledObject}.
+038     * <p>This method <strong>must</strong> support concurrent, multi-threaded
+039     * activation.</p>
+040     *
+041     * @return an instance to be served by the pool
+042     *
+043     * @throws Exception if there is a problem creating a new instance,
+044     *    this will be propagated to the code requesting an object.
+045     */
+046    public abstract T create() throws Exception;
+047
+048    /**
+049     * Wrap the provided instance with an implementation of
+050     * {@link PooledObject}.
+051     *
+052     * @param obj the instance to wrap
+053     *
+054     * @return The provided instance, wrapped by a {@link PooledObject}
+055     */
+056    public abstract PooledObject<T> wrap(T obj);
+057
+058    @Override
+059    public PooledObject<T> makeObject() throws Exception {
+060        return wrap(create());
+061    }
+062
+063    /**
+064     *  No-op.
+065     *
+066     *  @param p ignored
+067     */
+068    @Override
+069    public void destroyObject(PooledObject<T> p)
+070        throws Exception  {
+071    }
+072
+073    /**
+074     * This implementation always returns {@code true}.
+075     *
+076     * @param p ignored
+077     *
+078     * @return {@code true}
+079     */
+080    @Override
+081    public boolean validateObject(PooledObject<T> p) {
+082        return true;
+083    }
+084
+085    /**
+086     *  No-op.
+087     *
+088     *  @param p ignored
+089     */
+090    @Override
+091    public void activateObject(PooledObject<T> p) throws Exception {
+092    }
+093
+094    /**
+095     *  No-op.
+096     *
+097     * @param p ignored
+098     */
+099    @Override
+100    public void passivateObject(PooledObject<T> p)
+101        throws Exception {
+102    }
+103}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + Propchange: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/BasePooledObjectFactory.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/KeyedObjectPool.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/KeyedObjectPool.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/KeyedObjectPool.html Sun May 31 22:24:03 2015 @@ -0,0 +1,302 @@ + + + +Source code + + + +

001/*
+002 * Licensed to the Apache Software Foundation (ASF) under one or more
+003 * contributor license agreements.  See the NOTICE file distributed with
+004 * this work for additional information regarding copyright ownership.
+005 * The ASF licenses this file to You under the Apache License, Version 2.0
+006 * (the "License"); you may not use this file except in compliance with
+007 * the License.  You may obtain a copy of the License at
+008 *
+009 *      http://www.apache.org/licenses/LICENSE-2.0
+010 *
+011 * Unless required by applicable law or agreed to in writing, software
+012 * distributed under the License is distributed on an "AS IS" BASIS,
+013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+014 * See the License for the specific language governing permissions and
+015 * limitations under the License.
+016 */
+017package org.apache.commons.pool2;
+018
+019import java.util.NoSuchElementException;
+020
+021/**
+022 * A "keyed" pooling interface.
+023 * <p>
+024 * A keyed pool maintains a pool of instances for each key value.
+025 * <p>
+026 * Example of use:
+027 * <pre style="border:solid thin; padding: 1ex;"
+028 * > Object obj = <code style="color:#00C">null</code>;
+029 * Object key = <code style="color:#C00">"Key"</code>;
+030 *
+031 * <code style="color:#00C">try</code> {
+032 *     obj = pool.borrowObject(key);
+033 *     <code style="color:#0C0">//...use the object...</code>
+034 * } <code style="color:#00C">catch</code>(Exception e) {
+035 *     <code style="color:#0C0">// invalidate the object</code>
+036 *     pool.invalidateObject(key, obj);
+037 *     <code style="color:#0C0">// do not return the object to the pool twice</code>
+038 *     obj = <code style="color:#00C">null</code>;
+039 * } <code style="color:#00C">finally</code> {
+040 *     <code style="color:#0C0">// make sure the object is returned to the pool</code>
+041 *     <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) {
+042 *         pool.returnObject(key, obj);
+043 *     }
+044 * }</pre>
+045 * <p>
+046 * {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
+047 * one instance per key value, or may choose to maintain a pool of instances
+048 * for each key (essentially creating a {@link java.util.Map Map} of
+049 * {@link ObjectPool pools}).
+050 * <p>
+051 * See {@link org.apache.commons.pool2.impl.GenericKeyedObjectPool
+052 * GenericKeyedObjectPool} for an implementation.
+053 *
+054 * @param <K> The type of keys maintained by this pool.
+055 * @param <V> Type of element pooled in this pool.
+056 *
+057 * @see KeyedPooledObjectFactory
+058 * @see ObjectPool
+059 * @see org.apache.commons.pool2.impl.GenericKeyedObjectPool GenericKeyedObjectPool
+060 *
+061 * @version $Revision: 1566605 $
+062 *
+063 * @since 2.0
+064 */
+065public interface KeyedObjectPool<K,V> {
+066    /**
+067     * Obtains an instance from this pool for the specified <code>key</code>.
+068     * <p>
+069     * Instances returned from this method will have been either newly created
+070     * with {@link KeyedPooledObjectFactory#makeObject makeObject} or will be
+071     * a previously idle object and have been activated with
+072     * {@link KeyedPooledObjectFactory#activateObject activateObject} and then
+073     * (optionally) validated with
+074     * {@link KeyedPooledObjectFactory#validateObject validateObject}.
+075     * <p>
+076     * By contract, clients <strong>must</strong> return the borrowed object
+077     * using {@link #returnObject returnObject},
+078     * {@link #invalidateObject invalidateObject}, or a related method as
+079     * defined in an implementation or sub-interface, using a <code>key</code>
+080     * that is {@link Object#equals equivalent} to the one used to borrow the
+081     * instance in the first place.
+082     * <p>
+083     * The behaviour of this method when the pool has been exhausted is not
+084     * strictly specified (although it may be specified by implementations).
+085     *
+086     * @param key the key used to obtain the object
+087     *
+088     * @return an instance from this pool.
+089     *
+090     * @throws IllegalStateException
+091     *              after {@link #close close} has been called on this pool
+092     * @throws Exception
+093     *              when {@link KeyedPooledObjectFactory#makeObject
+094     *              makeObject} throws an exception
+095     * @throws NoSuchElementException
+096     *              when the pool is exhausted and cannot or will not return
+097     *              another instance
+098     */
+099    V borrowObject(K key) throws Exception, NoSuchElementException, IllegalStateException;
+100
+101    /**
+102     * Return an instance to the pool. By contract, <code>obj</code>
+103     * <strong>must</strong> have been obtained using
+104     * {@link #borrowObject borrowObject} or a related method as defined in an
+105     * implementation or sub-interface using a <code>key</code> that is
+106     * equivalent to the one used to borrow the instance in the first place.
+107     *
+108     * @param key the key used to obtain the object
+109     * @param obj a {@link #borrowObject borrowed} instance to be returned.
+110     *
+111     * @throws IllegalStateException
+112     *              if an attempt is made to return an object to the pool that
+113     *              is in any state other than allocated (i.e. borrowed).
+114     *              Attempting to return an object more than once or attempting
+115     *              to return an object that was never borrowed from the pool
+116     *              will trigger this exception.
+117     *
+118     * @throws Exception if an instance cannot be returned to the pool
+119     */
+120    void returnObject(K key, V obj) throws Exception;
+121
+122    /**
+123     * Invalidates an object from the pool.
+124     * <p>
+125     * By contract, <code>obj</code> <strong>must</strong> have been obtained
+126     * using {@link #borrowObject borrowObject} or a related method as defined
+127     * in an implementation or sub-interface using a <code>key</code> that is
+128     * equivalent to the one used to borrow the <code>Object</code> in the first
+129     * place.
+130     * <p>
+131     * This method should be used when an object that has been borrowed is
+132     * determined (due to an exception or other problem) to be invalid.
+133     *
+134     * @param key the key used to obtain the object
+135     * @param obj a {@link #borrowObject borrowed} instance to be returned.
+136     *
+137     * @throws Exception if the instance cannot be invalidated
+138     */
+139    void invalidateObject(K key, V obj) throws Exception;
+140
+141    /**
+142     * Create an object using the {@link KeyedPooledObjectFactory factory} or
+143     * other implementation dependent mechanism, passivate it, and then place it
+144     * in the idle object pool. <code>addObject</code> is useful for
+145     * "pre-loading" a pool with idle objects (Optional operation).
+146     *
+147     * @param key the key a new instance should be added to
+148     *
+149     * @throws Exception
+150     *              when {@link KeyedPooledObjectFactory#makeObject} fails.
+151     * @throws IllegalStateException
+152     *              after {@link #close} has been called on this pool.
+153     * @throws UnsupportedOperationException
+154     *              when this pool cannot add new idle objects.
+155     */
+156    void addObject(K key) throws Exception, IllegalStateException,
+157            UnsupportedOperationException;
+158
+159    /**
+160     * Returns the number of instances corresponding to the given
+161     * <code>key</code> currently idle in this pool. Returns a negative value if
+162     * this information is not available.
+163     *
+164     * @param key the key to query
+165     * @return the number of instances corresponding to the given
+166     * <code>key</code> currently idle in this pool.
+167     */
+168    int getNumIdle(K key);
+169
+170    /**
+171     * Returns the number of instances currently borrowed from but not yet
+172     * returned to the pool corresponding to the given <code>key</code>.
+173     * Returns a negative value if this information is not available.
+174     *
+175     * @param key the key to query
+176     * @return the number of instances currently borrowed from but not yet
+177     * returned to the pool corresponding to the given <code>key</code>.
+178=     */
+179    int getNumActive(K key);
+180
+181    /**
+182     * Returns the total number of instances currently idle in this pool.
+183     * Returns a negative value if this information is not available.
+184     * @return the total number of instances currently idle in this pool.
+185 =    */
+186    int getNumIdle();
+187
+188    /**
+189     * Returns the total number of instances current borrowed from this pool but
+190     * not yet returned. Returns a negative value if this information is not
+191     * available.
+192     * @return the total number of instances current borrowed from this pool but
+193     * not yet returned.
+194     */
+195    int getNumActive();
+196
+197    /**
+198     * Clears the pool, removing all pooled instances (optional operation).
+199     *
+200     * @throws UnsupportedOperationException when this implementation doesn't
+201     *                                       support the operation
+202     *
+203     * @throws Exception if the pool cannot be cleared
+204     */
+205    void clear() throws Exception, UnsupportedOperationException;
+206
+207    /**
+208     * Clears the specified pool, removing all pooled instances corresponding to
+209     * the given <code>key</code> (optional operation).
+210     *
+211     * @param key the key to clear
+212     *
+213     * @throws UnsupportedOperationException when this implementation doesn't
+214     *                                       support the operation
+215     *
+216     * @throws Exception if the key cannot be cleared
+217     */
+218    void clear(K key) throws Exception, UnsupportedOperationException;
+219
+220    /**
+221     * Close this pool, and free any resources associated with it.
+222     * <p>
+223     * Calling {@link #addObject addObject} or
+224     * {@link #borrowObject borrowObject} after invoking this method on a pool
+225     * will cause them to throw an {@link IllegalStateException}.
+226     * <p>
+227     * Implementations should silently fail if not all resources can be freed.
+228     */
+229    void close();
+230}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + Propchange: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/KeyedObjectPool.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/KeyedPooledObjectFactory.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/KeyedPooledObjectFactory.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/KeyedPooledObjectFactory.html Sun May 31 22:24:03 2015 @@ -0,0 +1,222 @@ + + + +Source code + + + +

001/*
+002 * Licensed to the Apache Software Foundation (ASF) under one or more
+003 * contributor license agreements.  See the NOTICE file distributed with
+004 * this work for additional information regarding copyright ownership.
+005 * The ASF licenses this file to You under the Apache License, Version 2.0
+006 * (the "License"); you may not use this file except in compliance with
+007 * the License.  You may obtain a copy of the License at
+008 *
+009 *      http://www.apache.org/licenses/LICENSE-2.0
+010 *
+011 * Unless required by applicable law or agreed to in writing, software
+012 * distributed under the License is distributed on an "AS IS" BASIS,
+013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+014 * See the License for the specific language governing permissions and
+015 * limitations under the License.
+016 */
+017package org.apache.commons.pool2;
+018
+019/**
+020 * An interface defining life-cycle methods for
+021 * instances to be served by a {@link KeyedObjectPool}.
+022 * <p>
+023 * By contract, when an {@link KeyedObjectPool}
+024 * delegates to a {@link KeyedPooledObjectFactory},
+025 * <ol>
+026 *  <li>
+027 *   {@link #makeObject} is called whenever a new instance is needed.
+028 *  </li>
+029 *  <li>
+030 *   {@link #activateObject} is invoked on every instance that has been
+031 *   {@link #passivateObject passivated} before it is
+032 *   {@link KeyedObjectPool#borrowObject borrowed} from the pool.
+033 *  </li>
+034 *  <li>
+035 *   {@link #validateObject} may be invoked on {@link #activateObject activated}
+036 *   instances to make sure they can be
+037 *   {@link KeyedObjectPool#borrowObject borrowed} from the pool.
+038 *   <code>validateObject</code> may also be used to test an
+039 *   instance being {@link KeyedObjectPool#returnObject returned} to the pool
+040 *   before it is {@link #passivateObject passivated}. It will only be invoked
+041 *   on an activated instance.
+042 *  </li>
+043 *  <li>
+044 *   {@link #passivateObject passivateObject}
+045 *   is invoked on every instance when it is returned to the pool.
+046 *  </li>
+047 *  <li>
+048 *   {@link #destroyObject destroyObject}
+049 *   is invoked on every instance when it is being "dropped" from the
+050 *   pool (whether due to the response from <code>validateObject</code>,
+051 *   or for reasons specific to the pool implementation.) There is no
+052 *   guarantee that the instance being destroyed will
+053 *   be considered active, passive or in a generally consistent state.
+054 *  </li>
+055 * </ol>
+056 * {@link KeyedPooledObjectFactory} must be thread-safe. The only promise
+057 * an {@link KeyedObjectPool} makes is that the same instance of an object will
+058 * not be passed to more than one method of a
+059 * <code>KeyedPoolableObjectFactory</code> at a time.
+060 * <p>
+061 * While clients of a {@link KeyedObjectPool} borrow and return instances of
+062 * the underlying value type V, the factory methods act on instances of
+063 * {@link PooledObject PooledObject&lt;V&gt;}.  These are the object wrappers that
+064 * pools use to track and maintain state informations about the objects that
+065 * they manage.
+066 *
+067 * @see KeyedObjectPool
+068 * @see BaseKeyedPooledObjectFactory
+069 *
+070 * @param <K> The type of keys managed by this factory.
+071 * @param <V> Type of element managed by this factory.
+072 *
+073 * @version $Revision: 1333925 $
+074 *
+075 * @since 2.0
+076 */
+077public interface KeyedPooledObjectFactory<K,V> {
+078    /**
+079     * Create an instance that can be served by the pool and
+080     * wrap it in a {@link PooledObject} to be managed by the pool.
+081     *
+082     * @param key the key used when constructing the object
+083     *
+084     * @return a {@code PooledObject} wrapping an instance that can
+085     * be served by the pool.
+086     *
+087     * @throws Exception if there is a problem creating a new instance,
+088     *    this will be propagated to the code requesting an object.
+089     */
+090    PooledObject<V> makeObject(K key) throws Exception;
+091
+092    /**
+093     * Destroy an instance no longer needed by the pool.
+094     * <p>
+095     * It is important for implementations of this method to be aware that there
+096     * is no guarantee about what state <code>obj</code> will be in and the
+097     * implementation should be prepared to handle unexpected errors.
+098     * <p>
+099     * Also, an implementation must take in to consideration that instances lost
+100     * to the garbage collector may never be destroyed.
+101     *
+102     * @param key the key used when selecting the instance
+103     * @param p a {@code PooledObject} wrapping the instance to be destroyed
+104     *
+105     * @throws Exception should be avoided as it may be swallowed by
+106     *    the pool implementation.
+107     *
+108     * @see #validateObject
+109     * @see KeyedObjectPool#invalidateObject
+110     */
+111    void destroyObject(K key, PooledObject<V> p) throws Exception;
+112
+113    /**
+114     * Ensures that the instance is safe to be returned by the pool.
+115     *
+116     * @param key the key used when selecting the object
+117     * @param p a {@code PooledObject} wrapping the instance to be validated
+118     *
+119     * @return <code>false</code> if <code>obj</code> is not valid and should
+120     *         be dropped from the pool, <code>true</code> otherwise.
+121     */
+122    boolean validateObject(K key, PooledObject<V> p);
+123
+124    /**
+125     * Reinitialize an instance to be returned by the pool.
+126     *
+127     * @param key the key used when selecting the object
+128     * @param p a {@code PooledObject} wrapping the instance to be activated
+129     *
+130     * @throws Exception if there is a problem activating <code>obj</code>,
+131     *    this exception may be swallowed by the pool.
+132     *
+133     * @see #destroyObject
+134     */
+135    void activateObject(K key, PooledObject<V> p) throws Exception;
+136
+137    /**
+138     * Uninitialize an instance to be returned to the idle object pool.
+139     *
+140     * @param key the key used when selecting the object
+141     * @param p a {@code PooledObject} wrapping the instance to be passivated
+142     *
+143     * @throws Exception if there is a problem passivating <code>obj</code>,
+144     *    this exception may be swallowed by the pool.
+145     *
+146     * @see #destroyObject
+147     */
+148    void passivateObject(K key, PooledObject<V> p) throws Exception;
+149}
+150
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + Propchange: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/KeyedPooledObjectFactory.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/ObjectPool.html ============================================================================== --- websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/ObjectPool.html (added) +++ websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/ObjectPool.html Sun May 31 22:24:03 2015 @@ -0,0 +1,250 @@ + + + +Source code + + + +

001/*
+002 * Licensed to the Apache Software Foundation (ASF) under one or more
+003 * contributor license agreements.  See the NOTICE file distributed with
+004 * this work for additional information regarding copyright ownership.
+005 * The ASF licenses this file to You under the Apache License, Version 2.0
+006 * (the "License"); you may not use this file except in compliance with
+007 * the License.  You may obtain a copy of the License at
+008 *
+009 *      http://www.apache.org/licenses/LICENSE-2.0
+010 *
+011 * Unless required by applicable law or agreed to in writing, software
+012 * distributed under the License is distributed on an "AS IS" BASIS,
+013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+014 * See the License for the specific language governing permissions and
+015 * limitations under the License.
+016 */
+017package org.apache.commons.pool2;
+018
+019import java.util.NoSuchElementException;
+020
+021/**
+022 * A pooling simple interface.
+023 * <p>
+024 * Example of use:
+025 * <pre style="border:solid thin; padding: 1ex;"
+026 * > Object obj = <code style="color:#00C">null</code>;
+027 *
+028 * <code style="color:#00C">try</code> {
+029 *     obj = pool.borrowObject();
+030 *     <code style="color:#00C">try</code> {
+031 *         <code style="color:#0C0">//...use the object...</code>
+032 *     } <code style="color:#00C">catch</code>(Exception e) {
+033 *         <code style="color:#0C0">// invalidate the object</code>
+034 *         pool.invalidateObject(obj);
+035 *         <code style="color:#0C0">// do not return the object to the pool twice</code>
+036 *         obj = <code style="color:#00C">null</code>;
+037 *     } <code style="color:#00C">finally</code> {
+038 *         <code style="color:#0C0">// make sure the object is returned to the pool</code>
+039 *         <code style="color:#00C">if</code>(<code style="color:#00C">null</code> != obj) {
+040 *             pool.returnObject(obj);
+041 *        }
+042 *     }
+043 * } <code style="color:#00C">catch</code>(Exception e) {
+044 *       <code style="color:#0C0">// failed to borrow an object</code>
+045 * }</pre>
+046 * <p>
+047 * See {@link BaseObjectPool} for a simple base implementation.
+048 *
+049 * @param <T> Type of element pooled in this pool.
+050 *
+051 * @see PooledObjectFactory
+052 * @see KeyedObjectPool
+053 * @see BaseObjectPool
+054 *
+055 * @version $Revision: 1566605 $
+056 *
+057 * @since 2.0
+058 */
+059public interface ObjectPool<T> {
+060    /**
+061     * Obtains an instance from this pool.
+062     * <p>
+063     * Instances returned from this method will have been either newly created
+064     * with {@link PooledObjectFactory#makeObject} or will be a previously
+065     * idle object and have been activated with
+066     * {@link PooledObjectFactory#activateObject} and then validated with
+067     * {@link PooledObjectFactory#validateObject}.
+068     * <p>
+069     * By contract, clients <strong>must</strong> return the borrowed instance
+070     * using {@link #returnObject}, {@link #invalidateObject}, or a related
+071     * method as defined in an implementation or sub-interface.
+072     * <p>
+073     * The behaviour of this method when the pool has been exhausted
+074     * is not strictly specified (although it may be specified by
+075     * implementations).
+076     *
+077     * @return an instance from this pool.
+078     *
+079     * @throws IllegalStateException
+080     *              after {@link #close close} has been called on this pool.
+081     * @throws Exception
+082     *              when {@link PooledObjectFactory#makeObject} throws an
+083     *              exception.
+084     * @throws NoSuchElementException
+085     *              when the pool is exhausted and cannot or will not return
+086     *              another instance.
+087     */
+088    T borrowObject() throws Exception, NoSuchElementException,
+089            IllegalStateException;
+090
+091    /**
+092     * Return an instance to the pool. By contract, <code>obj</code>
+093     * <strong>must</strong> have been obtained using {@link #borrowObject()} or
+094     * a related method as defined in an implementation or sub-interface.
+095     *
+096     * @param obj a {@link #borrowObject borrowed} instance to be returned.
+097     *
+098     * @throws IllegalStateException
+099     *              if an attempt is made to return an object to the pool that
+100     *              is in any state other than allocated (i.e. borrowed).
+101     *              Attempting to return an object more than once or attempting
+102     *              to return an object that was never borrowed from the pool
+103     *              will trigger this exception.
+104     *
+105     * @throws Exception if an instance cannot be returned to the pool
+106     */
+107    void returnObject(T obj) throws Exception;
+108
+109    /**
+110     * Invalidates an object from the pool.
+111     * <p>
+112     * By contract, <code>obj</code> <strong>must</strong> have been obtained
+113     * using {@link #borrowObject} or a related method as defined in an
+114     * implementation or sub-interface.
+115     * <p>
+116     * This method should be used when an object that has been borrowed is
+117     * determined (due to an exception or other problem) to be invalid.
+118     *
+119     * @param obj a {@link #borrowObject borrowed} instance to be disposed.
+120     *
+121     * @throws Exception if the instance cannot be invalidated
+122     */
+123    void invalidateObject(T obj) throws Exception;
+124
+125    /**
+126     * Create an object using the {@link PooledObjectFactory factory} or other
+127     * implementation dependent mechanism, passivate it, and then place it in
+128     * the idle object pool. <code>addObject</code> is useful for "pre-loading"
+129     * a pool with idle objects. (Optional operation).
+130     *
+131     * @throws Exception
+132     *              when {@link PooledObjectFactory#makeObject} fails.
+133     * @throws IllegalStateException
+134     *              after {@link #close} has been called on this pool.
+135     * @throws UnsupportedOperationException
+136     *              when this pool cannot add new idle objects.
+137     */
+138    void addObject() throws Exception, IllegalStateException,
+139            UnsupportedOperationException;
+140
+141    /**
+142     * Return the number of instances currently idle in this pool. This may be
+143     * considered an approximation of the number of objects that can be
+144     * {@link #borrowObject borrowed} without creating any new instances.
+145     * Returns a negative value if this information is not available.
+146     * @return the number of instances currently idle in this pool.
+147     */
+148    int getNumIdle();
+149
+150    /**
+151     * Return the number of instances currently borrowed from this pool. Returns
+152     * a negative value if this information is not available.
+153     * @return the number of instances currently borrowed from this pool.
+154     */
+155    int getNumActive();
+156
+157    /**
+158     * Clears any objects sitting idle in the pool, releasing any associated
+159     * resources (optional operation). Idle objects cleared must be
+160     * {@link PooledObjectFactory#destroyObject(PooledObject)}.
+161     *
+162     * @throws UnsupportedOperationException
+163     *              if this implementation does not support the operation
+164     *
+165     * @throws Exception if the pool cannot be cleared
+166     */
+167    void clear() throws Exception, UnsupportedOperationException;
+168
+169    /**
+170     * Close this pool, and free any resources associated with it.
+171     * <p>
+172     * Calling {@link #addObject} or {@link #borrowObject} after invoking this
+173     * method on a pool will cause them to throw an {@link IllegalStateException}.
+174     * <p>
+175     * Implementations should silently fail if not all resources can be freed.
+176     */
+177    void close();
+178}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

+ + Propchange: websites/production/commons/content/proper/commons-pool/api-2.4.1/src-html/org/apache/commons/pool2/ObjectPool.html ------------------------------------------------------------------------------ svn:eol-style = native