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