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