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  ;
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   default_schema, String   username, String   password,
48                  DatabaseCallBack call_back) throws SQLException  ;
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  ;
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  ;
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  ;
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  ;
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  ;
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  ;
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  ;
134 
135 }
136
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags