Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

Source code: com/ibatis/dao/client/DaoManager.java


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 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 iface, String 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 }