KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > mckoi > database > jdbc > DatabaseInterface


1 /**
2  * com.mckoi.database.jdbc.DatabaseInterface 15 Aug 2000
3  *
4  * Mckoi SQL Database ( http://www.mckoi.com/database )
5  * Copyright (C) 2000, 2001, 2002 Diehl and Associates, Inc.
6  *
7  * This program is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License
9  * Version 2 as published by the Free Software Foundation.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14  * GNU General Public License Version 2 for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * Version 2 along with this program; if not, write to the Free Software
18  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
19  *
20  * Change Log:
21  *
22  *
23  */

24
25 package com.mckoi.database.jdbc;
26
27 import java.sql.SQLException JavaDoc;
28
29 /**
30  * The interface with the Database whether it be remotely via TCP/IP or
31  * locally within the current JVM.
32  *
33  * @author Tobias Downer
34  */

35
36 public interface DatabaseInterface {
37
38   /**
39    * Attempts to log in to the database as the given username with the given
40    * password. Only one user may be authenticated per connection. This must
41    * be called before the other methods are used.
42    * <p>
43    * A DatabaseCallBack implementation must be given here that is notified
44    * of all events from the database. Events are only received if the
45    * login was successful.
46    */

47   boolean login(String JavaDoc default_schema, String JavaDoc username, String JavaDoc password,
48                 DatabaseCallBack call_back) throws SQLException JavaDoc;
49
50   /**
51    * Pushes a part of a streamable object from the client onto the server. The
52    * server stores the large object for use with a future query. For example,
53    * a sequence of with a query with large objects may operate as follows;
54    * <p><pre>
55    * 1) Push 100 MB object (id = 104)
56    * 2) execQuery with query that contains a streamable object with id 104
57    * </pre><p>
58    * Note that the client may push any part of a streamable object onto the
59    * server, however the streamable object must have been completely pushed
60    * for the query to execute correctly. For example, an 100 MB byte array may
61    * be pushed onto the server in blocks of 64K (in 1,600 separate blocks).
62    * <p>
63    * @param type the StreamableObject type (1 = byte array, 2 = char array)
64    * @param object_id the identifier of the StreamableObject for future queries.
65    * @param object_length the total length of the StreamableObject.
66    * @param buf the byte[] array representing the block of information being
67    * sent.
68    * @param offset the offset into of the object of this block.
69    * @param length the length of the block being pushed.
70    */

71   void pushStreamableObjectPart(byte type, long object_id, long object_length,
72                       byte[] buf, long offset, int length) throws SQLException JavaDoc;
73
74   /**
75    * Executes the query and returns a QueryResponse object that describes the
76    * result of the query. The QueryResponse object describes the number of
77    * rows, describes the columns, etc. This method will block until the query
78    * has completed. The QueryResponse can be used to obtain the 'result id'
79    * variable that is used in subsequent queries to the engine to retrieve
80    * the actual result of the query.
81    */

82   QueryResponse execQuery(SQLQuery sql) throws SQLException JavaDoc;
83
84   /**
85    * Returns a part of a result set. The result set part is referenced via the
86    * 'result id' found in the QueryResponse. This is used to read parts
87    * of the query once it has been found via 'execQuery'.
88    * <p>
89    * The returned List object contains the result requested.
90    * <p>
91    * If the result contains any StreamableObject objects, then the server
92    * allocates a channel to the object via the 'getStreamableObjectPart' and
93    * the identifier of the StreamableObject. The channel may only be disposed
94    * if the 'disposeStreamableObject' method is called.
95    */

96   ResultPart getResultPart(int result_id, int row_number, int row_count)
97                                                           throws SQLException JavaDoc;
98
99   /**
100    * Disposes of a result of a query on the server. This frees up server side
101    * resources allocated to a query. This should be called when the ResultSet
102    * of a query closes. We should try and use this method as soon as possible
103    * because it frees locks on tables and allows deleted rows to be
104    * reclaimed.
105    */

106   void disposeResult(int result_id) throws SQLException JavaDoc;
107
108   /**
109    * Returns a section of a large binary or character stream in a result set.
110    * This is used to stream large values over the connection. For example, if
111    * a row contained a multi megabyte object and the client is only interested
112    * in the first few characters and the last few characters of the stream.
113    * This would require only a few queries to the database and the multi-
114    * megabyte object would not need to be downloaded to the client in its
115    * entirety.
116    */

117   StreamableObjectPart getStreamableObjectPart(int result_id,
118          long streamable_object_id, long offset, int len) throws SQLException JavaDoc;
119
120   /**
121    * Disposes a streamable object channel with the given identifier. This
122    * should be called to free any resources on the server associated with the
123    * object. It should be called as soon as possible because it frees locks on
124    * the tables and allows deleted rows to be reclaimed.
125    */

126   void disposeStreamableObject(int result_id, long streamable_object_id)
127                                                           throws SQLException JavaDoc;
128
129   /**
130    * Called when the connection is disposed. This will terminate the
131    * connection if there is any connection to terminate.
132    */

133   void dispose() throws SQLException JavaDoc;
134
135 }
136
Popular Tags