1 package org.apache.torque.avalon;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22 import java.sql.Connection;
23 import java.util.Map;
24
25 import org.apache.avalon.framework.component.Component;
26 import org.apache.torque.Database;
27 import org.apache.torque.TorqueException;
28 import org.apache.torque.adapter.DB;
29 import org.apache.torque.manager.AbstractBaseManager;
30 import org.apache.torque.map.DatabaseMap;
31
32 /***
33 * Avalon role interface for Torque.
34 *
35 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
36 * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
37 * @version $Id: Torque.java 476550 2006-11-18 16:08:37Z tfischer $
38 */
39 public interface Torque
40 extends Component
41 {
42 /***
43 * The avalon role.
44 */
45 String ROLE = Torque.class.getName();
46
47
48
49
50
51
52
53
54
55 /***
56 * Determine whether Torque has already been initialized.
57 *
58 * @return true if Torque is already initialized
59 */
60 boolean isInit();
61
62 /***
63 * Get the configuration for this component.
64 *
65 * @return the Configuration
66 */
67 org.apache.commons.configuration.Configuration getConfiguration();
68
69 /***
70 * This method returns a Manager for the given name.
71 *
72 * @param name name of the manager
73 * @return a Manager
74 */
75 AbstractBaseManager getManager(String name);
76
77 /***
78 * This methods returns either the Manager from the configuration file,
79 * or the default one provided by the generated code.
80 *
81 * @param name name of the manager
82 * @param defaultClassName the class to use if name has not been configured
83 * @return a Manager
84 */
85 AbstractBaseManager getManager(String name, String defaultClassName);
86
87 /***
88 * Returns the default database map information.
89 *
90 * @return A DatabaseMap.
91 * @throws TorqueException Any exceptions caught during processing will be
92 * rethrown wrapped into a TorqueException.
93 */
94 DatabaseMap getDatabaseMap() throws TorqueException;
95
96 /***
97 * Returns the database map information. Name relates to the name
98 * of the connection pool to associate with the map.
99 *
100 * @param name The name of the database corresponding to the
101 * <code>DatabaseMap</code> to retrieve.
102 * @return The named <code>DatabaseMap</code>.
103 * @throws TorqueException Any exceptions caught during processing will be
104 * rethrown wrapped into a TorqueException.
105 */
106 DatabaseMap getDatabaseMap(String name) throws TorqueException;
107
108 /***
109 * Register a MapBuilder
110 *
111 * @param className the MapBuilder
112 */
113 void registerMapBuilder(String className);
114
115 /***
116 * This method returns a Connection from the default pool.
117 *
118 * @return The requested connection.
119 * @throws TorqueException Any exceptions caught during processing will be
120 * rethrown wrapped into a TorqueException.
121 */
122 Connection getConnection() throws TorqueException;
123
124 /***
125 *
126 * @param name The database name.
127 * @return a database connection
128 * @throws TorqueException Any exceptions caught during processing will be
129 * rethrown wrapped into a TorqueException.
130 */
131 Connection getConnection(String name) throws TorqueException;
132
133 /***
134 * This method returns a Connecton using the given parameters.
135 * You should only use this method if you need user based access to the
136 * database!
137 *
138 * @param name The database name.
139 * @param username The name of the database user.
140 * @param password The password of the database user.
141 * @return A Connection.
142 * @throws TorqueException Any exceptions caught during processing will be
143 * rethrown wrapped into a TorqueException.
144 */
145 Connection getConnection(String name, String username, String password)
146 throws TorqueException;
147
148 /***
149 * Returns database adapter for a specific connection pool.
150 *
151 * @param name A pool name.
152 * @return The corresponding database adapter.
153 * @throws TorqueException Any exceptions caught during processing will be
154 * rethrown wrapped into a TorqueException.
155 */
156 DB getDB(String name) throws TorqueException;
157
158 /***
159 * Returns the name of the default database.
160 *
161 * @return name of the default DB
162 */
163 String getDefaultDB();
164
165 /***
166 * Closes a connection.
167 *
168 * @param con A Connection to close.
169 */
170 void closeConnection(Connection con);
171
172 /***
173 * Sets the current schema for a database connection
174 *
175 * @param name The database name.
176 * @param schema The current schema name
177 * @throws TorqueException Any exceptions caught during processing will be
178 * rethrown wrapped into a TorqueException.
179 */
180 void setSchema(String name, String schema) throws TorqueException;
181
182 /***
183 * This method returns the current schema for a database connection
184 *
185 * @param name The database name.
186 * @return The current schema name. Null means, no schema has been set.
187 * @throws TorqueException Any exceptions caught during processing will be
188 * rethrown wrapped into a TorqueException.
189 */
190 String getSchema(String name) throws TorqueException;
191
192 /***
193 * Returns the database for the key <code>databaseName</code>.
194 *
195 * @param databaseName the key to get the database for.
196 * @return the database for the specified key, or null if the database
197 * does not exist.
198 * @throws TorqueException if Torque is not yet initialized.
199 */
200 Database getDatabase(String databaseName) throws TorqueException;
201
202 /***
203 * Returns a Map containing all Databases registered to Torque.
204 * The key of the Map is the name of the database, and the value is the
205 * database instance. <br/>
206 * Note that in the very special case where a new database which
207 * is not configured in Torque's configuration gets known to Torque
208 * at a later time, the returned map may change, and there is no way to
209 * protect you against this.
210 *
211 * @return a Map containing all Databases known to Torque, never null.
212 * @throws TorqueException if Torque is not yet initialized.
213 */
214 Map getDatabases() throws TorqueException;
215
216 /***
217 * Returns the database for the key <code>databaseName</code>.
218 * If no database is associated to the specified key,
219 * a new database is created, mapped to the specified key, and returned.
220 *
221 * @param databaseName the key to get the database for.
222 * @return the database associated with specified key, or the newly created
223 * database, never null.
224 */
225 Database getOrCreateDatabase(String databaseName);
226 }