org.eclipse.birt.data.engine.api
Interface IResultIterator


public interface IResultIterator

An iterator on a result set from a prepared and executed query. Multiple IResultIterator objects could be associated with the same IQueryResults object, such as in the case of an ODA data set capable of producing multiple result sets.


Method Summary
 void close()
          Closes this result and any associated secondary result iterator(s), providing a hint that the consumer is done with this result, whose resources can be safely released as appropriate.
 boolean findGroup(java.lang.Object[] groupKeyValues)
          Move the current position of the iterator to the first element of the group with matching group key values.
 java.math.BigDecimal getBigDecimal(java.lang.String name)
          Returns the value of a bound column as the BigDecimal data type.
 java.sql.Blob getBlob(java.lang.String name)
          Returns the value of a bound column as the Blob data type.
 java.lang.Boolean getBoolean(java.lang.String name)
          Returns the value of a bound column as the Boolean data type.
 byte[] getBytes(java.lang.String name)
          Returns the value of a bound column as the byte[] data type.
 java.util.Date getDate(java.lang.String name)
          Returns the value of a bound column as the Date data type.
 java.lang.Double getDouble(java.lang.String name)
          Returns the value of a bound column as the Double data type.
 int getEndingGroupLevel()
          Returns the 1-based index of the outermost group in which the current row is the last row.
 java.lang.Integer getInteger(java.lang.String name)
          Returns the value of a bound column as the Integer data type.
 IQueryResults getQueryResults()
          Returns the IQueryResults from which this result iterator is obtained.
 IResultMetaData getResultMetaData()
          Returns the metadata of this result set's detail row.
 int getRowId()
          Each row has its an ID associated with it, and this id will never be changed no matter when the query is running against a data set or against a report document.
 int getRowIndex()
          Each row has its own index, which indicates this row position in the result set.
 org.mozilla.javascript.Scriptable getScope()
          Returns the JavaScript scope associated with this result iterator.
 IResultIterator getSecondaryIterator(java.lang.String subQueryName, org.mozilla.javascript.Scriptable scope)
          Returns the secondary result specified by a sub query that was defined in the prepared IQueryDefinition.
 int getStartingGroupLevel()
          Returns the 1-based index of the outermost group in which the current row is the first row.
 java.lang.String getString(java.lang.String name)
          Returns the value of a bound column as the String data type.
 java.lang.Object getValue(java.lang.String name)
          Returns the value of a bound column.
 boolean isBeforeFirst()
          Retrieves whether the cursor is before the first row in this IResultIterator object.
 boolean isEmpty()
          Judges if the IResultSetIterator is empty or not
 boolean isFirst()
          Retrieves whether the cursor is on the first row of this IResultIterator object.
 void moveTo(int rowIndex)
          Moves iterator to the row with given absolute index.
 boolean next()
          Moves down one element from its current position of the iterator.
 void skipToEnd(int groupLevel)
          Advances the iterator, skipping rows to the last row in the current group at the specified group level.
 

Method Detail

getQueryResults

IQueryResults getQueryResults()
Returns the IQueryResults from which this result iterator is obtained. If this iterator is that of a subquery, null is returned.


getScope

org.mozilla.javascript.Scriptable getScope()
Returns the JavaScript scope associated with this result iterator. All JavaScript result objects, e.g. rows, row, specific to this result set are defined within this scope. The returned scope is the same as the one passed to IPreparedQuery.excute() which produced this iterator's IQueryResults.

Returns:
The JavaScript scope associated to this result iterator.

getResultMetaData

IResultMetaData getResultMetaData()
                                  throws org.eclipse.birt.core.exception.BirtException
Returns the metadata of this result set's detail row.

Returns:
The result metadata of a detail row.
Throws:
org.eclipse.birt.core.exception.BirtException

next

boolean next()
             throws org.eclipse.birt.core.exception.BirtException
Moves down one element from its current position of the iterator. This method applies to a result whose ReportQuery is defined to use detail or group rows.

Returns:
true if next element exists and has not reached the limit on the maximum number of rows that can be accessed.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getRowId

int getRowId()
             throws org.eclipse.birt.core.exception.BirtException
Each row has its an ID associated with it, and this id will never be changed no matter when the query is running against a data set or against a report document.

Returns:
row id of current row
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine
Since:
2.1

getRowIndex

int getRowIndex()
                throws org.eclipse.birt.core.exception.BirtException
Each row has its own index, which indicates this row position in the result set. This method retrieves current row index. The row index is 0 based, and -1 is returned when there is no current row.

Returns:
row index of current row
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine
Since:
2.1

moveTo

void moveTo(int rowIndex)
            throws org.eclipse.birt.core.exception.BirtException
Moves iterator to the row with given absolute index. Valid index must be both not less than current row index and not great than the maximum row index. Presently backward see is not supportted.

Parameters:
rowIndex, - which index needs to advance to
Throws:
BirtException, - if rowIndex is invalid
org.eclipse.birt.core.exception.BirtException
Since:
2.1

getValue

java.lang.Object getValue(java.lang.String name)
                          throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

getBoolean

java.lang.Boolean getBoolean(java.lang.String name)
                             throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column as the Boolean data type. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

getInteger

java.lang.Integer getInteger(java.lang.String name)
                             throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column as the Integer data type. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

getDouble

java.lang.Double getDouble(java.lang.String name)
                           throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column as the Double data type. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

getString

java.lang.String getString(java.lang.String name)
                           throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column as the String data type. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

getBigDecimal

java.math.BigDecimal getBigDecimal(java.lang.String name)
                                   throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column as the BigDecimal data type. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

getDate

java.util.Date getDate(java.lang.String name)
                       throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column as the Date data type. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

getBlob

java.sql.Blob getBlob(java.lang.String name)
                      throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column as the Blob data type. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

getBytes

byte[] getBytes(java.lang.String name)
                throws org.eclipse.birt.core.exception.BirtException
Returns the value of a bound column as the byte[] data type. Currently it is only a dummy implementation.

Parameters:
name - of bound column
Returns:
value of bound column
Throws:
org.eclipse.birt.core.exception.BirtException

skipToEnd

void skipToEnd(int groupLevel)
               throws org.eclipse.birt.core.exception.BirtException
Advances the iterator, skipping rows to the last row in the current group at the specified group level. This is for result sets that do not use detail rows to advance to next group. Calling next() after skip() would position the current row to the first row of the next group.

Parameters:
groupLevel - An absolute value for group level. A value of 0 applies to the whole result set.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getStartingGroupLevel

int getStartingGroupLevel()
                          throws org.eclipse.birt.core.exception.BirtException
Returns the 1-based index of the outermost group in which the current row is the first row. For example, if a query contain N groups (group with index 1 being the outermost group, and group with index N being the innermost group), and this function returns a value M, it indicates that the current row is the first row in groups with indexes (M, M+1, ..., N ).

Returns:
1-based index of the outermost group in which the current row is the first row; (N+1) if the current row is not at the start of any group; 0 if the result set has no groups.
Throws:
org.eclipse.birt.core.exception.BirtException

getEndingGroupLevel

int getEndingGroupLevel()
                        throws org.eclipse.birt.core.exception.BirtException
Returns the 1-based index of the outermost group in which the current row is the last row. For example, if a query contain N groups (group with index 1 being the outermost group, and group with index N being the innermost group), and this function returns a value M, it indicates that the current row is the last row in groups with indexes (M, M+1, ..., N ).

Returns:
1-based index of the outermost group in which the current row is the last row; (N+1) if the current row is not at the end of any group; 0 if the result set has no groups.
Throws:
org.eclipse.birt.core.exception.BirtException

getSecondaryIterator

IResultIterator getSecondaryIterator(java.lang.String subQueryName,
                                     org.mozilla.javascript.Scriptable scope)
                                     throws org.eclipse.birt.core.exception.BirtException
Returns the secondary result specified by a sub query that was defined in the prepared IQueryDefinition.

Parameters:
subQueryName - name of sub query which defines the secondary result set
scope - Javascript scope to be associated with the secondary result set
Throws:
DataException - if error occurs in Data Engine
org.eclipse.birt.core.exception.BirtException

close

void close()
           throws org.eclipse.birt.core.exception.BirtException
Closes this result and any associated secondary result iterator(s), providing a hint that the consumer is done with this result, whose resources can be safely released as appropriate.

Throws:
org.eclipse.birt.core.exception.BirtException

findGroup

boolean findGroup(java.lang.Object[] groupKeyValues)
                  throws org.eclipse.birt.core.exception.BirtException
Move the current position of the iterator to the first element of the group with matching group key values. To locate the [n]th inner group, values for all outer groups锟�? keys need to be provided in the array groupKeyValues. groupKeyValue[0] is the key value for group 1 (outermost group), groupKeyValue[1] is the key value for group 2, etc.

Parameters:
groupKeyValues - Values of group keys
Returns:
true if group located successfully and cursor is re-positioned. False if no group is found to match the group key values exactly, and iterator cursor is not moved.
Throws:
DataException
org.eclipse.birt.core.exception.BirtException

isEmpty

boolean isEmpty()
                throws org.eclipse.birt.core.exception.BirtException
Judges if the IResultSetIterator is empty or not

Returns:
true if IResultSetIterator is empty. false if the IResultSetIterator is not empty.
Throws:
org.eclipse.birt.core.exception.BirtException

isFirst

boolean isFirst()
                throws org.eclipse.birt.core.exception.BirtException
Retrieves whether the cursor is on the first row of this IResultIterator object.

Returns:
true if the cursor is on the first row; false otherwise
Throws:
org.eclipse.birt.core.exception.BirtException

isBeforeFirst

boolean isBeforeFirst()
                      throws org.eclipse.birt.core.exception.BirtException
Retrieves whether the cursor is before the first row in this IResultIterator object.

Returns:
true if the cursor is before the first row; false if the cursor is at any other position or the result set contains no rows
Throws:
org.eclipse.birt.core.exception.BirtException


Copyright © 2008 Actuate Corp. All rights reserved.