Package: ObjectPool

ObjectPool

Coverage

1: /*
2: * Copyright (c) 2012, 2017 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Public License v. 2.0, which is available at
6: * http://www.eclipse.org/legal/epl-2.0.
7: *
8: * This Source Code may also be made available under the following Secondary
9: * Licenses when the conditions for such availability set forth in the
10: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11: * version 2 with the GNU Classpath Exception, which is available at
12: * https://www.gnu.org/software/classpath/license.html.
13: *
14: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15: */
16:
17: package org.glassfish.grizzly.memcached.pool;
18:
19: import java.util.concurrent.TimeoutException;
20:
21: /**
22: * Keyed object pooling interface
23: *
24: * ObjectPool interface mainly defines {@link #borrowObject borrowObject}, {@link #returnObject returnObject} and {@link #removeObject removeObject}.
25: *
26: * Example of use:
27: * {@code
28: * Object obj = null;
29: * try {
30: * obj = pool.borrowObject(key, timeout);
31: * try {
32: * //...use the object...
33: * } catch(Exception e) {
34: * // invalidate the object
35: * try {
36: * pool.removeObject(key, obj);
37: * } catch(Exception ignore) {
38: * }
39: * // do not return the object to the pool twice
40: * obj = null;
41: * } finally {
42: * // make sure the object is returned to the pool
43: * if(obj != null) {
44: * try {
45: * pool.returnObject(key, obj);
46: * } catch(Exception ignore) {
47: * }
48: * }
49: * }
50: * } catch(Exception e) {
51: * // failed to borrow an object(pool exhausted, no valid object, interrupted or etc...)
52: * }
53: * }
54: * @author Bongjae Chang
55: */
56: public interface ObjectPool<K, V> {
57:
58: /**
59: * Create objects using the {@link PoolableObjectFactory factory} until pool's minimum size, and then place them in the idle object pool
60: * <p>
61: * {@code createAllMinObjects} is useful for "pre-loading" a pool with idle objects.
62: *
63: * @param key the key new instances should be added to
64: * @throws Exception if an unexpected exception occurred
65: */
66: public void createAllMinObjects(final K key) throws Exception;
67:
68: /**
69: * Obtains an instance from this pool
70: * <p>
71: * Instances returned from this method will have been either newly created with
72: * {@link PoolableObjectFactory#createObject createObject} or will be a previously idle object and
73: * then validated with {@link PoolableObjectFactory#validateObject validateObject}.
74: * <p>
75: * By contract, clients should return the borrowed instance using
76: * {@link #returnObject returnObject}, {@link #removeObject removeObject}
77: * <p>
78: * When the pool has been exhausted, a {@link PoolExhaustedException} will be thrown.
79: *
80: * @param key the key used to obtain the object
81: * @param timeoutInMillis the max time(milli-second) for borrowing the object. If the pool cannot return an instance in given time,
82: * {@link PoolExhaustedException} will be thrown.
83: * @return an instance from this pool
84: * @throws PoolExhaustedException when the pool is exhausted
85: * @throws NoValidObjectException when the pool cannot or will not return another instance
86: * @throws TimeoutException when the pool cannot or will not return another instance because of connection timeout
87: * @throws InterruptedException when the pool is interrupted
88: */
89: public V borrowObject(final K key, final long timeoutInMillis) throws PoolExhaustedException, NoValidObjectException,
90: TimeoutException, InterruptedException;
91:
92: /**
93: * Return an instance to the pool
94: * <p>
95: * By contract, {@code value} should have been obtained
96: * using {@link #borrowObject borrowObject} using a {@code key} that is equivalent to the one used to
97: * borrow the instance in the first place.
98: *
99: * @param key the key used to obtain the object
100: * @param value a {@link #borrowObject borrowed} instance to be returned
101: * @throws Exception if an unexpected exception occurred
102: */
103: public void returnObject(final K key, final V value) throws Exception;
104:
105: /**
106: * Removes(invalidates) an object from the pool
107: * <p>
108: * By contract, {@code value} should have been obtained
109: * using {@link #borrowObject borrowObject} using a {@code key} that is equivalent to the one used to
110: * borrow the instance in the first place.
111: * <p>
112: * This method should be used when an object that has been borrowed
113: * is determined (due to an exception or other problem) to be invalid.
114: *
115: * @param key the key used to obtain the object
116: * @param value a {@link #borrowObject borrowed} instance to be removed
117: * @throws Exception if an unexpected exception occurred
118: */
119: public void removeObject(final K key, final V value) throws Exception;
120:
121: /**
122: * Clears the specified pool, removing all pooled instances corresponding to the given {@code key}
123: *
124: * @param key the key to clear
125: * @throws Exception if an unexpected exception occurred
126: */
127: public void removeAllObjects(final K key) throws Exception;
128:
129: /**
130: * Destroy the specified pool, removing all pooled instances, mapping key and statistics corresponding to the given {@code key}
131: * <p>
132: * After destroying, {@link #borrowObject} with the given {@code key} will be failed.
133: *
134: * @param key the key to destroy
135: * @throws Exception if an unexpected exception occurred
136: */
137: public void destroy(final K key) throws Exception;
138:
139: /**
140: * Destroy this pool, and free any resources associated with it
141: * <p>
142: * Calling other methods such as {@link #createAllMinObjects createAllMinObjects} or {@link #borrowObject borrowObject},
143: * {@link #returnObject returnObject} or {@link #removeObject removeObject} or {@link #removeAllObjects removeAllObjects} after invoking
144: * this method on a pool will cause them to throw an {@link IllegalStateException}.
145: * </p>
146: */
147: public void destroy();
148:
149: /**
150: * Returns the total number of instances
151: *
152: * @param key the key to query
153: * @return the total number of instances corresponding to the given {@code key} currently idle and active in this pool or a negative value if unsupported
154: */
155: public int getPoolSize(final K key);
156:
157: /**
158: * Returns the total peak number of instances
159: *
160: * @param key the key to query
161: * @return the peak number of instances corresponding to the given {@code key} or a negative value if unsupported
162: */
163: public int getPeakCount(final K key);
164:
165: /**
166: * Returns the number of instances currently borrowed from but not yet returned to the pool
167: *
168: * @param key the key to query
169: * @return the number of instances corresponding to the given {@code key} currently borrowed in this pool or a negative value if unsupported
170: */
171: public int getActiveCount(final K key);
172:
173: /**
174: * Returns the number of instances currently idle in this pool
175: *
176: * @param key the key to query
177: * @return the number of instances corresponding to the given {@code key} currently idle in this pool or a negative value if unsupported
178: */
179: public int getIdleCount(final K key);
180: }