Package: PoolableObjectFactory

PoolableObjectFactory

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: /**
20: * An interface defining life-cycle methods for instances to be served by a {@link ObjectPool}
21: * <p>
22: * By contract, when an {@link ObjectPool} delegates to a {@link PoolableObjectFactory},
23: * {@link #createObject createObject} is called whenever a new instance is needed.
24: * {@link #validateObject validateObject} is invoked for making sure
25: * they can be {@link ObjectPool#borrowObject borrowed} or {@link ObjectPool#returnObject returned} from the pool.
26: * {@link #destroyObject destroyObject} is invoked on every instance when it is being "dropped" from the pool.
27: *
28: * @author Bongjae Chang
29: */
30: public interface PoolableObjectFactory<K, V> {
31:
32: /**
33: * Create an instance that can be served by the pool
34: *
35: * @param key the key used when constructing the object
36: * @return an instance that can be served by the pool
37: * @throws Exception if there is a problem creating a new instance
38: */
39: public V createObject(final K key) throws Exception;
40:
41: /**
42: * Destroy an instance no longer needed by the pool
43: *
44: * @param key the key used when selecting the instance
45: * @param value the instance to be destroyed
46: * @throws Exception if there is a problem destroying {@code value}
47: */
48: public void destroyObject(final K key, final V value) throws Exception;
49:
50: /**
51: * Ensures that the instance is safe to be borrowed and returned by the pool
52: *
53: * @param key the key used when selecting the object
54: * @param value the instance to be validated
55: * @return false if {@code value} is not valid and should be dropped from the pool,
56: * true otherwise
57: * @throws Exception if there is a problem validating {@code value}.
58: * an exception should be avoided as it may be swallowed by the pool implementation.
59: */
60: public boolean validateObject(final K key, final V value) throws Exception;
61: }