CVS: fulcrum/db/src/java/org/apache/fulcrum/db DatabaseService.java,1.1,1.2
[email protected] Mon, 5 May 2003 16:16:37 -0500
| Newsgroups | gmane.comp.java.plexus.devel |
|---|---|
| Message-ID | <[email protected]> |
Update of /cvsroot/plexus/fulcrum/db/src/java/org/apache/fulcrum/db In directory eng.werken.com:/tmp/cvs-serv5369/db/src/java/org/apache/fulcrum/db Modified Files: DatabaseService.java Log Message: Index: DatabaseService.java =================================================================== RCS file: /cvsroot/plexus/fulcrum/db/src/java/org/apache/fulcrum/db/DatabaseService.java,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- DatabaseService.java 29 Mar 2003 15:55:32 -0000 1.1 +++ DatabaseService.java 5 May 2003 21:16:33 -0000 1.2 @@ -1,190 +1,190 @@ -package org.apache.fulcrum.db; - -/* ==================================================================== - * The Apache Software License, Version 1.1 - * - * Copyright (c) 2001 The Apache Software Foundation. All rights - * reserved. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in - * the documentation and/or other materials provided with the - * distribution. - * - * 3. The end-user documentation included with the redistribution, - * if any, must include the following acknowledgment: - * "This product includes software developed by the - * Apache Software Foundation (http://www.apache.org/)." - * Alternately, this acknowledgment may appear in the software itself, - * if and wherever such third-party acknowledgments normally appear. - * - * 4. The names "Apache" and "Apache Software Foundation" and - * "Apache Turbine" must not be used to endorse or promote products - * derived from this software without prior written permission. For - * written permission, please contact [email protected]. - * - * 5. Products derived from this software may not be called "Apache", - * "Apache Turbine", nor may "Apache" appear in their name, without - * prior written permission of the Apache Software Foundation. - * - * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED - * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES - * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR - * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND - * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, - * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT - * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * ==================================================================== - * - * This software consists of voluntary contributions made by many - * individuals on behalf of the Apache Software Foundation. For more - * information on the Apache Software Foundation, please see - * <http://www.apache.org/>. - */ - -import java.sql.Connection; -import org.apache.torque.map.DatabaseMap; -import org.apache.torque.adapter.DB; - -/** - * This service provides database connection pooling and manages - * {@link org.apache.torque.map.DatabaseMap} objects used throughout - * a Turbine application. - * It provides single point of access to a pool of maps, assuring that every - * client will access the same instance of DatabaseMap object. - * - * The service can manage a number of connection pools. Each pool is related - * to a specific database, identified by it's driver class name, url, username - * and password. The pools may be defined in TurbineResources.properties - * file, or created at runtime using - * {@link #registerPool(String,String,String,String,String)} method. - * - * <p> You can use {@link #getConnection(String)} to acquire a - * {@link java.sql.Connection} object, which in - * turn can be used to create <code>java.sql.Statement</code> objects. - * - * <p>When you are done using the <code>Connection</code> you <strong>must</strong> - * return it to the pool using {@link #releaseConnection(Connection)} method. - * This method call is often placed in <code>finally</code> clause of a <code>try / - * catch</code> statement, to ensure that the connection is always returned - * to the pool.<br> - * - * @author <a href="mailto:[email protected]">Rafal Krzewski</a> - * @version $Id$ - * @deprecated you should use org.apache.torque.Torque - */ -public interface DatabaseService -{ - public static final String SERVICE_NAME = "DatabaseService"; - - /** - * Returns the default database map information. - * - * @return A DatabaseMap. - * @throws Exception Any exceptions caught during procssing will be - * rethrown wrapped into a Exception. - */ - public DatabaseMap getDatabaseMap() - throws Exception; - - /** - * Returns the database map information. Name relates to the name - * of the connection pool to associate with the map. - * - * @param name The name of the <code>DatabaseMap</code> to - * retrieve. - * @return The named <code>DatabaseMap</code>. - * @throws Exception Any exceptions caught during procssing will be - * rethrown wrapped into a Exception. - */ - public DatabaseMap getDatabaseMap(String name) - throws Exception; - - /** - * This method returns a Connection from the default pool. - * - * @return The requested connection. - * @throws Exception Any exceptions caught during processing will be - * rethrown wrapped into a Exception. - */ - public Connection getConnection() - throws Exception; - - /** - * This method returns a Connection from the pool with the - * specified name. The pool must either have been registered - * with the {@link #registerPool(String,String,String,String,String)} - * method, or be specified in the property file using the - * following syntax: - * - * <pre> - * database.[name].driver - * database.[name].url - * database.[name].username - * database.[name].password - * </pre> - * - * @param name The name of the pool to get a connection from. - * @return The requested connection. - * @throws Exception Any exceptions caught during processing will be - * rethrown wrapped into a Exception. - */ - public Connection getConnection(String name) - throws Exception; - - /** - * Release a connection back to the database pool. - * - * @throws Exception Any exceptions caught during processing will be - * rethrown wrapped into a Exception. - * @exception Exception A generic exception. - */ - public void releaseConnection(Connection dbconn) - throws Exception; - - - /** - * Returns the database adapter for the default connection pool. - * - * @return The database adapter. - * @throws Exception Any exceptions caught during processing will be - * rethrown wrapped into a Exception. - */ - public DB getDB() - throws Exception; - - /** - * Returns database adapter for a specific connection pool. - * - * @param name A pool name. - * @return The corresponding database adapter. - * @throws Exception Any exceptions caught during processing will be - * rethrown wrapped into a Exception. - */ - public DB getDB(String name) - throws Exception; - - - public String getDefaultDB(); - - /** - * This method is gone in Torque HEAD as it is a duplicate - * for getDefaultDB, but will stay here marked as deprecated - * for a little while. - * - * @deprecated - */ - public String getDefaultMap(); -} +package org.apache.fulcrum.db; + +/* ==================================================================== + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2001 The Apache Software Foundation. All rights + * reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, + * if any, must include the following acknowledgment: + * "This product includes software developed by the + * Apache Software Foundation (http://www.apache.org/)." + * Alternately, this acknowledgment may appear in the software itself, + * if and wherever such third-party acknowledgments normally appear. + * + * 4. The names "Apache" and "Apache Software Foundation" and + * "Apache Turbine" must not be used to endorse or promote products + * derived from this software without prior written permission. For + * written permission, please contact [email protected]. + * + * 5. Products derived from this software may not be called "Apache", + * "Apache Turbine", nor may "Apache" appear in their name, without + * prior written permission of the Apache Software Foundation. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR + * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + * + * This software consists of voluntary contributions made by many + * individuals on behalf of the Apache Software Foundation. For more + * information on the Apache Software Foundation, please see + * <http://www.apache.org/>. + */ + +import java.sql.Connection; +import org.apache.torque.map.DatabaseMap; +import org.apache.torque.adapter.DB; + +/** + * This service provides database connection pooling and manages + * {@link org.apache.torque.map.DatabaseMap} objects used throughout + * a Turbine application. + * It provides single point of access to a pool of maps, assuring that every + * client will access the same instance of DatabaseMap object. + * + * The service can manage a number of connection pools. Each pool is related + * to a specific database, identified by it's driver class name, url, username + * and password. The pools may be defined in TurbineResources.properties + * file, or created at runtime using + * {@link #registerPool(String,String,String,String,String)} method. + * + * <p> You can use {@link #getConnection(String)} to acquire a + * {@link java.sql.Connection} object, which in + * turn can be used to create <code>java.sql.Statement</code> objects. + * + * <p>When you are done using the <code>Connection</code> you <strong>must</strong> + * return it to the pool using {@link #releaseConnection(Connection)} method. + * This method call is often placed in <code>finally</code> clause of a <code>try / + * catch</code> statement, to ensure that the connection is always returned + * to the pool.<br> + * + * @author <a href="mailto:[email protected]">Rafal Krzewski</a> + * @version $Id$ + * @deprecated you should use org.apache.torque.Torque + */ +public interface DatabaseService +{ + public static final String ROLE = DatabaseService.class.getName(); + + /** + * Returns the default database map information. + * + * @return A DatabaseMap. + * @throws Exception Any exceptions caught during procssing will be + * rethrown wrapped into a Exception. + */ + public DatabaseMap getDatabaseMap() + throws Exception; + + /** + * Returns the database map information. Name relates to the name + * of the connection pool to associate with the map. + * + * @param name The name of the <code>DatabaseMap</code> to + * retrieve. + * @return The named <code>DatabaseMap</code>. + * @throws Exception Any exceptions caught during procssing will be + * rethrown wrapped into a Exception. + */ + public DatabaseMap getDatabaseMap(String name) + throws Exception; + + /** + * This method returns a Connection from the default pool. + * + * @return The requested connection. + * @throws Exception Any exceptions caught during processing will be + * rethrown wrapped into a Exception. + */ + public Connection getConnection() + throws Exception; + + /** + * This method returns a Connection from the pool with the + * specified name. The pool must either have been registered + * with the {@link #registerPool(String,String,String,String,String)} + * method, or be specified in the property file using the + * following syntax: + * + * <pre> + * database.[name].driver + * database.[name].url + * database.[name].username + * database.[name].password + * </pre> + * + * @param name The name of the pool to get a connection from. + * @return The requested connection. + * @throws Exception Any exceptions caught during processing will be + * rethrown wrapped into a Exception. + */ + public Connection getConnection(String name) + throws Exception; + + /** + * Release a connection back to the database pool. + * + * @throws Exception Any exceptions caught during processing will be + * rethrown wrapped into a Exception. + * @exception Exception A generic exception. + */ + public void releaseConnection(Connection dbconn) + throws Exception; + + + /** + * Returns the database adapter for the default connection pool. + * + * @return The database adapter. + * @throws Exception Any exceptions caught during processing will be + * rethrown wrapped into a Exception. + */ + public DB getDB() + throws Exception; + + /** + * Returns database adapter for a specific connection pool. + * + * @param name A pool name. + * @return The corresponding database adapter. + * @throws Exception Any exceptions caught during processing will be + * rethrown wrapped into a Exception. + */ + public DB getDB(String name) + throws Exception; + + + public String getDefaultDB(); + + /** + * This method is gone in Torque HEAD as it is a duplicate + * for getDefaultDB, but will stay here marked as deprecated + * for a little while. + * + * @deprecated + */ + public String getDefaultMap(); +}