src/java/org/apache/commons/pool2/impl/GenericObjectPoolMBean.java - commons-pool - Git at Google

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.apache.commons.pool2.impl;

 import org.apache.commons.pool2.PoolableObjectFactory;

 /**
  * The <code>GenericObjectPool</code> JMX interface.
  *
  * @version $Revision$ $Date$
  * @since 2.0
  */
 public interface GenericObjectPoolMBean<T> {

     /**
      * Returns the maximum number of objects that can be allocated by the pool
      * (checked out to clients, or idle awaiting checkout) at a given time.
      * When non-positive, there is no limit to the number of objects that can
      * be managed by the pool at one time.
      *
      * @return the cap on the total number of object instances managed by the pool.
      */
     int getMaxTotal();

     /**
      * Sets the cap on the number of objects that can be allocated by the pool
      * (checked out to clients, or idle awaiting checkout) at a given time. Use
      * a negative value for no limit.
      *
      * @param maxTotal The cap on the total number of object instances managed by the pool.
      * Negative values mean that there is no limit to the number of objects allocated
      * by the pool.
      */
     void setMaxTotal(int maxTotal);

     /**
      * Returns the action to take when the {@link #borrowObject} method
      * is invoked when the pool is exhausted (the maximum number
      * of "active" objects has been reached).
      *
      * @return one of {@link WhenExhaustedAction#BLOCK},
      *      {@link WhenExhaustedAction#FAIL} or {@link WhenExhaustedAction#GROW}
      */
     WhenExhaustedAction getWhenExhaustedAction();

     /**
      * Sets the action to take when the {@link #borrowObject} method
      * is invoked when the pool is exhausted (the maximum number
      * of "active" objects has been reached).
      *
      * @param whenExhaustedAction the action code, which must be one of
      *        {@link WhenExhaustedAction#BLOCK}, {@link WhenExhaustedAction#FAIL},
      *        or {@link WhenExhaustedAction#GROW}
      */
     void setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction);

     /**
      * Returns the maximum amount of time (in milliseconds) the
      * {@link #borrowObject} method should block before throwing
      * an exception when the pool is exhausted and the
      * {@link #setWhenExhaustedAction "when exhausted" action} is
      * {@link WhenExhaustedAction#BLOCK}.
      *
      * When less than or equal to 0, the {@link #borrowObject} method
      * may block indefinitely.
      *
      * @return maximum number of milliseconds to block when borrowing an object.
      */
     long getMaxWait();

     /**
      * Sets the maximum amount of time (in milliseconds) the
      * {@link #borrowObject} method should block before throwing
      * an exception when the pool is exhausted and the
      * {@link #setWhenExhaustedAction "when exhausted" action} is
      * {@link WhenExhaustedAction#BLOCK}.
      *
      * When less than or equal to 0, the {@link #borrowObject} method
      * may block indefinitely.
      *
      * @param maxWait maximum number of milliseconds to block when borrowing an object.
      */
     void setMaxWait(long maxWait);

     /**
      * Returns the cap on the number of "idle" instances in the pool.
      *
      * @return the cap on the number of "idle" instances in the pool.
      */
     int getMaxIdle();

     /**
      * Sets the cap on the number of "idle" instances in the pool.
      * If maxIdle is set too low on heavily loaded systems it is possible you
      * will see objects being destroyed and almost immediately new objects
      * being created. This is a result of the active threads momentarily
      * returning objects faster than they are requesting them them, causing the
      * number of idle objects to rise above maxIdle. The best value for maxIdle
      * for heavily loaded system will vary but the default is a good starting
      * point.
      *
      * @param maxIdle The cap on the number of "idle" instances in the pool.
      * Use a negative value to indicate an unlimited number of idle instances.
      */
     void setMaxIdle(int maxIdle);

     /**
      * Sets the minimum number of objects allowed in the pool
      * before the evictor thread (if active) spawns new objects.
      * Note that no objects are created when
      * <code>numActive + numIdle >= maxActive.</code>
      * This setting has no effect if the idle object evictor is disabled
      * (i.e. if <code>timeBetweenEvictionRunsMillis <= 0</code>).
      *
      * @param minIdle The minimum number of objects.
      */
     void setMinIdle(int minIdle);

     /**
      * Returns the minimum number of objects allowed in the pool
      * before the evictor thread (if active) spawns new objects.
      * (Note no objects are created when: numActive + numIdle >= maxActive)
      *
      * @return The minimum number of objects.
      */
     int getMinIdle();

     /**
      * When <tt>true</tt>, objects will be
      * {@link PoolableObjectFactory#validateObject validated}
      * before being returned by the {@link #borrowObject}
      * method.  If the object fails to validate,
      * it will be dropped from the pool, and we will attempt
      * to borrow another.
      *
      * @return <code>true</code> if objects are validated before being borrowed.
      */
     boolean getTestOnBorrow();

     /**
      * When <tt>true</tt>, objects will be
      * {@link PoolableObjectFactory#validateObject validated}
      * before being returned by the {@link #borrowObject}
      * method.  If the object fails to validate,
      * it will be dropped from the pool, and we will attempt
      * to borrow another.
      *
      * @param testOnBorrow <code>true</code> if objects should be validated before being borrowed.
      */
     void setTestOnBorrow(boolean testOnBorrow);

     /**
      * When <tt>true</tt>, objects will be
      * {@link PoolableObjectFactory#validateObject validated}
      * before being returned to the pool within the
      * {@link #returnObject}.
      *
      * @return <code>true</code> when objects will be validated after returned to {@link #returnObject}.
      */
     boolean getTestOnReturn();

     /**
      * When <tt>true</tt>, objects will be
      * {@link PoolableObjectFactory#validateObject validated}
      * before being returned to the pool within the
      * {@link #returnObject}.
      *
      * @param testOnReturn <code>true</code> so objects will be validated after returned to {@link #returnObject}.
      */
     void setTestOnReturn(boolean testOnReturn);

     /**
      * Returns the number of milliseconds to sleep between runs of the
      * idle object evictor thread.
      * When non-positive, no idle object evictor thread will be
      * run.
      *
      * @return number of milliseconds to sleep between evictor runs.
      */
     long getTimeBetweenEvictionRunsMillis();

     /**
      * Sets the number of milliseconds to sleep between runs of the
      * idle object evictor thread.
      * When non-positive, no idle object evictor thread will be
      * run.
      *
      * @param timeBetweenEvictionRunsMillis number of milliseconds to sleep between evictor runs.
      */
     void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis);

     /**
      * Returns the max number of objects to examine during each run of the
      * idle object evictor thread (if any).
      *
      * @return max number of objects to examine during each evictor run.
      */
     int getNumTestsPerEvictionRun();

     /**
      * Sets the max number of objects to examine during each run of the
      * idle object evictor thread (if any).
      * <p>
      * When a negative value is supplied, <tt>ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})</tt>
      * tests will be run.  That is, when the value is <i>-n</i>, roughly one <i>n</i>th of the
      * idle objects will be tested per run. When the value is positive, the number of tests
      * actually performed in each run will be the minimum of this value and the number of instances
      * idle in the pool.
      *
      * @param numTestsPerEvictionRun max number of objects to examine during each evictor run.
      */
     void setNumTestsPerEvictionRun(int numTestsPerEvictionRun);

     /**
      * Returns the minimum amount of time an object may sit idle in the pool
      * before it is eligible for eviction by the idle object evictor
      * (if any).
      *
      * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
      */
     long getMinEvictableIdleTimeMillis();

     /**
      * Sets the minimum amount of time an object may sit idle in the pool
      * before it is eligible for eviction by the idle object evictor
      * (if any).
      * When non-positive, no objects will be evicted from the pool
      * due to idle time alone.
      *
      * @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
      * it is eligible for eviction.
      */
     void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis);

     /**
      * Returns the minimum amount of time an object may sit idle in the pool
      * before it is eligible for eviction by the idle object evictor
      * (if any), with the extra condition that at least
      * "minIdle" amount of object remain in the pool.
      *
      * @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
      */
     long getSoftMinEvictableIdleTimeMillis();

     /**
      * Sets the minimum amount of time an object may sit idle in the pool
      * before it is eligible for eviction by the idle object evictor
      * (if any), with the extra condition that at least
      * "minIdle" object instances remain in the pool.
      * When non-positive, no objects will be evicted from the pool
      * due to idle time alone.
      *
      * @param softMinEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
      * it is eligible for eviction.
      */
     void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis);

     /**
      * When <tt>true</tt>, objects will be
      * {@link PoolableObjectFactory#validateObject validated}
      * by the idle object evictor (if any).  If an object
      * fails to validate, it will be dropped from the pool.
      *
      * @return <code>true</code> when objects will be validated by the evictor.
      */
     boolean getTestWhileIdle();

     /**
      * When <tt>true</tt>, objects will be
      * {@link PoolableObjectFactory#validateObject validated}
      * by the idle object evictor (if any).  If an object
      * fails to validate, it will be dropped from the pool.
      *
      * @param testWhileIdle <code>true</code> so objects will be validated by the evictor.
      */
     void setTestWhileIdle(boolean testWhileIdle);

     /**
      * Whether or not the idle object pool acts as a LIFO queue. True means
      * that borrowObject returns the most recently used ("last in") idle object
      * in the pool (if there are idle instances available).  False means that
      * the pool behaves as a FIFO queue - objects are taken from the idle object
      * pool in the order that they are returned to the pool.
      *
      * @return <code>true</true> if the pool is configured to act as a LIFO queue
      */
     boolean getLifo();

     /**
      * Sets the LIFO property of the pool. True means that borrowObject returns
      * the most recently used ("last in") idle object in the pool (if there are
      * idle instances available).  False means that the pool behaves as a FIFO
      * queue - objects are taken from the idle object pool in the order that
      * they are returned to the pool.
      *
      * @param lifo the new value for the LIFO property
      */
     void setLifo(boolean lifo);

     /**
      * Return the number of instances currently borrowed from this pool.
      *
      * @return the number of instances currently borrowed from this pool
      */
     int getNumActive();

     /**
      * Return the number of instances currently idle in this pool.
      *
      * @return the number of instances currently idle in this pool
      */
     int getNumIdle();

 }
	/*
	* Licensed to the Apache Software Foundation (ASF) under one or more
	* contributor license agreements. See the NOTICE file distributed with
	* this work for additional information regarding copyright ownership.
	* The ASF licenses this file to You under the Apache License, Version 2.0
	* (the "License"); you may not use this file except in compliance with
	* the License. You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/
	package org.apache.commons.pool2.impl;

	import org.apache.commons.pool2.PoolableObjectFactory;

	/**
	* The <code>GenericObjectPool</code> JMX interface.
	*
	* @version $Revision$ $Date$
	* @since 2.0
	*/
	public interface GenericObjectPoolMBean<T> {

	/**
	* Returns the maximum number of objects that can be allocated by the pool
	* (checked out to clients, or idle awaiting checkout) at a given time.
	* When non-positive, there is no limit to the number of objects that can
	* be managed by the pool at one time.
	*
	* @return the cap on the total number of object instances managed by the pool.
	*/
	int getMaxTotal();

	/**
	* Sets the cap on the number of objects that can be allocated by the pool
	* (checked out to clients, or idle awaiting checkout) at a given time. Use
	* a negative value for no limit.
	*
	* @param maxTotal The cap on the total number of object instances managed by the pool.
	* Negative values mean that there is no limit to the number of objects allocated
	* by the pool.
	*/
	void setMaxTotal(int maxTotal);

	/**
	* Returns the action to take when the {@link #borrowObject} method
	* is invoked when the pool is exhausted (the maximum number
	* of "active" objects has been reached).
	*
	* @return one of {@link WhenExhaustedAction#BLOCK},
	* {@link WhenExhaustedAction#FAIL} or {@link WhenExhaustedAction#GROW}
	*/
	WhenExhaustedAction getWhenExhaustedAction();

	/**
	* Sets the action to take when the {@link #borrowObject} method
	* is invoked when the pool is exhausted (the maximum number
	* of "active" objects has been reached).
	*
	* @param whenExhaustedAction the action code, which must be one of
	* {@link WhenExhaustedAction#BLOCK}, {@link WhenExhaustedAction#FAIL},
	* or {@link WhenExhaustedAction#GROW}
	*/
	void setWhenExhaustedAction(WhenExhaustedAction whenExhaustedAction);

	/**
	* Returns the maximum amount of time (in milliseconds) the
	* {@link #borrowObject} method should block before throwing
	* an exception when the pool is exhausted and the
	* {@link #setWhenExhaustedAction "when exhausted" action} is
	* {@link WhenExhaustedAction#BLOCK}.
	*
	* When less than or equal to 0, the {@link #borrowObject} method
	* may block indefinitely.
	*
	* @return maximum number of milliseconds to block when borrowing an object.
	*/
	long getMaxWait();

	/**
	* Sets the maximum amount of time (in milliseconds) the
	* {@link #borrowObject} method should block before throwing
	* an exception when the pool is exhausted and the
	* {@link #setWhenExhaustedAction "when exhausted" action} is
	* {@link WhenExhaustedAction#BLOCK}.
	*
	* When less than or equal to 0, the {@link #borrowObject} method
	* may block indefinitely.
	*
	* @param maxWait maximum number of milliseconds to block when borrowing an object.
	*/
	void setMaxWait(long maxWait);

	/**
	* Returns the cap on the number of "idle" instances in the pool.
	*
	* @return the cap on the number of "idle" instances in the pool.
	*/
	int getMaxIdle();

	/**
	* Sets the cap on the number of "idle" instances in the pool.
	* If maxIdle is set too low on heavily loaded systems it is possible you
	* will see objects being destroyed and almost immediately new objects
	* being created. This is a result of the active threads momentarily
	* returning objects faster than they are requesting them them, causing the
	* number of idle objects to rise above maxIdle. The best value for maxIdle
	* for heavily loaded system will vary but the default is a good starting
	* point.
	*
	* @param maxIdle The cap on the number of "idle" instances in the pool.
	* Use a negative value to indicate an unlimited number of idle instances.
	*/
	void setMaxIdle(int maxIdle);

	/**
	* Sets the minimum number of objects allowed in the pool
	* before the evictor thread (if active) spawns new objects.
	* Note that no objects are created when
	* <code>numActive + numIdle >= maxActive.</code>
	* This setting has no effect if the idle object evictor is disabled
	* (i.e. if <code>timeBetweenEvictionRunsMillis <= 0</code>).
	*
	* @param minIdle The minimum number of objects.
	*/
	void setMinIdle(int minIdle);

	/**
	* Returns the minimum number of objects allowed in the pool
	* before the evictor thread (if active) spawns new objects.
	* (Note no objects are created when: numActive + numIdle >= maxActive)
	*
	* @return The minimum number of objects.
	*/
	int getMinIdle();

	/**
	* When <tt>true</tt>, objects will be
	* {@link PoolableObjectFactory#validateObject validated}
	* before being returned by the {@link #borrowObject}
	* method. If the object fails to validate,
	* it will be dropped from the pool, and we will attempt
	* to borrow another.
	*
	* @return <code>true</code> if objects are validated before being borrowed.
	*/
	boolean getTestOnBorrow();

	/**
	* When <tt>true</tt>, objects will be
	* {@link PoolableObjectFactory#validateObject validated}
	* before being returned by the {@link #borrowObject}
	* method. If the object fails to validate,
	* it will be dropped from the pool, and we will attempt
	* to borrow another.
	*
	* @param testOnBorrow <code>true</code> if objects should be validated before being borrowed.
	*/
	void setTestOnBorrow(boolean testOnBorrow);

	/**
	* When <tt>true</tt>, objects will be
	* {@link PoolableObjectFactory#validateObject validated}
	* before being returned to the pool within the
	* {@link #returnObject}.
	*
	* @return <code>true</code> when objects will be validated after returned to {@link #returnObject}.
	*/
	boolean getTestOnReturn();

	/**
	* When <tt>true</tt>, objects will be
	* {@link PoolableObjectFactory#validateObject validated}
	* before being returned to the pool within the
	* {@link #returnObject}.
	*
	* @param testOnReturn <code>true</code> so objects will be validated after returned to {@link #returnObject}.
	*/
	void setTestOnReturn(boolean testOnReturn);

	/**
	* Returns the number of milliseconds to sleep between runs of the
	* idle object evictor thread.
	* When non-positive, no idle object evictor thread will be
	* run.
	*
	* @return number of milliseconds to sleep between evictor runs.
	*/
	long getTimeBetweenEvictionRunsMillis();

	/**
	* Sets the number of milliseconds to sleep between runs of the
	* idle object evictor thread.
	* When non-positive, no idle object evictor thread will be
	* run.
	*
	* @param timeBetweenEvictionRunsMillis number of milliseconds to sleep between evictor runs.
	*/
	void setTimeBetweenEvictionRunsMillis(long timeBetweenEvictionRunsMillis);

	/**
	* Returns the max number of objects to examine during each run of the
	* idle object evictor thread (if any).
	*
	* @return max number of objects to examine during each evictor run.
	*/
	int getNumTestsPerEvictionRun();

	/**
	* Sets the max number of objects to examine during each run of the
	* idle object evictor thread (if any).
	* <p>
	* When a negative value is supplied, <tt>ceil({@link #getNumIdle})/abs({@link #getNumTestsPerEvictionRun})</tt>
	* tests will be run. That is, when the value is <i>-n</i>, roughly one <i>n</i>th of the
	* idle objects will be tested per run. When the value is positive, the number of tests
	* actually performed in each run will be the minimum of this value and the number of instances
	* idle in the pool.
	*
	* @param numTestsPerEvictionRun max number of objects to examine during each evictor run.
	*/
	void setNumTestsPerEvictionRun(int numTestsPerEvictionRun);

	/**
	* Returns the minimum amount of time an object may sit idle in the pool
	* before it is eligible for eviction by the idle object evictor
	* (if any).
	*
	* @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
	*/
	long getMinEvictableIdleTimeMillis();

	/**
	* Sets the minimum amount of time an object may sit idle in the pool
	* before it is eligible for eviction by the idle object evictor
	* (if any).
	* When non-positive, no objects will be evicted from the pool
	* due to idle time alone.
	*
	* @param minEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
	* it is eligible for eviction.
	*/
	void setMinEvictableIdleTimeMillis(long minEvictableIdleTimeMillis);

	/**
	* Returns the minimum amount of time an object may sit idle in the pool
	* before it is eligible for eviction by the idle object evictor
	* (if any), with the extra condition that at least
	* "minIdle" amount of object remain in the pool.
	*
	* @return minimum amount of time an object may sit idle in the pool before it is eligible for eviction.
	*/
	long getSoftMinEvictableIdleTimeMillis();

	/**
	* Sets the minimum amount of time an object may sit idle in the pool
	* before it is eligible for eviction by the idle object evictor
	* (if any), with the extra condition that at least
	* "minIdle" object instances remain in the pool.
	* When non-positive, no objects will be evicted from the pool
	* due to idle time alone.
	*
	* @param softMinEvictableIdleTimeMillis minimum amount of time an object may sit idle in the pool before
	* it is eligible for eviction.
	*/
	void setSoftMinEvictableIdleTimeMillis(long softMinEvictableIdleTimeMillis);

	/**
	* When <tt>true</tt>, objects will be
	* {@link PoolableObjectFactory#validateObject validated}
	* by the idle object evictor (if any). If an object
	* fails to validate, it will be dropped from the pool.
	*
	* @return <code>true</code> when objects will be validated by the evictor.
	*/
	boolean getTestWhileIdle();

	/**
	* When <tt>true</tt>, objects will be
	* {@link PoolableObjectFactory#validateObject validated}
	* by the idle object evictor (if any). If an object
	* fails to validate, it will be dropped from the pool.
	*
	* @param testWhileIdle <code>true</code> so objects will be validated by the evictor.
	*/
	void setTestWhileIdle(boolean testWhileIdle);

	/**
	* Whether or not the idle object pool acts as a LIFO queue. True means
	* that borrowObject returns the most recently used ("last in") idle object
	* in the pool (if there are idle instances available). False means that
	* the pool behaves as a FIFO queue - objects are taken from the idle object
	* pool in the order that they are returned to the pool.
	*
	* @return <code>true</true> if the pool is configured to act as a LIFO queue
	*/
	boolean getLifo();

	/**
	* Sets the LIFO property of the pool. True means that borrowObject returns
	* the most recently used ("last in") idle object in the pool (if there are
	* idle instances available). False means that the pool behaves as a FIFO
	* queue - objects are taken from the idle object pool in the order that
	* they are returned to the pool.
	*
	* @param lifo the new value for the LIFO property
	*/
	void setLifo(boolean lifo);

	/**
	* Return the number of instances currently borrowed from this pool.
	*
	* @return the number of instances currently borrowed from this pool
	*/
	int getNumActive();

	/**
	* Return the number of instances currently idle in this pool.
	*
	* @return the number of instances currently idle in this pool
	*/
	int getNumIdle();

	}