com.crystaldecisions.sdk.occa.report.data
Interface IRowset

All Superinterfaces:
IClone
All Known Implementing Classes:
Rowset

public interface IRowset
extends IClone

This interface is used to get and set values for a set of rows from a table of data. The Rowset object is used to store the raw data it has retrieved and filtered in a flat format. When the RAS SDK retrieves rows from the RAS server, it does so in batches, which are of equal size except the last batch. A batch is only retrieved when it is needed or when you explicitly state you want a batch. The batches are stored in the RecordBatches object; access this collection using the getRecordBatches() method.

Use the RowsetController object's createCursor method to create, navigate, and retrieve the rowset for a report. Note, however, that when you call this function, it does not automatically retrieve all the record batches: it was intended to retrieve records in batches. For example, it could be used to display a certain number of records per web page. To retrieve record batches in the rowset, do the following:

To retrieve record batches:

  1. Set the record batch size in the Rowset controller using the setBatchSize method, and the number of batches to be cached in the cursor using the setNumOfCachedBatches method.
  2. Call the createCursor method.
  3. Use the moveTo method to fetch the batch that you want.
  4. Repeat step three until you reach the getRecordCount method, or when isEOF method returns true.
For example, suppose that RowsetBatchSize is 100, RecordCount is 500, and NumOfCachedBatches is 2.

When reading the records in the batches, be aware that the records may be filtered or sorted and thus the record keys may not be consecutive or may not be there at all: the row number, however, is always consecutive. Use the getIsRecordKeyConsecutive() method to determine whether the record keys are in consecutive order or not. The batches that have been retrieved may also be stored in an XML format. You may do this using the saveToXML method.

Note: When you save the data to XML only the data that has been retrieved is saved. This means that only a part of the record set may be saved if you have not retrieved all batches.


Method Summary
 int getBatchSize()
           Returns the size of the record batches.
 int getFirstRecordKey()
           Returns the key of the first record in the set.
 boolean getIsRecordKeyConsecutive()
           Returns true if the record keys are consecutive, and false otherwise.
 boolean getIsTotalRecordKnown()
           Returns true if the total number of records in the rowset is known, and false otherwise.
 IRowsetMetaData getMetaData()
           Returns the rowset's column headings.
 RecordBatches getRecordBatches()
           Returns the record batches that have been retrieved.
 int getTotalRecordCount()
           Returns the total number of rows in the rowset.
 java.lang.String getXMLData()
           Returns a string that stores the data in the rowset in XML format.
 void loadFromXML(java.lang.Object xmlSource)
           Loads data from an XML file into the rowset.
 void saveToXML(java.lang.Object destination)
           Saves the data in the RecordBatches collection to a file in XML format.
 void setBatchSize(int batchSize)
           Sets the size of the record batches.
 void setFirstRecordKey(int recordKey)
           Sets the key of the first record in the set.
 void setIsRecordKeyConsecutive(boolean isRecordKeyConsecutive)
           Sets> if the record keys are consecutive.
 void setMetaData(IRowsetMetaData metaData)
           Sets the rowset's column headings.
 void setRecordBatches(RecordBatches recordBatches)
           Sets the record batches that have been retrieved.
 void setTotalRecordCount(int totalRecordCount)
           Sets the total number of rows in the rowset.
 void setXMLData(java.lang.String xMLData)
           Sets the string that stores the data in the rowset in XML format.
 

Method Detail

getBatchSize

int getBatchSize()

Returns the size of the record batches.

Returns:
An int that specifies the size of the record batches.

getFirstRecordKey

int getFirstRecordKey()

Returns the key of the first record in the set.

Returns:
An int that specifies the key of the first record in the set.

getIsRecordKeyConsecutive

boolean getIsRecordKeyConsecutive()

Returns true if the record keys are consecutive, and false otherwise.

Returns:
true if the record keys are consecutive, and false otherwise.

getIsTotalRecordKnown

boolean getIsTotalRecordKnown()

Returns true if the total number of records in the rowset is known, and false otherwise.

Returns:
true if the total number of records in the rowset is known, and false otherwise.

getMetaData

IRowsetMetaData getMetaData()

Returns the rowset's column headings.

Returns:
An IRowsetMetaData object containing the rowset's column headings.

getRecordBatches

RecordBatches getRecordBatches()

Returns the record batches that have been retrieved.

Returns:
A RecordBatches object that contains the record batches that have been retrieved.

getTotalRecordCount

int getTotalRecordCount()

Returns the total number of rows in the rowset. If the total number of records is not known, this number is 7FFFFFFF hex (2147483647 decimal).

Returns:
An int that specifies the total number of rows in the rowset.

getXMLData

java.lang.String getXMLData()
                            throws java.io.IOException

Returns a string that stores the data in the rowset in XML format. To save the XML data to a file use the saveToXML method.

Returns:
A String that stores the data in the rowset in XML format.
Throws:
java.io.IOException

loadFromXML

void loadFromXML(java.lang.Object xmlSource)
                 throws java.io.FileNotFoundException,
                        java.io.IOException,
                        org.xml.sax.SAXException

Loads data from an XML file into the rowset.

Parameters:
xmlSource - The path and filename of the XML file. In Java this may also be an InputStream.
Throws:
java.io.FileNotFoundException
java.io.IOException
org.xml.sax.SAXException

saveToXML

void saveToXML(java.lang.Object destination)
               throws java.io.IOException,
                      ReportSDKException

Saves the data in the RecordBatches collection to a file in XML format.

When you save to XML only the record batches that have been retrieved from the server are saved. The XML format is ADO RecordSet compatible.

Parameters:
destination - An Object that specifies the path and filename of the XML file.
Throws:
java.io.IOException
ReportSDKException

setBatchSize

void setBatchSize(int batchSize)

Sets the size of the record batches.

Parameters:
batchSize - An int that specifies the size of the record batches.

setFirstRecordKey

void setFirstRecordKey(int recordKey)

Sets the key of the first record in the set.

Parameters:
recordKey - An int that specifies the key of the first record in the set.

setIsRecordKeyConsecutive

void setIsRecordKeyConsecutive(boolean isRecordKeyConsecutive)

Sets> if the record keys are consecutive.

Parameters:
isRecordKeyConsecutive - true if the record keys are consecutive, and false otherwise.

setMetaData

void setMetaData(IRowsetMetaData metaData)

Sets the rowset's column headings.

Parameters:
metaData - An IRowsetMetaData object containing the rowset's column headings.

setRecordBatches

void setRecordBatches(RecordBatches recordBatches)

Sets the record batches that have been retrieved.

Parameters:
recordBatches - A RecordBatches object that contains the record batches that have been retrieved.

setTotalRecordCount

void setTotalRecordCount(int totalRecordCount)

Sets the total number of rows in the rowset. If the total number of records is not known, this number is 7FFFFFFF hex (2147483647 decimal).

Parameters:
totalRecordCount - An int that specifies the total number of rows in the rowset.

setXMLData

void setXMLData(java.lang.String xMLData)
                throws java.io.IOException

Sets the string that stores the data in the rowset in XML format. To save the XML data to a file use the saveToXML method.

Parameters:
xMLData - A String that stores the data in the rowset in XML format.
Throws:
java.io.IOException