View Javadoc

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;
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       * Torque Methods, accessible from the Component
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 }