Cursor


1   package com.quadcap.sql;
2   
3   /* Copyright 1999 - 2003 Quadcap Software.  All rights reserved.
4    *
5    * This software is distributed under the Quadcap Free Software License.
6    * This software may be used or modified for any purpose, personal or
7    * commercial.  Open Source redistributions are permitted.  Commercial
8    * redistribution of larger works derived from, or works which bundle
9    * this software requires a "Commercial Redistribution License"; see
10   * http://www.quadcap.com/purchase.
11   *
12   * Redistributions qualify as "Open Source" under  one of the following terms:
13   *   
14   *    Redistributions are made at no charge beyond the reasonable cost of
15   *    materials and delivery.
16   *
17   *    Redistributions are accompanied by a copy of the Source Code or by an
18   *    irrevocable offer to provide a copy of the Source Code for up to three
19   *    years at the cost of materials and delivery.  Such redistributions
20   *    must allow further use, modification, and redistribution of the Source
21   *    Code under substantially the same terms as this license.
22   *
23   * Redistributions of source code must retain the copyright notices as they
24   * appear in each source code file, these license terms, and the
25   * disclaimer/limitation of liability set forth as paragraph 6 below.
26   *
27   * Redistributions in binary form must reproduce this Copyright Notice,
28   * these license terms, and the disclaimer/limitation of liability set
29   * forth as paragraph 6 below, in the documentation and/or other materials
30   * provided with the distribution.
31   *
32   * The Software is provided on an "AS IS" basis.  No warranty is
33   * provided that the Software is free of defects, or fit for a
34   * particular purpose.  
35   *
36   * Limitation of Liability. Quadcap Software shall not be liable
37   * for any damages suffered by the Licensee or any third party resulting
38   * from use of the Software.
39   */
40  
41  import java.io.IOException  ;
42  
43  import java.util.Vector  ;
44  
45  import java.sql.SQLException  ;
46  
47  /**
48   * The base cursor interface.
49   *
50   * @author Stan Bailes
51   */
52  public interface Cursor extends Tuple {
53      // ---------------------- Row accessors
54      /**
55       * Return the cursor's current row
56       */
57      public Row getRow() throws SQLException  ;
58  
59      /**
60       * Insert the specified row into the cursor's underlying table
61       */
62      public void insertRow(Row row) throws SQLException  ;
63  
64      /**
65       * Replace the current cursor row with the specified row
66       */
67      public void updateRow(Row row) throws SQLException  ;
68  
69      /**
70       * Delete the current cursor row
71       */
72      public void deleteRow() throws SQLException  ;
73  
74      /**
75       * Some cursors have rows where the rows can be identified by row
76       * id, and sometimes the cursors even know the row id for the
77       * current row.   If you know, tell us here!  If you don't know,
78       * just return 0.
79       */     
80      public long getRowId();
81  
82  
83      // ---------------------- Movement
84      /**
85       * Position the cursor before the first row
86       */
87      public void beforeFirst() throws SQLException  ;
88  
89      /**
90       * Position the cursor after the last row.
91       */
92      public void afterLast() throws SQLException  ;
93  
94      /**
95       * Move to the specified absolute row.  The first row is '1'.
96       * absolute(-1) moves to the last row.  absolute(0) throws an
97       * exception.
98       *
99       * @param row if > 0 the (one-based) row number else negative
100      *          offset from last row in cursor.
101      * @return <b>true</b> if the specified row can be successfully
102      * positioned.
103      */
104     public boolean absolute(int row) throws SQLException  ;
105 
106     /**
107      * Advance the cursor and return true if we advanced to a valid row
108      */
109     public boolean next() throws SQLException  ;
110 
111     /**
112      * Move the cursor back one row and return true if we moved back
113      * to a valid row.
114      */
115     public boolean prev() throws SQLException  ;
116 
117     /**
118      * Close the cursor and free up any resources (including closing
119      * the cursor's transaction if that is feasible) used by the cursor.
120      *
121      * @exception SQLException may be thrown
122      */
123     public void close() throws SQLException  ;
124 
125     // ---------------------- Accessors
126 
127     /**
128      * If the underlying implementation knows, or can compute cheaply,
129      * the actual size of the ResultSet, it should return a non-negative
130      * number here.  If the size is unknown and it would be expensive to
131      * compute it (i.e., on the order of <code>while next()) size++</code>),
132      * then the implementation should return -1
133      */
134     public long size() throws SQLException  ;
135 
136     /**
137      * Return <b>true</b> if the specified column is writable.
138      *
139      * @param column the (one-based) column number
140      * @exception SQLException may be thrown
141      */
142     public boolean isWritable(int column) throws SQLException  ;
143 
144     /**
145      * Return the cursor in the enclosing context (this applies if we're
146      * in a sub-query, for example)
147      */
148     public Cursor getOuterCursor();
149 
150     /**
151      * Set the cursor context in which this subquery is executing
152      *
153      * @param outer the cursor from the outer context
154      */
155     public void setOuterCursor(Cursor outer);
156 
157     /**
158      * Return the cursor's session
159      */
160     public Session getSession();
161 
162     /**
163      * Some cursors are, or can be viewed as, tables.  If your cursor
164      * is such a type, return your table here, otherwise simply return
165      * null.
166      */
167     public Table getTable();
168 
169     /**
170      * An attempt at an API to allow cursor reuse.
171      */
172     public void reset(Expression where, Cursor outer) throws SQLException  ;
173 }
174
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags