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(IBaseExpression dataExpr)
          Returns the value of a query result expression as a BigDecimal, by type casting the Object returned by getValue.
 java.sql.Blob getBlob(IBaseExpression dataExpr)
          Returns the value of a query result expression representing Blob data.
 java.lang.Boolean getBoolean(IBaseExpression dataExpr)
          Returns the value of a query result expression as a Boolean, by type casting the Object returned by getValue.
 byte[] getBytes(IBaseExpression dataExpr)
          Returns the value of a query result expression representing Binary data.
 java.util.Date getDate(IBaseExpression dataExpr)
          Returns the value of a query result expression as a Date, by type casting the Object returned by getValue.
 java.lang.Double getDouble(IBaseExpression dataExpr)
          Returns the value of a query result expression as a Double, by type casting the Object returned by getValue.
 int getEndingGroupLevel()
          Returns the 1-based index of the outermost group in which the current row is the last row.
 java.lang.Integer getInteger(IBaseExpression dataExpr)
          Returns the value of a query result expression as an Integer, by type casting the Object returned by getValue.
 IQueryResults getQueryResults()
          Returns the IQueryResults from which this result iterator is obtained.
 IResultMetaData getResultMetaData()
          Returns the metadata of this result set's detail row.
 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(IBaseExpression dataExpr)
          Returns the value of a query result expression as a String, by type casting the Object returned by getValue.
 java.lang.Object getValue(IBaseExpression dataExpr)
          Returns the value of a query result expression.
 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

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


getScope

public 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

public 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

public 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

getValue

public java.lang.Object getValue(IBaseExpression dataExpr)
                          throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression. A given data expression could be for one of the Selected Columns (if detail rows are used), or of an Aggregation specified in the prepared ReportQueryDefn spec. When requesting for the value of a Selected Column, its value in the current row of the iterator will be returned.

Throws an exception if a result expression value is requested out of sequence from the prepared IQueryDefinition spec. E.g. A group aggregation is defined to be after_last_row. It would be out of sequence if requested before having iterated/skipped to the last row of the group. In future release, this could have intelligence to auto recover and performs dependent operations to properly evaluate any out-of-sequence result values.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given expression. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getBoolean

public java.lang.Boolean getBoolean(IBaseExpression dataExpr)
                             throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression as a Boolean, by type casting the Object returned by getValue.
A convenience method for the API consumer.
If the expression value has an incompatible type, a DataException is thrown at runtime.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given expression as a Boolean. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getInteger

public java.lang.Integer getInteger(IBaseExpression dataExpr)
                             throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression as an Integer, by type casting the Object returned by getValue.
A convenience method for the API consumer.
If the expression value has an incompatible type, a DataException is thrown at runtime.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given expression as an Integer. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getDouble

public java.lang.Double getDouble(IBaseExpression dataExpr)
                           throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression as a Double, by type casting the Object returned by getValue.
A convenience method for the API consumer.
If the expression value has an incompatible type, a DataException is thrown at runtime.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given expression as a Double. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getString

public java.lang.String getString(IBaseExpression dataExpr)
                           throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression as a String, by type casting the Object returned by getValue.
A convenience method for the API consumer.
If the expression value has an incompatible type, a DataException is thrown at runtime.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given expression as a String. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getBigDecimal

public java.math.BigDecimal getBigDecimal(IBaseExpression dataExpr)
                                   throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression as a BigDecimal, by type casting the Object returned by getValue.
A convenience method for the API consumer.
If the expression value has an incompatible type, a DataException is thrown at runtime.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given expression as a BigDecimal. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getDate

public java.util.Date getDate(IBaseExpression dataExpr)
                       throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression as a Date, by type casting the Object returned by getValue.
A convenience method for the API consumer.
If the expression value has an incompatible type, a DataException is thrown at runtime.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given expression as a Date. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getBlob

public java.sql.Blob getBlob(IBaseExpression dataExpr)
                      throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression representing Blob data.
If the expression value has an incompatible type, a DataException is thrown at runtime.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given Blob expression. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

getBytes

public byte[] getBytes(IBaseExpression dataExpr)
                throws org.eclipse.birt.core.exception.BirtException
Returns the value of a query result expression representing Binary data.
If the expression value has an incompatible type, a DataException is thrown at runtime.

Parameters:
dataExpr - An IBaseExpression object provided in the IQueryDefinition at the time of prepare.
Returns:
The value of the given Blob expression. It could be null.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs in Data Engine

skipToEnd

public 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

public 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

public 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

public 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:
org.eclipse.birt.data.engine.core.DataException - if error occurs in Data Engine
org.eclipse.birt.core.exception.BirtException

close

public 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

public 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:
org.eclipse.birt.data.engine.core.DataException
org.eclipse.birt.core.exception.BirtException


Copyright © 2005 Actuate Corp. All rights reserved.