/*
 * $Header: /home/cvs/commons/pool-1.0.1/ja/src/org/apache/commons/pool/KeyedObjectPool.java,v 1.1.1.1 2004/02/13 10:02:01 hioki Exp $
 * $Revision: 1.1.1.1 $
 * $Date: 2004/02/13 10:02:01 $
 *
 * ====================================================================
 *
 * The Apache Software License, Version 1.1
 *
 * Copyright (c) 2001-2002 The Apache Software Foundation.  All rights
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution, if
 *    any, must include the following acknowlegement:
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowlegement may appear in the software itself,
 *    if and wherever such third-party acknowlegements normally appear.
 *
 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
 *    Foundation" must not be used to endorse or promote products derived
 *    from this software without prior written permission. For written
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache"
 *    nor may "Apache" appear in their names without prior written
 *    permission of the Apache Group.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 *
 */

package org.apache.commons.pool;

/**
 * キーに対応するプーリングを行うためのインターフェイスです。
 * {@primary A  "keyed" pooling interface.}
 * <p>
 * KeyedObjectPool は複数の型のインスタンスをプールします。
 * 各型のオブジェクトに任意のキーを使用してアクセスすることが可能です。
 * {@primary A keyed pool pools instances of multiple types. Each
 * type may be accessed using an arbitrary key.}
 * <p>
 * 以下に使用方法を示します:
 * {@primary Example of use:}
 * <table border="1" cellspacing="0" cellpadding="3" align="center" bgcolor="#FFFFFF"><tr><td>
 * &nbsp;Object obj = <font color="#0000CC">null</font>;<br/>
 * &nbsp;Object key = <font color="#CC0000">"Key"</font>;<br/>
 * <br/>
 * &nbsp;<font color="#0000CC">try</font>{<br/>
 * &nbsp;&nbsp;&nbsp;&nbsp;obj = pool.borrowObject(key);<br/>
 * &nbsp;&nbsp;&nbsp;&nbsp;<font color="#00CC00">//...オブジェクトを使用...</font>
 * {@primary &nbsp;&nbsp;&nbsp;&nbsp;//...use the object...}<br/>
 * &nbsp;}&nbsp;<font color="#0000CC">catch</font>(Exception e) {<br/>
 * &nbsp;&nbsp;&nbsp;&nbsp;<font color="#00CC00">//...例外をハンドル...</font>
 * {@primary &nbsp;&nbsp;&nbsp;&nbsp;//...handle any exceptions...} <br/>
 * &nbsp;}&nbsp;<font color="#0000CC">finally</font> {<br/>
 * &nbsp;&nbsp;&nbsp;&nbsp;<font color="#00CC00">// 確実にオブジェクトをプールに返す</font>&nbsp;
 * {@primary &nbsp;&nbsp;&nbsp;&nbsp;// make sure the object is returned to the pool}<br/>
 * &nbsp;&nbsp;&nbsp;&nbsp;<font color="#0000CC">if</font>(<font color="#0000CC">null</font> != obj) {<br/>
 * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pool.returnObject(key,obj);<br/>
 * &nbsp;&nbsp;&nbsp;&nbsp;}<br/>
 * &nbsp;}<br/><br/></td></tr></table>
 *
 * <p>
 * {@link KeyedObjectPool} の実装はキー毎に選択された1つのインスタンスを保持するか、
 * キー毎にプールするインスタンスの管理を行うことができます。
 * (実際には {@link ObjectPool pool} の {@link java.util.Map Map} を生成します)。
 * {@primary {@link KeyedObjectPool} implementations <i>may</i> choose to store at most
 * one instance per key value, or may choose to maintain a pool of instances
 * for each key (essentially creating a {@link java.util.Map Map} of
 * {@link ObjectPool pools}).}
 * </p>
 *
 * @author Rodney Waldhoff
 * @translator 日置 聡
 * @status firstdraft
 * @update 2003/08/19
 * @version $Revision: 1.1.1.1 $ $Date: 2004/02/13 10:02:01 $
 *
 * @see KeyedPoolableObjectFactory
 * @see KeyedObjectPoolFactory
 * @see ObjectPool
 */
public interface KeyedObjectPool {
    /**
     * プールから指定された <i>key</i> に対応するインスタンスを取り出します。
     * プールからインスタンスを取得したクライアントは必ず
     * {@link #returnObject(java.lang.Object,java.lang.Object) <tt>returnObject</tt>}
     * または実装クラスやサブインターフェイスのそれと関連するメソッドを使用して
     * インスタンスをプールに返さなくてはなりません。
     * また、 <i>key</i> には返すインスタンスを取得した際と同じ値を設定しなくてはなりません。
     * {@primary Obtain an instance from my pool
     * for the specified <i>key</i>.
     * By contract, clients MUST return
     * the borrowed object using
     * {@link #returnObject(java.lang.Object,java.lang.Object) <tt>returnObject</tt>},
     * or a related method as defined in an implementation
     * or sub-interface,
     * using a <i>key</i> that is equivalent to the one used to
     * borrow the instance in the first place.}
     *
     * @param key オブジェクトを取得する際に使用するキー
     * {@primary the key used to obtain the object}
     * @return プールから取得したインスタンス
     * {@primary an instance from my pool.}
     */
    Object borrowObject(Object key) throws Exception;

    /**
     * プールにインスタンスを返します。
     * プールに返される <i>obj</i> は必ず
     * {@link #borrowObject(java.lang.Object) <tt>borrowObject</tt>}
     * または実装クラスやサブインターフェイスのそれと関連するメソッドを使用して
     * 取得されたインスタンスでなくてはなりません。
     * また、 <i>key</i> には返すインスタンスを取得した際と同じ値を設定しなくてはなりません。
     * {@primary Return an instance to my pool.
     * By contract, <i>obj</i> MUST have been obtained
     * using {@link #borrowObject(java.lang.Object) <tt>borrowObject</tt>}
     * or a related method as defined in an implementation
     * or sub-interface,
     * using a <i>key</i> that is equivalent to the one used to
     * borrow the <tt>Object</tt> in the first place.}
     *
     * @param key オブジェクトを取得する際に使用するキー
     * {@primary the key used to obtain the object}
     * @param obj プールに返す {@link #borrowObject(java.lang.Object)} にて取得されたインスタンス
     * {@primary a {@link #borrowObject(java.lang.Object) borrowed} instance to be returned.}
     */
    void returnObject(Object key, Object obj) throws Exception;

    /**
     * 現在プール内にある使用されていない指定された
     * <i>key</i> に対応するインスタンスの数を返します(オプショナルな処理)。
     * この情報を取得する機能を持たない場合 {@link UnsupportedOperationException} が投げられます。
     * {@primary Returns the number of instances
     * corresponding to the given <i>key</i>
     * currently idle in my pool (optional operation).
     * Throws {@link UnsupportedOperationException}
     * if this information is not available.}
     *
     * @param key 対象となるキー
     * {@primary the key}
     * @return プール内にある使用されていない指定された <i>key</i> に対応するインスタンスの数
     * {@primary the number of instances corresponding to the given <i>key</i> currently idle in my pool}
     * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合
     * {@primary when this implementation doesn't support the operation}
     */
    int getNumIdle(Object key) throws UnsupportedOperationException;

    /**
     * このプールから取得され、まだ戻されていない指定された
     * <i>key</i> に対応するインスタンスの数を返します(オプショナルな処理)。
     * この情報を取得する機能を持たない場合 {@link UnsupportedOperationException} が投げられます。
     * {@primary Returns the number of instances
     * currently borrowed from but not yet returned
     * to my pool corresponding to the
     * given <i>key</i> (optional operation).
     * Throws {@link UnsupportedOperationException}
     * if this information is not available.}
     *
     * @param key 対象となるキー
     * {@primary the key}
     * @return 現在プールから貸し出されている指定された <i>key</i> に対応するインスタンスの数
     * {@primary the number of instances corresponding to the given <i>key</i> currently borrowed in my pool}
     * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合
     * {@primary when this implementation doesn't support the operation}
     */
    int getNumActive(Object key) throws UnsupportedOperationException;

    /**
     * 現在プール内にある使用されていないインスタンスの数を返します(オプショナルな処理)。
     * この情報を取得する機能を持たない場合 {@link UnsupportedOperationException} が投げられます。
     * {@primary Returns the total number of instances
     * currently idle in my pool (optional operation).
     * Throws {@link UnsupportedOperationException}
     * if this information is not available.}
     *
     * @return プール内にある使用されていないインスタンスの数
     * {@primary the total number of instances currently idle in my pool}
     * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合
     * {@primary when this implementation doesn't support the operation}
     */
    int getNumIdle() throws UnsupportedOperationException;

    /**
     * このプールから取得され、まだ戻されていないインスタンスの数を返します(オプショナルな処理)。
     * この情報を取得する機能を持たない場合 {@link UnsupportedOperationException} が投げられます。
     * {@primary Returns the total number of instances
     * current borrowed from my pool but not
     * yet returned (optional operation).
     * Throws {@link UnsupportedOperationException}
     * if this information is not available.}
     *
     * @return 現在プールから貸し出されているインスタンスの数
     * {@primary the total number of instances currently borrowed from my pool}
     * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合
     * {@primary when this implementation doesn't support the operation}
     */
    int getNumActive() throws UnsupportedOperationException;

    /**
     * 全てのプールされたインスタンスを削除し、プールをクリアします(オプショナルな処理)。
     * このプールが削除の機能を持たない場合 {@link UnsupportedOperationException} が投げられます。
     * {@primary Clears my pool, removing all pooled instances
     * (optional operation).
     * Throws {@link UnsupportedOperationException}
     * if the pool cannot be cleared.}
     *
     * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合
     * {@primary when this implementation doesn't support the operation}
     */
    void clear() throws Exception, UnsupportedOperationException;

    /**
     * 指定された <i>key</i> に対応するプールされたインスタンスを削除し、指定されたプールをクリアします(オプショナルな処理)。
     * このプールが削除の機能を持たない場合 {@link UnsupportedOperationException} が投げられます。
     * {@primary Clears the specified pool, removing all
     * pooled instances corresponding to
     * the given <i>key</i>  (optional operation).
     * Throws {@link UnsupportedOperationException}
     * if the pool cannot be cleared.}
     *
     * @param key the key to clear
     * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合
     * {@primary when this implementation doesn't support the operation}
     */
    void clear(Object key) throws Exception, UnsupportedOperationException;

    /**
     * このプールを閉じ、関連する全てのリソースを開放します。
     * {@primary Close this pool, and free any resources associated with it.}
     */
    void close() throws Exception;

    /**
     * 新たなインスタンスを生成するために使用する
     * {@link KeyedPoolableObjectFactory ファクトリ} を設定します(オプショナルな処理)。
     * {@primary Sets the {@link KeyedPoolableObjectFactory factory} I use
     * to create new instances (optional operation).}
     * @param factory 新たなインスタンスを生成するために使用する {@link KeyedPoolableObjectFactory}
     * {@primary the {@link KeyedPoolableObjectFactory} I use to create new instances.}
     * @throws IllegalStateException ファクトリを設定できる状態でない場合
     * {@primary IllegalStateException when the factory cannot be set at this time}
     * @throws UnsupportedOperationException この実装がこの処理をサポートしない場合
     * {@primary when this implementation doesn't support the operation}
     */
    void setFactory(KeyedPoolableObjectFactory factory) throws IllegalStateException, UnsupportedOperationException;
}