001: /*
002: * Enhydra Java Application Server Project
003: *
004: * The contents of this file are subject to the Enhydra Public License
005: * Version 1.1 (the "License"); you may not use this file except in
006: * compliance with the License. You may obtain a copy of the License on
007: * the Enhydra web site ( http://www.enhydra.org/ ).
008: *
009: * Software distributed under the License is distributed on an "AS IS"
010: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
011: * the License for the specific terms governing rights and limitations
012: * under the License.
013: *
014: * The Initial Developer of the Enhydra Application Server is Lutris
015: * Technologies, Inc. The Enhydra Application Server and portions created
016: * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
017: * All Rights Reserved.
018: *
019: * Contributor(s):
020: *
021: * $Id: DBQuery.java,v 1.1 2007-01-24 16:59:09 sinisa Exp $
022: */
023: package com.lutris.appserver.server.sql;
024:
025: import java.sql.SQLException;
026:
027: /**
028: * Utility for querying object from a database. Allocates connections from
029: * the database connection pool, ensures the integrity of those
030: * connections, and manages result sets after a
031: * <A HREF=#query>query</A> is performed. Returns objects representing
032: * data in the database.
033: *
034: * <P>Example - querying a user:
035: * <PRE>
036: *
037: * import org.enhydra.dods.DODS;
038: * import com.lutris.appserver.server.sql.*;
039: *
040: * DBQuery dbQuery =
041: * DODS.getDatabaseManager().createQuery(DATABASE_NAME);
042: *
043: * // NOTE: class CustomerQuery implements Query { ... }
044: * CustomerQuery
045: * customerQuery = new CustomerQuery();
046: * String [] loginIds = { "customer1", "customer2" };
047: *
048: * try {
049: * for (int idx=0; idx < loginIds.length; idx++) {
050: *
051: * customerQuery.setQueryLoginId(loginIds[idx]);
052: * dbQuery.query(customerQuery); // query the database
053: *
054: * // Print all query results.
055: * CustomerDO customerResult;
056: * while ((customerResult =
057: * (CustomerDO)dbQuery.next()) != null) {
058: * System.out.println("Customer name for " +
059: * loginIds[idx] +
060: * " is " + customerResult.getName());
061: * }
062: *
063: * }
064: * }
065: * finally {
066: * //
067: * // Return database connections used by
068: * // this object back to the connection pool
069: * // and free any other resources consumed
070: * // by this object.
071: * //
072: * dbQuery.release();
073: * }
074: *
075: * </PRE>
076: *
077: * @author Kyle Clark
078: * @since LBS1.8
079: * @version $Revision: 1.1 $
080: */
081: public interface DBQuery {
082:
083: /**
084: * Query the database.
085: *
086: * @param q
087: * Query interface via which the query will be executed.
088: * @exception SQLException
089: * If a database access error occurs.
090: */
091: public void query(Query q) throws SQLException;
092:
093: /**
094: * Returns a new object representing the next result form
095: * the query.
096: *
097: * @return
098: * New instance of object representing query results.
099: * <I>null</I> is returned when there are no more results.
100: * @exception SQLException
101: * If a database access error occurs.
102: * @exception ObjectIdException
103: * If ObjectId was not found.
104: */
105: public Object next() throws SQLException, ObjectIdException;
106:
107: /**
108: * Frees all resources consumed by this query.
109: * Connections are returned to the connection pool.
110: * Subsequent queries via this object,
111: * will throw an exception.
112: */
113: public void release();
114:
115: /**
116: * Exception handler. This object is should not be
117: * used for subsequent queries if this method returns
118: * false.
119: *
120: * @return
121: * True if the exception can be handled and the object is
122: * still valid, false otherwise.
123: */
124: public boolean handleException(SQLException e);
125:
126: /**
127: * Method to ensure this object is still valid.
128: * Once this object has been released it cannot be
129: * used any more.
130: *
131: * @exception SQLException
132: * If a database access error occurs.
133: */
134: public void validate() throws SQLException;
135: }
|