KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ibatis > dao > client > DaoManager


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.dao.client;
17
18 /**
19  * This interface describes the DaoManager interface. It provides
20  * access to all DAOs it manages and also allows transactions
21  * to be committed and ended (possibly rolled back).
22  * <p/>
23  * DAO instances returned from the DAO Manager are proxied such that transactions
24  * can be automatically started, committed and ended (or rolled back). This is
25  * a similar semantic to the JDBC autocommit, but much more powerful.
26  * <p/>
27  * Alternatively, tranasctions can be controlled programmatically, allowing you to
28  * demarcate wider scope transactions as needed.
29  * <p/>
30  * Either way, transactions will only be started for those contexts that require them.
31  * No unneccessary transactions will be started. When commitTransaction() and
32  * endTransaction() are called, all transactions which have been started in each
33  * configured context will be committed and ended respectively. endTransaction() will
34  * automatically rollback any transactions that have not been committed.
35  * <p/>
36  * Here's a couple of examples:
37  * <p/>
38  * <p/>
39  * <p/>
40  * <pre>
41  * <p/>
42  * // **************************************************************
43  * // AUTO COMMIT TRANASACTION SEMANTIC
44  * // **************************************************************
45  * <p/>
46  * DaoManager daoManager = DaoManagerBuilder.buildDaoManager(reader);
47  * PersonDao personDao = daoManager.getDao(PersonDao.class);
48  * // A transaction will be automatically started committed and ended
49  * // by calling any method on the DAO. The following insert and update
50  * // are TWO separate transactions.
51  * personDao.insertPerson (person); // Starts transaction
52  * person.setLastName("Begin");
53  * personDao.updatePerson (person); // Starts a new transaction
54  * <p/>
55  * // **************************************************************
56  * // PROGRAMMATIC DEMARCATION OF TRANSACTION SCOPE
57  * // **************************************************************
58  * <p/>
59  * DaoManager daoManager = DaoManagerBuilder.buildDaoManager(reader);
60  * PersonDao personDao = daoManager.getDao(PersonDao.class);
61  * try {
62  * // Calling startTransaction() tells the DAO Manager that you
63  * // are going to be managing the transactions manually.
64  * daoManager.startTransaction();
65  * personDao.insertPerson (person);
66  * person.setLastName("Begin");
67  * personDao.updatePerson (person);
68  * // Commit all active transactions in all contexts
69  * daoManager.commitTransaction();
70  * } finally {
71  * // End all active transactions in all contexts and rollback if necessary.
72  * daoManager.endTransaction();
73  * }
74  * </pre>
75  * <p/>
76  * <b>Important: </b> In order to achieve global transaction behaviour
77  * (i.e. two phase commit), you'll need to configure all of your contexts
78  * using JTA, JNDI and XA compliant DataSources.
79  * <p/>
80  */
81 public interface DaoManager {
82
83   /**
84    * Gets a Dao instance for the requested interface type.
85    *
86    * @param type The interface or generic type for which an implementation
87    * should be returned.
88    * @return The Dao implementation instance.
89    */
90   public Dao getDao(Class JavaDoc type);
91
92   /**
93    * Gets a Dao instance for the requested interface type registered
94    * under the context with the specified id.
95    *
96    * @param iface The interface or generic type for which an implementation
97    * should be returned.
98    * @param contextId The ID of the context under which to find the DAO
99    * implementation (use for multiple interface defs).
100    * @return The Dao implementation instance.
101    */
102   public Dao getDao(Class JavaDoc iface, String JavaDoc contextId);
103
104   /**
105    * Gets the transaction that the provided Dao is currently working
106    * under. If there is no current transaction in scope, one will
107    * be started.
108    *
109    * @param dao The Dao to find a transaction for.
110    * @return The Transaction under which the Dao provided is working
111    * under.
112    */
113   public DaoTransaction getTransaction(Dao dao);
114
115   /**
116    * Starts a transaction scope managed by this DaoManager.
117    * If this method isn't called, then all DAO methods use
118    * "autocommit" semantics.
119    */
120   public void startTransaction();
121
122   /**
123    * Commits all transactions currently started for all DAO contexts
124    * managed by this DaoManager.
125    */
126   public void commitTransaction();
127
128   /**
129    * Ends all transactions currently started for all DAO contexts
130    * managed by this DaoManager. If any transactions have not been
131    * successfully committed, then those remaining will be rolled back.
132    */
133   public void endTransaction();
134
135 }
136
Popular Tags