01: // jTDS JDBC Driver for Microsoft SQL Server and Sybase
02: // Copyright (C) 2004 The jTDS Project
03: //
04: // This library is free software; you can redistribute it and/or
05: // modify it under the terms of the GNU Lesser General Public
06: // License as published by the Free Software Foundation; either
07: // version 2.1 of the License, or (at your option) any later version.
08: //
09: // This library is distributed in the hope that it will be useful,
10: // but WITHOUT ANY WARRANTY; without even the implied warranty of
11: // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12: // Lesser General Public License for more details.
13: //
14: // You should have received a copy of the GNU Lesser General Public
15: // License along with this library; if not, write to the Free Software
16: // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
17: //
18: package net.sourceforge.jtds.jdbc.cache;
19:
20: import java.util.Collection;
21:
22: /**
23: * Interface for a statement cache. Abstraction of the caching mechanism by use
24: * of this interface will allow developers to create custom caching schemes
25: * that are optimal for their specific applications. Any synchronization
26: * required by an implementation should utilize the implementing object for the
27: * lock.
28: * <p>
29: * There are two types of attributes that the cache is concerned with:
30: * <dl>
31: * <dt>statement key</dt>
32: * <dd><code>String</code> generated from the SQL query for which the
33: * prepared statement was created, the database name and the parameter
34: * types; this key uniquely identifies a server-side preparation of the
35: * statement and is used to retrieve the handle of the statement when it
36: * needs to be executed</dd>
37: * <dt>temporary procedure name or <code>sp_prepare</code> or
38: * <code>sp_cursorprepare</code> handle on the server</dt>
39: * <dd>One <code>PreparedStatement</code> can map to multiple handles, depending on
40: * the types of the parameters it is called with (hence the need to be able
41: * to map both keys and SQL strings to handles)</dd>
42: * </dl>
43: * The cache can retrieve statement handles using statement keys.
44: * <p>
45: * The caching types provided by jTDS should be:
46: * <ul>
47: * <li>Arbitrary first un-latched (initial default until other caches are
48: * implemented)</li>
49: * <li>Fast caching (never latches and never releases handles)</li>
50: * <li>FIFO</li>
51: * <li>LRU</li>
52: * <li>No caching</li>
53: * <li>Touch Count / Most Frequently Used</li>
54: * </ul>
55: *
56: * @author Brian Heineman
57: * @version $Id: StatementCache.java,v 1.6 2007/07/11 19:57:06 bheineman Exp $
58: */
59: public interface StatementCache {
60: /**
61: * Returns a statement handle associated with the specified key or
62: * <code>null</code> if the key specified does not have an associated
63: * statement handle.
64: *
65: * @param key the statement key whose associated handle is to be returned
66: * @return statement handle
67: */
68: Object get(String key);
69:
70: /**
71: * Places the specified statement handle in the cache for the given key. If
72: * a key already exists in the cache, the handle will be overwritten.
73: *
74: * @param key the statement key to associated with the handle
75: * @param handle the statement handle
76: */
77: void put(String key, Object handle);
78:
79: /**
80: * Removes a statement key and handle from the cache for the specified key.
81: *
82: * @param key the statement key whose associated handle is to be removed
83: * from the cache
84: */
85: void remove(String key);
86:
87: /**
88: * Returns a <code>Collection</code> of obsolete statement handles that may
89: * be released, or <code>null</code> if no statement handles are obsolete.
90: *
91: * @param handles the statement handles that are no longer being used
92: * @return <code>Collection</code> of obsolete statement handles to be
93: * removed
94: */
95: Collection getObsoleteHandles(Collection handles);
96: }
|