001: /*
002: * Copyright 2004 Clinton Begin
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package com.ibatis.sqlmap.client;
017:
018: import java.sql.Connection;
019:
020: /**
021: * A thread safe client for working with your SQL Maps (Start Here). This interface inherits transaction control
022: * and execution methods from the SqlMapTransactionManager and SqlMapExecutor interfaces.
023: * <p/>
024: * The SqlMapClient is the central class for working with SQL Maps. This class will allow you
025: * to run mapped statements (select, insert, update, delete etc.), and also demarcate
026: * transactions and work with batches. Once you have an SqlMapClient instance, everything
027: * you need to work with SQL Maps is easily available.
028: * <p/>
029: * The SqlMapClient can either
030: * be worked with directly as a multi-threaded client (internal session management), or you can get a single threaded
031: * session and work with that. There may be a slight performance increase if you explicitly
032: * get a session (using the openSession() method), as it saves the SqlMapClient from having
033: * to manage threads contexts. But for most cases it won't make much of a difference, so
034: * choose whichever paradigm suits your needs or preferences.
035: * <p/>
036: * An SqlMapClient instance can be safely made <i>static</i> or applied as a <i>Singleton</i>.
037: * Generally it's a good idea to make a simple configuration class that will configure the
038: * instance (using SqlMapClientBuilder) and provide access to it.
039: * <p/>
040: * <b>The following example will demonstrate the use of SqlMapClient.</b>
041: * <pre>
042: * <i><font color="green">
043: * //
044: * // autocommit simple query --these are just examples...not patterns
045: * //
046: * </font></i>
047: * Employee emp = (Employee) <b>sqlMap.queryForObject("getEmployee", new Integer(1))</b>;
048: * <i><font color="green">
049: * //
050: * // transaction --these are just examples...not patterns
051: * //
052: * </font></i>
053: * try {
054: * <b>sqlMap.startTransaction()</b>
055: * Employee emp2 = new Employee();
056: * // ...set emp2 data
057: * Integer generatedKey = (Integer) <b>sqlMap.insert ("insertEmployee", emp2)</b>;
058: * emp2.setFavouriteColour ("green");
059: * <b>sqlMap.update("updateEmployee", emp2)</b>;
060: * <b>sqlMap.commitTransaction()</b>;
061: * } finally {
062: * <b>sqlMap.endTransaction()</b>;
063: * }
064: * <i><font color="green">
065: * //
066: * // session --these are just examples...not patterns
067: * //
068: * </font></i>
069: * try {
070: * <b>SqlMapSession session = sqlMap.openSession()</b>
071: * <b>session.startTransaction()</b>
072: * Employee emp2 = new Employee();
073: * // ...set emp2 data
074: * Integer generatedKey = (Integer) <b>session.insert ("insertEmployee", emp2)</b>;
075: * emp2.setFavouriteColour ("green");
076: * <b>session.update("updateEmployee", emp2)</b>;
077: * <b>session.commitTransaction()</b>;
078: * } finally {
079: * try {
080: * <b>session.endTransaction()</b>;
081: * } finally {
082: * <b>session.close()</b>;
083: * }
084: * // Generally your session scope would be in a wider context and therefore the
085: * // ugly nested finally block above would not be there. Realize that sessions
086: * // MUST be closed if explicitly opened (via openSession()).
087: * }
088: * <i><font color="green">
089: * //
090: * // batch --these are just examples...not patterns
091: * //
092: * </font></i>
093: * try {
094: * <b>sqlMap.startTransaction()</b>
095: * List list = (Employee) <b>sqlMap.queryForList("getFiredEmployees", null)</b>;
096: * <b>sqlMap.startBatch ()</b>;
097: * for (int i=0, n=list.size(); i < n; i++) {
098: * <b>sqlMap.delete ("deleteEmployee", list.get(i))</b>;
099: * }
100: * <b>sqlMap.executeBatch()</b>;
101: * <b>sqlMap.commitTransaction()</b>;
102: * } finally {
103: * <b>sqlMap.endTransaction()</b>;
104: * }
105: * </pre>
106: *
107: * @see SqlMapClientBuilder
108: * @see SqlMapSession
109: * @see SqlMapExecutor
110: */
111: public interface SqlMapClient extends SqlMapExecutor,
112: SqlMapTransactionManager {
113:
114: /**
115: * Returns a single threaded SqlMapSession implementation for use by
116: * one user. Remember though, that SqlMapClient itself is a thread safe SqlMapSession
117: * implementation, so you can also just work directly with it. If you do get a session
118: * explicitly using this method <b>be sure to close it!</b> You can close a session using
119: * the sqlMapSession.close() method.
120: * <p/>
121: *
122: * @return An SqlMapSession instance.
123: */
124: public SqlMapSession openSession();
125:
126: /**
127: * Returns a single threaded SqlMapSession implementation for use by
128: * one user. Remember though, that SqlMapClient itself is a thread safe SqlMapSession
129: * implementation, so you can also just work directly with it. If you do get a session
130: * explicitly using this method <b>be sure to close it!</b> You can close a session using
131: * the SqlMapSession.close() method.
132: * <p/>
133: * This particular implementation takes a user provided connection as a parameter. This
134: * connection will be used for executing statements, and therefore overrides any
135: * configured datasources. Using this approach allows the developer to easily use an externally
136: * supplied connection for executing statements.
137: * <p/>
138: * <b>Important:</b> Using a user supplied connection basically sidesteps the datasource
139: * so you are responsible for appropriately handling your connection lifecycle (i.e. closing).
140: * Here's a (very) simple example (throws SQLException):
141: * <pre>
142: * try {
143: * Connection connection = dataSource.getConnection();
144: * SqlMapSession session = sqlMap.openSession(connection);
145: * // do work
146: * connection.commit();
147: * } catch (SQLException e) {
148: * try {
149: * if (connection != null) commit.rollback();
150: * } catch (SQLException ignored) {
151: * // generally ignored
152: * }
153: * throw e; // rethrow the exception
154: * } finally {
155: * try {
156: * if (connection != null) connection.close();
157: * } catch (SQLException ignored) {
158: * // generally ignored
159: * }
160: * }
161: * </pre>
162: *
163: * @param conn - the connection to use for the session
164: *
165: * @return An SqlMapSession instance.
166: */
167: public SqlMapSession openSession(Connection conn);
168:
169: /**
170: * TODO : Deprecated and will be removed.
171: *
172: * @return A session (DEPRECATED)
173: * @deprecated Use openSession() instead. THIS METHOD WILL BE REMOVED BEFORE
174: * FINAL RELEASE.
175: */
176: public SqlMapSession getSession();
177:
178: /**
179: * Flushes all data caches.
180: */
181: public void flushDataCache();
182:
183: /**
184: * Flushes the data cache that matches the cache model ID provided.
185: * cacheId should include the namespace, even when
186: * useStatementNamespaces="false".
187: *
188: * @param cacheId The cache model to flush
189: */
190: public void flushDataCache(String cacheId);
191:
192: /**
193: * Returns a generated implementation of a cusom mapper class as specified by the method
194: * parameter. The generated implementation will run mapped statements by matching the method
195: * name to the statement name. The mapped statement elements determine how the statement is
196: * run as per the following:
197: * <ul>
198: * <li><insert> -- insert()
199: * <li><update> -- update()
200: * <li><delete> -- delete()
201: * <li><select> -- queryForObject, queryForList or queryForMap, as determined by signature (see below)
202: * <li><procedure> -- determined by method name (see below)
203: * </ul>
204: *
205: * How select statements are run is determined by the method signature,
206: * as per the following:
207: * <ul>
208: * <li> Object methodName (Object param) -- queryForObject
209: * <li> List methodName (Object param [, int skip, int max | , int pageSize]) -- queryForList
210: * <li> Map methodName (Object param, String keyProp [,valueProp]) -- queryForMap
211: * </ul>
212: *
213: * How stored procedures are run is determined by the method name,
214: * as per the following:
215: * <ul>
216: * <li> insertXxxxx -- insert()
217: * <li> createXxxxx -- insert()
218: * <li> updateXxxxx -- update()
219: * <li> saveXxxxx -- update()
220: * <li> deleteXxxxx -- delete()
221: * <li> removeXxxxx -- delete()
222: * <li> selectXxxxx -- queryForXxxxxx() determined by method signature as above
223: * <li> queryXxxxx -- queryForXxxxxx() determined by method signature as above
224: * <li> fetchXxxxx -- queryForXxxxxx() determined by method signature as above
225: * <li> getXxxxx -- queryForXxxxxx() determined by method signature as above
226: * </ul>
227: *
228: * @param iface The interface that contains methods representing the mapped statements contained.
229: * @return An instance of iface that can be used to call mapped statements directly in a typesafe
230: * manner.
231: */
232: //public Object getMapper(Class iface);
233: }
|