01: /**
02: * EasyBeans
03: * Copyright (C) 2006 Bull S.A.S.
04: * Contact: easybeans@ow2.org
05: *
06: * This library is free software; you can redistribute it and/or
07: * modify it under the terms of the GNU Lesser General Public
08: * License as published by the Free Software Foundation; either
09: * version 2.1 of the License, or any later version.
10: *
11: * This library is distributed in the hope that it will be useful,
12: * but WITHOUT ANY WARRANTY; without even the implied warranty of
13: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14: * Lesser General Public License for more details.
15: *
16: * You should have received a copy of the GNU Lesser General Public
17: * License along with this library; if not, write to the Free Software
18: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
19: * USA
20: *
21: * --------------------------------------------------------------------------
22: * $Id: Pool.java 1970 2007-10-16 11:49:25Z benoitf $
23: * --------------------------------------------------------------------------
24: */package org.ow2.easybeans.api.pool;
25:
26: /**
27: * Defines a common pool interface used to manage objects.
28: * @param <InstanceType> the type of the object that are managed by the pool
29: * (could be EasyBeansSLSB, etc.)
30: * @param <Clue> a clue to retrieve a specific instance in the pool
31: * @author Florent Benoit
32: */
33: public interface Pool<InstanceType, Clue> extends PoolAttributes {
34:
35: /**
36: * Gets an object from the pool.
37: * @return an instance of an object with type Type.
38: * @throws PoolException if instance cannot be returned.
39: */
40: InstanceType get() throws PoolException;
41:
42: /**
43: * Gets an object by using a specific hint.
44: * @param clue attribute used to retrieve a given instance
45: * @return a specific instance of the resource.
46: * @throws PoolException if instance cannot be returned.
47: */
48: InstanceType get(Clue clue) throws PoolException;
49:
50: /**
51: * Puts back the instance in the pool so it can be reused.
52: * @param instance which will be put back in the pool.
53: * @throws PoolException if instance is not released.
54: */
55: void release(InstanceType instance) throws PoolException;
56:
57: /**
58: * Discard the instance which is in the pool.
59: * @param instance which will be discarded.
60: * @throws PoolException if instance is not discarded.
61: */
62: void discard(InstanceType instance) throws PoolException;
63:
64: /**
65: * Start the pool.<br>
66: * It could create initial instances if specified.
67: * @throws PoolException if initialization fails
68: */
69: void start() throws PoolException;
70:
71: /**
72: * Stop this pool.
73: * @throws PoolException if destroy fails
74: */
75: void stop() throws PoolException;
76: }
|