001: //$Id: ScrollableResults.java 6411 2005-04-13 07:37:50Z oneovthafew $
002: package org.hibernate;
003:
004: import java.math.BigDecimal;
005: import java.math.BigInteger;
006: import java.sql.Blob;
007: import java.sql.Clob;
008: import java.util.Calendar;
009: import java.util.Date;
010: import java.util.Locale;
011: import java.util.TimeZone;
012:
013: import org.hibernate.type.Type;
014:
015: /**
016: * A result iterator that allows moving around within the results
017: * by arbitrary increments. The <tt>Query</tt> / <tt>ScrollableResults</tt>
018: * pattern is very similar to the JDBC <tt>PreparedStatement</tt>/
019: * <tt>ResultSet</tt> pattern and the semantics of methods of this interface
020: * are similar to the similarly named methods on <tt>ResultSet</tt>.<br>
021: * <br>
022: * Contrary to JDBC, columns of results are numbered from zero.
023: *
024: * @see Query#scroll()
025: * @author Gavin King
026: */
027: public interface ScrollableResults {
028: /**
029: * Advance to the next result
030: * @return <tt>true</tt> if there is another result
031: */
032: public boolean next() throws HibernateException;
033:
034: /**
035: * Retreat to the previous result
036: * @return <tt>true</tt> if there is a previous result
037: */
038: public boolean previous() throws HibernateException;
039:
040: /**
041: * Scroll an arbitrary number of locations
042: * @param i a positive (forward) or negative (backward) number of rows
043: * @return <tt>true</tt> if there is a result at the new location
044: */
045: public boolean scroll(int i) throws HibernateException;
046:
047: /**
048: * Go to the last result
049: * @return <tt>true</tt> if there are any results
050: */
051: public boolean last() throws HibernateException;
052:
053: /**
054: * Go to the first result
055: * @return <tt>true</tt> if there are any results
056: */
057: public boolean first() throws HibernateException;
058:
059: /**
060: * Go to a location just before first result (this is the initial location)
061: */
062: public void beforeFirst() throws HibernateException;
063:
064: /**
065: * Go to a location just after the last result
066: */
067: public void afterLast() throws HibernateException;
068:
069: /**
070: * Is this the first result?
071: *
072: * @return <tt>true</tt> if this is the first row of results
073: * @throws HibernateException
074: */
075: public boolean isFirst() throws HibernateException;
076:
077: /**
078: * Is this the last result?
079: *
080: * @return <tt>true</tt> if this is the last row of results
081: * @throws HibernateException
082: */
083: public boolean isLast() throws HibernateException;
084:
085: /**
086: * Release resources immediately.
087: */
088: public void close() throws HibernateException;
089:
090: /**
091: * Get the current row of results
092: * @return an object or array
093: */
094: public Object[] get() throws HibernateException;
095:
096: /**
097: * Get the <tt>i</tt>th object in the current row of results, without
098: * initializing any other results in the row. This method may be used
099: * safely, regardless of the type of the column (ie. even for scalar
100: * results).
101: * @param i the column, numbered from zero
102: * @return an object of any Hibernate type or <tt>null</tt>
103: */
104: public Object get(int i) throws HibernateException;
105:
106: /**
107: * Get the type of the <tt>i</tt>th column of results
108: * @param i the column, numbered from zero
109: * @return the Hibernate type
110: */
111: public Type getType(int i);
112:
113: /**
114: * Convenience method to read an <tt>integer</tt>
115: */
116: public Integer getInteger(int col) throws HibernateException;
117:
118: /**
119: * Convenience method to read a <tt>long</tt>
120: */
121: public Long getLong(int col) throws HibernateException;
122:
123: /**
124: * Convenience method to read a <tt>float</tt>
125: */
126: public Float getFloat(int col) throws HibernateException;
127:
128: /**
129: * Convenience method to read a <tt>boolean</tt>
130: */
131: public Boolean getBoolean(int col) throws HibernateException;
132:
133: /**
134: * Convenience method to read a <tt>double</tt>
135: */
136: public Double getDouble(int col) throws HibernateException;
137:
138: /**
139: * Convenience method to read a <tt>short</tt>
140: */
141: public Short getShort(int col) throws HibernateException;
142:
143: /**
144: * Convenience method to read a <tt>byte</tt>
145: */
146: public Byte getByte(int col) throws HibernateException;
147:
148: /**
149: * Convenience method to read a <tt>character</tt>
150: */
151: public Character getCharacter(int col) throws HibernateException;
152:
153: /**
154: * Convenience method to read a <tt>binary</tt>
155: */
156: public byte[] getBinary(int col) throws HibernateException;
157:
158: /**
159: * Convenience method to read <tt>text</tt>
160: */
161: public String getText(int col) throws HibernateException;
162:
163: /**
164: * Convenience method to read a <tt>blob</tt>
165: */
166: public Blob getBlob(int col) throws HibernateException;
167:
168: /**
169: * Convenience method to read a <tt>clob</tt>
170: */
171: public Clob getClob(int col) throws HibernateException;
172:
173: /**
174: * Convenience method to read a <tt>string</tt>
175: */
176: public String getString(int col) throws HibernateException;
177:
178: /**
179: * Convenience method to read a <tt>big_decimal</tt>
180: */
181: public BigDecimal getBigDecimal(int col) throws HibernateException;
182:
183: /**
184: * Convenience method to read a <tt>big_integer</tt>
185: */
186: public BigInteger getBigInteger(int col) throws HibernateException;
187:
188: /**
189: * Convenience method to read a <tt>date</tt>, <tt>time</tt> or <tt>timestamp</tt>
190: */
191: public Date getDate(int col) throws HibernateException;
192:
193: /**
194: * Convenience method to read a <tt>locale</tt>
195: */
196: public Locale getLocale(int col) throws HibernateException;
197:
198: /**
199: * Convenience method to read a <tt>calendar</tt> or <tt>calendar_date</tt>
200: */
201: public Calendar getCalendar(int col) throws HibernateException;
202:
203: /**
204: * Convenience method to read a <tt>currency</tt>
205: */
206: //public Currency getCurrency(int col) throws HibernateException;
207: /**
208: * Convenience method to read a <tt>timezone</tt>
209: */
210: public TimeZone getTimeZone(int col) throws HibernateException;
211:
212: /**
213: * Get the current location in the result set. The first
214: * row is number <tt>0</tt>, contrary to JDBC.
215: * @return the row number, numbered from <tt>0</tt>, or <tt>-1</tt> if
216: * there is no current row
217: */
218: public int getRowNumber() throws HibernateException;
219:
220: /**
221: * Set the current location in the result set, numbered from either the
222: * first row (row number <tt>0</tt>), or the last row (row
223: * number <tt>-1</tt>).
224: * @param rowNumber the row number, numbered from the last row, in the
225: * case of a negative row number
226: * @return true if there is a row at that row number
227: */
228: public boolean setRowNumber(int rowNumber)
229: throws HibernateException;
230: }
|