Source code: com/lutris/appserver/server/sql/DBQuery.java
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.17.12.1 2000/10/19 17:59:05 jasona Exp $
22 */
23
24
25
26
27
28 package com.lutris.appserver.server.sql;
29
30 import java.sql.*;
31
32 /**
33 * Utility for querying object from a database. Allocates connections from
34 * the database connection pool, ensures the integrity of those
35 * connections, and manages result sets after a
36 * <A HREF=#query>query</A> is performed. Returns objects representing
37 * data in the database.
38 *
39 * <P>Example - querying a user:
40 * <PRE>
41 *
42 * import com.lutris.appserver.server.LBS;
43 * import com.lutris.appserver.server.sql.*;
44 *
45 * DBQuery dbQuery =
46 * LBS.getDatabaseManager().createQuery(DATABASE_NAME);
47 *
48 * // NOTE: class CustomerQuery implements Query { ... }
49 * CustomerQuery
50 * customerQuery = new CustomerQuery();
51 * String [] loginIds = { "customer1", "customer2" };
52 *
53 * try {
54 * for (int idx=0; idx < loginIds.length; idx++) {
55 *
56 * customerQuery.setQueryLoginId(loginIds[idx]);
57 * dbQuery.query(customerQuery); // query the database
58 *
59 * // Print all query results.
60 * CustomerDO customerResult;
61 * while ((customerResult =
62 * (CustomerDO)dbQuery.next()) != null) {
63 * System.out.println("Customer name for " +
64 * loginIds[idx] +
65 * " is " + customerResult.getName());
66 * }
67 *
68 * }
69 * }
70 * finally {
71 * //
72 * // Return database connections used by
73 * // this object back to the connection pool
74 * // and free any other resources consumed
75 * // by this object.
76 * //
77 * dbQuery.release();
78 * }
79 *
80 * </PRE>
81 *
82 * @author Kyle Clark
83 * @since LBS1.8
84 * @version $Revision: 1.17.12.1 $
85 */
86 public interface DBQuery {
87
88 /**
89 * Query the database.
90 *
91 * @param q
92 * Query interface via which the query will be executed.
93 * @exception SQLException
94 * If a database access error occurs.
95 */
96 public void query(Query q)
97 throws SQLException;
98
99
100 /**
101 * Returns a new object representing the next result form
102 * the query.
103 *
104 * @return
105 * New instance of object representing query results.
106 * <I>null</I> is returned when there are no more results.
107 * @exception SQLException
108 * If a database access error occurs.
109 * @exception ObjectIdException
110 * If ObjectId was not found.
111 */
112 public Object next()
113 throws SQLException, ObjectIdException;
114
115
116 /**
117 * Frees all resources consumed by this query.
118 * Connections are returned to the connection pool.
119 * Subsequent queries via this object,
120 * will throw an exception.
121 */
122 public void release();
123
124
125 /**
126 * Exception handler. This object is should not be
127 * used for subsequent queries if this method returns
128 * false.
129 *
130 * @return
131 * True if the exception can be handled and the object is
132 * still valid, false otherwise.
133 */
134 public boolean handleException(SQLException e);
135
136
137 /**
138 * Method to ensure this object is still valid.
139 * Once this object has been released it cannot be
140 * used any more.
141 *
142 * @exception SQLException
143 * If a database access error occurs.
144 */
145 public void validate()
146 throws SQLException;
147 }