KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ibatis > sqlmap > client > SqlMapClient


1 /*
2  * Copyright 2004 Clinton Begin
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package com.ibatis.sqlmap.client;
17
18 import java.sql.Connection JavaDoc;
19
20 /**
21  * A thread safe client for working with your SQL Maps (Start Here). This interface inherits transaction control
22  * and execution methods from the SqlMapTransactionManager and SqlMapExecutor interfaces.
23  * <p/>
24  * The SqlMapClient is the central class for working with SQL Maps. This class will allow you
25  * to run mapped statements (select, insert, update, delete etc.), and also demarcate
26  * transactions and work with batches. Once you have an SqlMapClient instance, everything
27  * you need to work with SQL Maps is easily available.
28  * <p/>
29  * The SqlMapClient can either
30  * be worked with directly as a multi-threaded client (internal session management), or you can get a single threaded
31  * session and work with that. There may be a slight performance increase if you explicitly
32  * get a session (using the openSession() method), as it saves the SqlMapClient from having
33  * to manage threads contexts. But for most cases it won't make much of a difference, so
34  * choose whichever paradigm suits your needs or preferences.
35  * <p/>
36  * An SqlMapClient instance can be safely made <i>static</i> or applied as a <i>Singleton</i>.
37  * Generally it's a good idea to make a simple configuration class that will configure the
38  * instance (using SqlMapClientBuilder) and provide access to it.
39  * <p/>
40  * <b>The following example will demonstrate the use of SqlMapClient.</b>
41  * <pre>
42  * <i><font color="green">
43  * //
44  * // autocommit simple query --these are just examples...not patterns
45  * //
46  * </font></i>
47  * Employee emp = (Employee) <b>sqlMap.queryForObject("getEmployee", new Integer(1))</b>;
48  * <i><font color="green">
49  * //
50  * // transaction --these are just examples...not patterns
51  * //
52  * </font></i>
53  * try {
54  * <b>sqlMap.startTransaction()</b>
55  * Employee emp2 = new Employee();
56  * // ...set emp2 data
57  * Integer generatedKey = (Integer) <b>sqlMap.insert ("insertEmployee", emp2)</b>;
58  * emp2.setFavouriteColour ("green");
59  * <b>sqlMap.update("updateEmployee", emp2)</b>;
60  * <b>sqlMap.commitTransaction()</b>;
61  * } finally {
62  * <b>sqlMap.endTransaction()</b>;
63  * }
64  * <i><font color="green">
65  * //
66  * // session --these are just examples...not patterns
67  * //
68  * </font></i>
69  * try {
70  * <b>SqlMapSession session = sqlMap.openSession()</b>
71  * <b>session.startTransaction()</b>
72  * Employee emp2 = new Employee();
73  * // ...set emp2 data
74  * Integer generatedKey = (Integer) <b>session.insert ("insertEmployee", emp2)</b>;
75  * emp2.setFavouriteColour ("green");
76  * <b>session.update("updateEmployee", emp2)</b>;
77  * <b>session.commitTransaction()</b>;
78  * } finally {
79  * try {
80  * <b>session.endTransaction()</b>;
81  * } finally {
82  * <b>session.close()</b>;
83  * }
84  * // Generally your session scope would be in a wider context and therefore the
85  * // ugly nested finally block above would not be there. Realize that sessions
86  * // MUST be closed if explicitly opened (via openSession()).
87  * }
88  * <i><font color="green">
89  * //
90  * // batch --these are just examples...not patterns
91  * //
92  * </font></i>
93  * try {
94  * <b>sqlMap.startTransaction()</b>
95  * List list = (Employee) <b>sqlMap.queryForList("getFiredEmployees", null)</b>;
96  * <b>sqlMap.startBatch ()</b>;
97  * for (int i=0, n=list.size(); i < n; i++) {
98  * <b>sqlMap.delete ("deleteEmployee", list.get(i))</b>;
99  * }
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, SqlMapTransactionManager {
112
113   /**
114    * Returns a single threaded SqlMapSession implementation for use by
115    * one user. Remember though, that SqlMapClient itself is a thread safe SqlMapSession
116    * implementation, so you can also just work directly with it. If you do get a session
117    * explicitly using this method <b>be sure to close it!</b> You can close a session using
118    * the sqlMapSession.close() method.
119    * <p/>
120    *
121    * @return An SqlMapSession instance.
122    */
123   public SqlMapSession openSession();
124
125   /**
126    * Returns a single threaded SqlMapSession implementation for use by
127    * one user. Remember though, that SqlMapClient itself is a thread safe SqlMapSession
128    * implementation, so you can also just work directly with it. If you do get a session
129    * explicitly using this method <b>be sure to close it!</b> You can close a session using
130    * the SqlMapSession.close() method.
131    * <p/>
132    * This particular implementation takes a user provided connection as a parameter. This
133    * connection will be used for executing statements, and therefore overrides any
134    * configured datasources. Using this approach allows the developer to easily use an externally
135    * supplied connection for executing statements.
136    * <p/>
137    * <b>Important:</b> Using a user supplied connection basically sidesteps the datasource
138    * so you are responsible for appropriately handling your connection lifecycle (i.e. closing).
139    * Here's a (very) simple example (throws SQLException):
140    * <pre>
141    * try {
142    * Connection connection = dataSource.getConnection();
143    * SqlMapSession session = sqlMap.openSession(connection);
144    * // do work
145    * connection.commit();
146    * } catch (SQLException e) {
147    * try {
148    * if (connection != null) commit.rollback();
149    * } catch (SQLException ignored) {
150    * // generally ignored
151    * }
152    * throw e; // rethrow the exception
153    * } finally {
154    * try {
155    * if (connection != null) connection.close();
156    * } catch (SQLException ignored) {
157    * // generally ignored
158    * }
159    * }
160    * </pre>
161    *
162    * @param conn - the connection to use for the session
163    *
164    * @return An SqlMapSession instance.
165    */
166   public SqlMapSession openSession(Connection JavaDoc conn);
167
168   /**
169    * TODO : Deprecated and will be removed.
170    *
171    * @return A session (DEPRECATED)
172    * @deprecated Use openSession() instead. THIS METHOD WILL BE REMOVED BEFORE
173    * FINAL RELEASE.
174    */
175   public SqlMapSession getSession();
176
177   /**
178    * Flushes all data caches.
179    */
180   public void flushDataCache();
181
182   /**
183    * Flushes the data cache that matches the cache model ID provided.
184    *
185    * @param cacheId The cache model to flush
186    */
187   public void flushDataCache(String JavaDoc cacheId);
188
189   /**
190    * Returns a generated implementation of a cusom mapper class as specified by the method
191    * parameter. The generated implementation will run mapped statements by matching the method
192    * name to the statement name. The mapped statement elements determine how the statement is
193    * run as per the following:
194    * <ul>
195    * <li>&lt;insert&gt; -- insert()
196    * <li>&lt;update&gt; -- update()
197    * <li>&lt;delete&gt; -- delete()
198    * <li>&lt;select&gt; -- queryForObject, queryForList or queryForMap, as determined by signature (see below)
199    * <li>&lt;procedure&gt; -- determined by method name (see below)
200    * </ul>
201    *
202    * How select statements are run is determined by the method signature,
203    * as per the following:
204    * <ul>
205    * <li> Object methodName (Object param) -- queryForObject
206    * <li> List methodName (Object param [, int skip, int max | , int pageSize]) -- queryForList
207    * <li> Map methodName (Object param, String keyProp [,valueProp]) -- queryForMap
208    * </ul>
209    *
210    * How stored procedures are run is determined by the method name,
211    * as per the following:
212    * <ul>
213    * <li> insertXxxxx -- insert()
214    * <li> createXxxxx -- insert()
215    * <li> updateXxxxx -- update()
216    * <li> saveXxxxx -- update()
217    * <li> deleteXxxxx -- delete()
218    * <li> removeXxxxx -- delete()
219    * <li> selectXxxxx -- queryForXxxxxx() determined by method signature as above
220    * <li> queryXxxxx -- queryForXxxxxx() determined by method signature as above
221    * <li> fetchXxxxx -- queryForXxxxxx() determined by method signature as above
222    * <li> getXxxxx -- queryForXxxxxx() determined by method signature as above
223    * </ul>
224    *
225    * @param iface The interface that contains methods representing the mapped statements contained.
226    * @return An instance of iface that can be used to call mapped statements directly in a typesafe
227    * manner.
228    */
229   //public Object getMapper (Class iface);
230
231 }
232
Popular Tags