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 */ 017 018 package org.apache.commons.pool; 019 020 /** 021 * A simple base implementation of <code>KeyedObjectPool</code>. 022 * Optional operations are implemented to either do nothing, return a value 023 * indicating it is unsupported or throw {@link UnsupportedOperationException}. 024 * 025 * @param <K> the type of keys in this pool 026 * @param <V> the type of objects held in this pool 027 * 028 * @author Rodney Waldhoff 029 * @author Sandy McArthur 030 * @version $Revision: 1222396 $ $Date: 2011-12-22 14:02:25 -0500 (Thu, 22 Dec 2011) $ 031 * @since Pool 1.0 032 */ 033 public abstract class BaseKeyedObjectPool<K, V> implements KeyedObjectPool<K, V> { 034 035 /** 036 * {@inheritDoc} 037 */ 038 public abstract V borrowObject(K key) throws Exception; 039 040 /** 041 * {@inheritDoc} 042 */ 043 public abstract void returnObject(K key, V obj) throws Exception; 044 045 /** 046 * <p>Invalidates an object from the pool.</p> 047 * 048 * <p>By contract, <code>obj</code> <strong>must</strong> have been obtained 049 * using {@link #borrowObject borrowObject} using a <code>key</code> that is 050 * equivalent to the one used to borrow the <code>Object</code> in the first place.</p> 051 * 052 * <p>This method should be used when an object that has been borrowed 053 * is determined (due to an exception or other problem) to be invalid.</p> 054 * 055 * @param key the key used to obtain the object 056 * @param obj a {@link #borrowObject borrowed} instance to be returned. 057 * @throws Exception 058 */ 059 public abstract void invalidateObject(K key, V obj) throws Exception; 060 061 /** 062 * Not supported in this base implementation. 063 * Always throws an {@link UnsupportedOperationException}, 064 * subclasses should override this behavior. 065 * @param key ignored 066 * @throws UnsupportedOperationException 067 */ 068 public void addObject(K key) throws Exception, UnsupportedOperationException { 069 throw new UnsupportedOperationException(); 070 } 071 072 /** 073 * Not supported in this base implementation. 074 * @return a negative value. 075 * @param key ignored 076 */ 077 public int getNumIdle(K key) throws UnsupportedOperationException { 078 return -1; 079 } 080 081 /** 082 * Not supported in this base implementation. 083 * @return a negative value. 084 * @param key ignored 085 */ 086 public int getNumActive(K key) throws UnsupportedOperationException { 087 return -1; 088 } 089 090 /** 091 * Not supported in this base implementation. 092 * @return a negative value. 093 */ 094 public int getNumIdle() throws UnsupportedOperationException { 095 return -1; 096 } 097 098 /** 099 * Not supported in this base implementation. 100 * @return a negative value. 101 */ 102 public int getNumActive() throws UnsupportedOperationException { 103 return -1; 104 } 105 106 /** 107 * Not supported in this base implementation. 108 * @throws UnsupportedOperationException 109 */ 110 public void clear() throws Exception, UnsupportedOperationException { 111 throw new UnsupportedOperationException(); 112 } 113 114 /** 115 * Not supported in this base implementation. 116 * @param key ignored 117 * @throws UnsupportedOperationException 118 */ 119 public void clear(K key) throws Exception, UnsupportedOperationException { 120 throw new UnsupportedOperationException(); 121 } 122 123 /** 124 * Close this pool. 125 * This affects the behavior of <code>isClosed</code> and <code>assertOpen</code>. 126 */ 127 public void close() throws Exception { 128 closed = true; 129 } 130 131 /** 132 * Not supported in this base implementation. 133 * Always throws an {@link UnsupportedOperationException}, 134 * subclasses should override this behavior. 135 * @param factory the new KeyedPoolableObjectFactory 136 * @deprecated to be removed in pool 2.0 137 */ 138 @Deprecated 139 public void setFactory(KeyedPoolableObjectFactory<K, V> factory) throws IllegalStateException, UnsupportedOperationException { 140 throw new UnsupportedOperationException(); 141 } 142 143 /** 144 * Has this pool instance been closed. 145 * @return <code>true</code> when this pool has been closed. 146 * @since Pool 1.4 147 */ 148 protected final boolean isClosed() { 149 return closed; 150 } 151 152 /** 153 * Throws an <code>IllegalStateException</code> when this pool has been closed. 154 * @throws IllegalStateException when this pool has been closed. 155 * @see #isClosed() 156 * @since Pool 1.4 157 */ 158 protected final void assertOpen() throws IllegalStateException { 159 if(isClosed()) { 160 throw new IllegalStateException("Pool not open"); 161 } 162 } 163 164 /** Whether or not the pool is close */ 165 private volatile boolean closed = false; 166 }