1 /*
2 * Copyright (c) 2003-2008 by Cosylab d. d.
3 *
4 * This file is part of Java-Common.
5 *
6 * Java-Common is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * Java-Common 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
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with Java-Common. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 package com.cosylab.util;
21
22 /**
23 * An object that is able of being recycled and stored in an object pool.
24 * This object must support:
25 * <ul>
26 * <li>
27 * <b>Resurrection.</b> When no other objects reference this object, this object
28 * may be garbage collected. Usually - if this is a small instance that is used
29 * (created) a lot of times, garbage collection will occur. In the <code>finalize</code>
30 * method, this object must call its <code>objectPool</code> and invoke method
31 * <code>returnToPool</code> on it. In this way, the object pool will contain
32 * a reference to <code>this</code>, making this object strongly reachable
33 * (see Java reference for explanation) after finalization and consequently
34 * making this object resurrected.
35 * </li>
36 * <li>
37 * <b>State reset.</code> In order to make this object useful again, it must support
38 * <code>clear</code> method. This method must force the object into the same state
39 * that it achieved during construction. Since object pools are mainly used for data
40 * holder objects, this would imply a reset of all data fields to their default values.
41 * </li>
42 * <li>
43 * <b>Holding a reference to the pool.</b> This reference is set through
44 * <code>setObjectPool</code> when the object is instantiated by the pool automatically,
45 * <b>OR</b> must be set by hand when the object is constructed manually.
46 * </li>
47 * </ul>
48 * <p>
49 * Note that object pools are mostly usable for simple data holder objects, which are
50 * created in great amounts and are also frequently released. This means that the receivers
51 * of these objects simply inspect some values (or even do nothing), after which they
52 * have no more use for the object and do not store it in some sort of data container structure.
53 * </p>
54 */
55 public interface PoolableObject
56 {
57
58 /**
59 * Clears the contents (data fields) of this object by resetting them to the
60 * uninitialized (after construction) values.
61 */
62 public void clear();
63
64 /**
65 * Sets the object pool to which this object belongs. During finalization of this
66 * object, it will attempt to resurrect itself by returning to the object pool.
67 *
68 * @param pool the pool to which this object will return
69 */
70 public void setObjectPool(ObjectPool pool);
71 }