KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > lutris > appserver > server > sql > DBQuery


1 /*
2  * Enhydra Java Application Server Project
3  *
4  * The contents of this file are subject to the Enhydra Public License
5  * Version 1.1 (the "License"); you may not use this file except in
6  * compliance with the License. You may obtain a copy of the License on
7  * the Enhydra web site ( http://www.enhydra.org/ ).
8  *
9  * Software distributed under the License is distributed on an "AS IS"
10  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
11  * the License for the specific terms governing rights and limitations
12  * under the License.
13  *
14  * The Initial Developer of the Enhydra Application Server is Lutris
15  * Technologies, Inc. The Enhydra Application Server and portions created
16  * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
17  * All Rights Reserved.
18  *
19  * Contributor(s):
20  *
21  * $Id: DBQuery.java,v 1.1 2004/09/03 13:42:37 sinisa Exp $
22  */
23 package com.lutris.appserver.server.sql;
24
25 import java.sql.SQLException JavaDoc;
26
27 /**
28  * Utility for querying object from a database. Allocates connections from
29  * the database connection pool, ensures the integrity of those
30  * connections, and manages result sets after a
31  * <A HREF=#query>query</A> is performed. Returns objects representing
32  * data in the database.
33  *
34  * <P>Example - querying a user:
35  * <PRE>
36  *
37  * import org.enhydra.dods.DODS;
38  * import com.lutris.appserver.server.sql.*;
39  *
40  * DBQuery dbQuery =
41  * DODS.getDatabaseManager().createQuery(DATABASE_NAME);
42  *
43  * // NOTE: class CustomerQuery implements Query { ... }
44  * CustomerQuery
45  * customerQuery = new CustomerQuery();
46  * String [] loginIds = { "customer1", "customer2" };
47  *
48  * try {
49  * for (int idx=0; idx &lt loginIds.length; idx++) {
50  *
51  * customerQuery.setQueryLoginId(loginIds[idx]);
52  * dbQuery.query(customerQuery); // query the database
53  *
54  * // Print all query results.
55  * CustomerDO customerResult;
56  * while ((customerResult =
57  * (CustomerDO)dbQuery.next()) != null) {
58  * System.out.println("Customer name for " +
59  * loginIds[idx] +
60  * " is " + customerResult.getName());
61  * }
62  *
63  * }
64  * }
65  * finally {
66  * //
67  * // Return database connections used by
68  * // this object back to the connection pool
69  * // and free any other resources consumed
70  * // by this object.
71  * //
72  * dbQuery.release();
73  * }
74  *
75  * </PRE>
76  *
77  * @author Kyle Clark
78  * @since LBS1.8
79  * @version $Revision: 1.1 $
80  */
81 public interface DBQuery {
82
83     /**
84      * Query the database.
85      *
86      * @param q
87      * Query interface via which the query will be executed.
88      * @exception SQLException
89      * If a database access error occurs.
90      */
91     public void query(Query q)
92         throws SQLException JavaDoc;
93
94     /**
95      * Returns a new object representing the next result form
96      * the query.
97      *
98      * @return
99      * New instance of object representing query results.
100      * <I>null</I> is returned when there are no more results.
101      * @exception SQLException
102      * If a database access error occurs.
103      * @exception ObjectIdException
104      * If ObjectId was not found.
105      */
106     public Object JavaDoc next()
107         throws SQLException JavaDoc, ObjectIdException;
108
109     /**
110      * Frees all resources consumed by this query.
111      * Connections are returned to the connection pool.
112      * Subsequent queries via this object,
113      * will throw an exception.
114      */
115     public void release();
116
117     /**
118      * Exception handler. This object is should not be
119      * used for subsequent queries if this method returns
120      * false.
121      *
122      * @return
123      * True if the exception can be handled and the object is
124      * still valid, false otherwise.
125      */
126     public boolean handleException(SQLException JavaDoc e);
127
128     /**
129      * Method to ensure this object is still valid.
130      * Once this object has been released it cannot be
131      * used any more.
132      *
133      * @exception SQLException
134      * If a database access error occurs.
135      */
136     public void validate()
137         throws SQLException JavaDoc;
138 }
139
Popular Tags