View Javadoc

1   // 
2   // Copyright (c) 2003, Caltha - Gajda, Krzewski, Mach, Potempski Sp.J. 
3   // All rights reserved. 
4   // 
5   // Redistribution and use in source and binary forms, with or without modification,  
6   // are permitted provided that the following conditions are met: 
7   //  
8   // * Redistributions of source code must retain the above copyright notice,  
9   //	 this list of conditions and the following disclaimer. 
10  // * Redistributions in binary form must reproduce the above copyright notice,  
11  //	 this list of conditions and the following disclaimer in the documentation  
12  //	 and/or other materials provided with the distribution. 
13  // * Neither the name of the Caltha - Gajda, Krzewski, Mach, Potempski Sp.J.  
14  //	 nor the names of its contributors may be used to endorse or promote products  
15  //	 derived from this software without specific prior written permission. 
16  // 
17  // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"  
18  // AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED  
19  // WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
20  // IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,  
21  // INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,  
22  // BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
23  // OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,  
24  // WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)  
25  // ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE  
26  // POSSIBILITY OF SUCH DAMAGE. 
27  // 
28  package org.objectledge.database;
29  
30  import java.sql.Connection;
31  import java.sql.SQLException;
32  
33  /***
34   * A convenience wrapper around database related components.
35   * 
36   * <p>Use this component to reduce the number of required constructor parameters in your database
37   * dependant components, and make sure that they'll access the right data source, if you are using
38   * the ThreadDataSource decorator.</p>
39   * 
40   * @author <a href="mailto:rafal@caltha.pl">Rafal Krzewski</a>
41   * @version $Id: Database.java,v 1.7 2005/04/04 11:38:08 rafal Exp $
42   */
43  public interface Database
44  {
45      /***
46       * Returns a database Connection produced by the DataSource.
47       * 
48       * @return a database Connection.
49       * @throws SQLException if the conneciton could not be obtained.
50       */
51      public abstract Connection getConnection() throws SQLException;
52  
53      /***
54       * Returns a database Connection produced by the DataSource.
55       * 
56       * @param user the user to connect as.
57       * @param password the user's password.
58       * @return a database Connection.
59       * @throws SQLException if the conneciton could not be obtained.
60       */
61      public abstract Connection getConnection(String user, String password) throws SQLException;
62  
63      /***
64       * Get the next row identifier for the table.
65       * 
66       * @param table the table name.
67       * @return the identifier.
68       * @throws SQLException if the id could not be generated.
69       */
70      public abstract long getNextId(String table) throws SQLException;
71  
72      /***
73       * Sets the transaction timeout for the current transaction.
74       * 
75       * @param seconds the requested length of timeout period in seconds.
76       * @throws SQLException if the timeout could not be set.
77       */
78      public abstract void setTransactionTimeout(int seconds) throws SQLException; 
79      
80      /***
81       * Begin the transaction, if there is none active.
82       * 
83       * @return <code>true</code> if the requestor become the controler.
84       * @throws SQLException if the operation fails.
85       */
86      public abstract boolean beginTransaction() throws SQLException;
87  
88      /***
89       * Commit the transaction, if the caller is the controller.
90       * 
91       * @param controller <code>true</code> if the caller is the controler.
92       * @throws SQLException if the commit fails.
93       */
94      public abstract void commitTransaction(boolean controller) throws SQLException;
95  
96      /***
97       * Rollback the transaction, if the caller is the controller.
98       * 
99       * @param controller <code>true</code> if the caller is the controler.
100      * @throws SQLException if the rollback fails.
101      */
102     public abstract void rollbackTransaction(boolean controller) throws SQLException;
103 }