KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > torque > avalon > Torque


1 package org.apache.torque.avalon;
2
3 /*
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  */

21
22 import java.sql.Connection JavaDoc;
23 import java.util.Map JavaDoc;
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 JavaDoc ROLE = Torque.class.getName();
47
48     /*
49      * ========================================================================
50      *
51      * Torque Methods, accessible from the Component
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 JavaDoc 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 JavaDoc name, String JavaDoc 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 JavaDoc name) throws TorqueException;
108
109     /**
110      * Register a MapBuilder
111      *
112      * @param className the MapBuilder
113      */

114     void registerMapBuilder(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc getConnection(String JavaDoc 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 JavaDoc getConnection(String JavaDoc name, String JavaDoc username, String JavaDoc 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 JavaDoc name) throws TorqueException;
177
178     /**
179      * Returns the name of the default database.
180      *
181      * @return name of the default DB
182      */

183     String JavaDoc getDefaultDB();
184
185     /**
186      * Closes a connection.
187      *
188      * @param con A Connection to close.
189      */

190     void closeConnection(Connection JavaDoc 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 JavaDoc name, String JavaDoc 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 JavaDoc getSchema(String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc databaseName);
246 }
247
Popular Tags