001: package org.apache.torque.avalon;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.sql.Connection;
023: import java.util.Map;
024:
025: import org.apache.avalon.framework.component.Component;
026: import org.apache.torque.Database;
027: import org.apache.torque.TorqueException;
028: import org.apache.torque.adapter.DB;
029: import org.apache.torque.manager.AbstractBaseManager;
030: import org.apache.torque.map.DatabaseMap;
031: import org.apache.torque.map.MapBuilder;
032:
033: /**
034: * Avalon role interface for Torque.
035: *
036: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
037: * @author <a href="mailto:tv@apache.org">Thomas Vandahl</a>
038: * @version $Id: Torque.java 493449 2007-01-06 11:46:50Z tv $
039: */
040: public interface Torque extends Component {
041: /**
042: * The avalon role.
043: */
044: String ROLE = Torque.class.getName();
045:
046: /*
047: * ========================================================================
048: *
049: * Torque Methods, accessible from the Component
050: *
051: * ========================================================================
052: */
053:
054: /**
055: * Determine whether Torque has already been initialized.
056: *
057: * @return true if Torque is already initialized
058: */
059: boolean isInit();
060:
061: /**
062: * Get the configuration for this component.
063: *
064: * @return the Configuration
065: */
066: org.apache.commons.configuration.Configuration getConfiguration();
067:
068: /**
069: * This method returns a Manager for the given name.
070: *
071: * @param name name of the manager
072: * @return a Manager
073: */
074: AbstractBaseManager getManager(String name);
075:
076: /**
077: * This methods returns either the Manager from the configuration file,
078: * or the default one provided by the generated code.
079: *
080: * @param name name of the manager
081: * @param defaultClassName the class to use if name has not been configured
082: * @return a Manager
083: */
084: AbstractBaseManager getManager(String name, String defaultClassName);
085:
086: /**
087: * Returns the default database map information.
088: *
089: * @return A DatabaseMap.
090: * @throws TorqueException Any exceptions caught during processing will be
091: * rethrown wrapped into a TorqueException.
092: */
093: DatabaseMap getDatabaseMap() throws TorqueException;
094:
095: /**
096: * Returns the database map information. Name relates to the name
097: * of the connection pool to associate with the map.
098: *
099: * @param name The name of the database corresponding to the
100: * <code>DatabaseMap</code> to retrieve.
101: * @return The named <code>DatabaseMap</code>.
102: * @throws TorqueException Any exceptions caught during processing will be
103: * rethrown wrapped into a TorqueException.
104: */
105: DatabaseMap getDatabaseMap(String name) throws TorqueException;
106:
107: /**
108: * Register a MapBuilder
109: *
110: * @param className the MapBuilder
111: */
112: void registerMapBuilder(String className);
113:
114: /**
115: * Register a MapBuilder
116: *
117: * @param builder the instance of the MapBuilder
118: *
119: */
120: void registerMapBuilder(MapBuilder builder);
121:
122: /**
123: * Get a MapBuilder
124: *
125: * @param className of the MapBuilder
126: * @return A MapBuilder, not null
127: * @throws TorqueException if the Map Builder cannot be instantiated
128: *
129: */
130: MapBuilder getMapBuilder(String className) throws TorqueException;
131:
132: /**
133: * This method returns a Connection from the default pool.
134: *
135: * @return The requested connection.
136: * @throws TorqueException Any exceptions caught during processing will be
137: * rethrown wrapped into a TorqueException.
138: */
139: Connection getConnection() throws TorqueException;
140:
141: /**
142: *
143: * @param name The database name.
144: * @return a database connection
145: * @throws TorqueException Any exceptions caught during processing will be
146: * rethrown wrapped into a TorqueException.
147: */
148: Connection getConnection(String name) throws TorqueException;
149:
150: /**
151: * This method returns a Connecton using the given parameters.
152: * You should only use this method if you need user based access to the
153: * database!
154: *
155: * @param name The database name.
156: * @param username The name of the database user.
157: * @param password The password of the database user.
158: * @return A Connection.
159: * @throws TorqueException Any exceptions caught during processing will be
160: * rethrown wrapped into a TorqueException.
161: */
162: Connection getConnection(String name, String username,
163: String password) throws TorqueException;
164:
165: /**
166: * Returns database adapter for a specific connection pool.
167: *
168: * @param name A pool name.
169: * @return The corresponding database adapter.
170: * @throws TorqueException Any exceptions caught during processing will be
171: * rethrown wrapped into a TorqueException.
172: */
173: DB getDB(String name) throws TorqueException;
174:
175: /**
176: * Returns the name of the default database.
177: *
178: * @return name of the default DB
179: */
180: String getDefaultDB();
181:
182: /**
183: * Closes a connection.
184: *
185: * @param con A Connection to close.
186: */
187: void closeConnection(Connection con);
188:
189: /**
190: * Sets the current schema for a database connection
191: *
192: * @param name The database name.
193: * @param schema The current schema name
194: * @throws TorqueException Any exceptions caught during processing will be
195: * rethrown wrapped into a TorqueException.
196: */
197: void setSchema(String name, String schema) throws TorqueException;
198:
199: /**
200: * This method returns the current schema for a database connection
201: *
202: * @param name The database name.
203: * @return The current schema name. Null means, no schema has been set.
204: * @throws TorqueException Any exceptions caught during processing will be
205: * rethrown wrapped into a TorqueException.
206: */
207: String getSchema(String name) throws TorqueException;
208:
209: /**
210: * Returns the database for the key <code>databaseName</code>.
211: *
212: * @param databaseName the key to get the database for.
213: * @return the database for the specified key, or null if the database
214: * does not exist.
215: * @throws TorqueException if Torque is not yet initialized.
216: */
217: Database getDatabase(String databaseName) throws TorqueException;
218:
219: /**
220: * Returns a Map containing all Databases registered to Torque.
221: * The key of the Map is the name of the database, and the value is the
222: * database instance. <br/>
223: * Note that in the very special case where a new database which
224: * is not configured in Torque's configuration gets known to Torque
225: * at a later time, the returned map may change, and there is no way to
226: * protect you against this.
227: *
228: * @return a Map containing all Databases known to Torque, never null.
229: * @throws TorqueException if Torque is not yet initialized.
230: */
231: Map getDatabases() throws TorqueException;
232:
233: /**
234: * Returns the database for the key <code>databaseName</code>.
235: * If no database is associated to the specified key,
236: * a new database is created, mapped to the specified key, and returned.
237: *
238: * @param databaseName the key to get the database for.
239: * @return the database associated with specified key, or the newly created
240: * database, never null.
241: */
242: Database getOrCreateDatabase(String databaseName);
243: }
|