com.crystaldecisions.sdk.occa.report.application
Class RowsetController

java.lang.Object
  extended by com.crystaldecisions.sdk.occa.report.application.RowsetController

public class RowsetController
extends java.lang.Object

This object is used to retrieve unformatted data in the report directly. In other words, it provides access to the rowsets in the ReportClientDocument. When data is retrieved from the database, it is filtered, grouped, and sorted, and then stored in a tree structure called the Totaller. The RowsetController allows you to search for and access this data in the tree. Additionally, it allows you some control over how the data is retrieved and cached by both the server and the client.


Method Summary
 void applyParameterFields(RowsetRequest request)
          For internal use only.
 Records browseFieldsValues(Fields browseFields, int cLimit)
          For internal use only
 Values browseFieldValues(IField field, int cLimit)
           Allows you to browse the values for a particular field in one of the tables from the database server.
 Records browseTableValues(ITable table, int cLimit)
           Allows you to browse the values for any field in the specified table from the database server.
 boolean canBrowseField(IField field)
           Returns true if a given field has data that can be browsed, and false otherwise.
 boolean canBrowseTable(ITable table)
          For internal use only
 void clearClientCaches()
          For internal use only
 RowsetCursor createCursor(IGroupPath groupPath, IRowsetMetaData metaData)
           Creates a cursor to navigate the set of data fetched from the server.
 void emptyBatch(IRowset rowset, int batchNumber)
          For internal use only.
 void fetchRowsetBatchByRowN(IGroupPath groupPath, IRowset rowset, int rowNumber)
          For internal use only.
 int findRowNByRecordKey(RowsetCursor cursor, int recordKey)
           Returns the row number given a record key; it converts the record number to a row number if the record numbers in the rowset are not consecutive.
 void fireOnRowsetBatchChanged(IGroupPath groupPath, IRowset rowset)
          For internal use only.
 void fireOnRowsetMoreBatchChanged(IRowset rowset, int batchNumber)
          For internal use only.
 void fireOnSearchResultChanged(RowsetSearchResult searchHandle, boolean moreRecords)
          For internal use only.
 IRowsetMetaData getDefaultMetaData(IGroupPath pGroupPath)
          For internal use only.
 int getDefaultNumOfBrowsingRecords()
           Returns the number of records that are retrieved when using the various browse methods (browseFieldValues method, browseTableValues method) that examine the contents of the report's database.
 int getFirstRecordKey(IGroupPath pGroupPath)
           Returns the record key for the first record under the specified group path.
 LOVRowsetProcessorHost getLOVRowsetProcessorHost()
          For internal use only.
 int getMaxNumOfRecords()
           Returns the maximum number of records that are to be retrieved from the database.
 java.util.Locale getProductLocale()
           
 int getRefreshOptions()
           Returns the options used by the RowsetController.refresh() method for refreshing the rowset.
 IRowset getRowset(IGroupPath groupPath, IRowsetMetaData metaData)
          For internal use only.
 int getRowsetBatchSize()
           Returns the number of records in each batch in the rowset.
 java.lang.String getSQLStatement(IGroupPath groupPath, java.lang.String specialStatement)
           Returns the SQL statement that is used to return records from the database.
 TotallerNodes getSubTotallerNodes(IGroupPath parentGroup)
           Returns the subnodes that belong to the root node of a specified parent group path.
 ITotallerNode getTotallerNode(IGroupPath pGroupPath)
           Returns the TotallerNode object in the given group path.
 boolean isServerCacheFilled()
           For internal use only.
 ResultInfo performFetchRowsetRequest(RowsetRequest request, int requestOptions, java.lang.Object additionalFetchRowsetInfo)
          For internal use only.
 ResultInfo performFetchSearchResultRequest(RowsetRequest request, int requestOptions, java.lang.Object additionalFetchSearchResultInfo)
          For internal use only.
 void refresh()
           Clears both the client's cache and the server's cache.
 void setDefaultNumOfBrowsingRecords(int defaultNumOfBrowsingRecords)
           Sets the number of records that are retrieved when using the various browse methods (browseFieldValues method, browseTableValues method) that examine the contents of the report's database.
 void setMaxNumOfRecords(int maxNumOfRecords)
           Sets the maximum number of records that are to be retrieved from the database.
 void setNumOfCachedBatches(int maxNumOfCachedBatches)
           Sets the number of rowset batches that will be cached in the RowsetCursor.
 void setRefreshOptions(int newOptions)
           Sets the options used by the RowsetController.refresh() method for refreshing the rowset.
 void setRowsetBatchSize(int newRowsetBatchSize)
           Sets the number of records in each batch in the rowset.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

browseFieldsValues

public Records browseFieldsValues(Fields browseFields,
                                  int cLimit)
                           throws ReportSDKException
For internal use only

Throws:
ReportSDKException

browseFieldValues

public Values browseFieldValues(IField field,
                                int cLimit)
                         throws ReportSDKException

Allows you to browse the values for a particular field in one of the tables from the database server. The retrieved data is not filtered, and the values are all unique; duplicate values are discarded. The data will be retrieved first from the client's cache--if it is available--and then from the server's cache. If the data is not in either cache, it is retrieved from the database.

Use the canBrowseField method to see if a particular field has data that can be browsed.

Parameters:
field - The field whose values are to be examined. A field can be retrieved using the getDatabase method in the DatabaseController object.
cLimit - The maximum number of records that will be returned from the database. If this property is 0 or less, then the DefaultNumOfBrowsingRecords will be retrieved when the report is refreshed.
Returns:
A Values object containing the values to be browsed.
Throws:
ReportSDKException

browseTableValues

public Records browseTableValues(ITable table,
                                 int cLimit)
                          throws ReportSDKException

Allows you to browse the values for any field in the specified table from the database server. The data will be retrieved first from the client's cache--if it is available--and then from the server's cache. If the data is not in either cache, it is retrieved from the database.

Parameters:
table - The table whose field values are to be examined. A table may be retrieved using the getDatabase method in the DatabaseController object, DataDefController object, or ReportClientDocument object.
cLimit - The maximum number of records that will be returned from the database. If this property is 0 or less, the DefaultNumOfBrowsingRecords will be retrieved when the report is refreshed.
Returns:
A Records object containing the values you wish to browse.
Throws:
ReportSDKException

canBrowseTable

public boolean canBrowseTable(ITable table)
For internal use only


canBrowseField

public boolean canBrowseField(IField field)

Returns true if a given field has data that can be browsed, and false otherwise. Before using the browseFieldValues method, use this method to see if a particular field has data that can be browsed.

Parameters:
field - The field for which browse information is requested.
Returns:
true if a given field has data that can be browsed, and false otherwise.

clearClientCaches

public void clearClientCaches()
For internal use only


createCursor

public RowsetCursor createCursor(IGroupPath groupPath,
                                 IRowsetMetaData metaData)
                          throws ReportSDKException

Creates a cursor to navigate the set of data fetched from the server. Creating a RowsetCursor object results in the creation of a Rowset object whose data is based on the specified group path. Use the RowsetCursor object's getRowset() method to retrieve the Rowset object.

By default, the metadata contains fields belonging to the next level. The exception is when the group level is 0; in this case, the grand total is returned, as well as the fields belonging to group level 1. If no group path is specified, then the result fields and the group condition fields are used as data fields

Parameters:
groupPath - This indicates which rowset will be retrieved. Use null to specify no group path.
metaData - The fields to be included in the rowset. This object must contain the desired fields for which you want data. If the fields are not added to the DataDefinition object's ResultFields collection, then the corresponding columns may be empty. The cursor supports the special field ReportPath; add this special field type as crSpecialFieldTypeReportPath to the metadata. By default, the RowsetController object adds a special field RecordKey to the end of the metadata of the resultant Rowset object.
Returns:
An ICursor object containing the newly created cursor.
Throws:
ReportSDKException -

emptyBatch

public void emptyBatch(IRowset rowset,
                       int batchNumber)
                throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

fetchRowsetBatchByRowN

public void fetchRowsetBatchByRowN(IGroupPath groupPath,
                                   IRowset rowset,
                                   int rowNumber)
                            throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

findRowNByRecordKey

public int findRowNByRecordKey(RowsetCursor cursor,
                               int recordKey)
                        throws ReportSDKException

Returns the row number given a record key; it converts the record number to a row number if the record numbers in the rowset are not consecutive. This method is useful since the records in the Totaller are not stored in consecutive order if grouping, sorting, or filtering is applied. Additionally, the nodes in the Totaller do not store the row number from which the record came; they only store the record's key.

Parameters:
cursor - The cursor object that contains the rowset that was fetched from the server.
recordKey - The key of the record for which the row number is requested. A key may be obtained using the TotallerNode to which the record belongs.
Returns:
An int that specifies the row number of the given record key.
Throws:
ReportSDKException

getDefaultMetaData

public IRowsetMetaData getDefaultMetaData(IGroupPath pGroupPath)
For internal use only.


getDefaultNumOfBrowsingRecords

public int getDefaultNumOfBrowsingRecords()

Returns the number of records that are retrieved when using the various browse methods (browseFieldValues method, browseTableValues method) that examine the contents of the report's database.

The default value is 100. If this property is -1, then all records will be retrieved when the report is refreshed (not recommended).

Returns:
An int that specifies the number of records that are retrieved when using various browse methods.
See Also:
RowsetController.setDefaultNumOfBrowsingRecords(int)

getFirstRecordKey

public int getFirstRecordKey(IGroupPath pGroupPath)
                      throws ReportSDKException

Returns the record key for the first record under the specified group path.

Parameters:
pGroupPath - The group path from the Totaller indicating which record you require a key for.
Returns:
An int that specifies the record key for the first record under the specified group path.
Throws:
ReportSDKException

getMaxNumOfRecords

public int getMaxNumOfRecords()

Returns the maximum number of records that are to be retrieved from the database. The default value is -1, which means that all records will be retrieved when the report is refreshed. The entire result set needs to be retrieved in order for summaries, such as grand totals, to be correct.

Returns:
An int that specifies the maximum number of records that are to be retrieved from the database.
See Also:
RowsetController.setMaxNumOfRecords(int)

applyParameterFields

public void applyParameterFields(RowsetRequest request)
For internal use only.


getRefreshOptions

public int getRefreshOptions()

Returns the options used by the RowsetController.refresh() method for refreshing the rowset.

Returns:
An int that specifies the refresh options used when refreshing the rowset.
See Also:
RowsetController.setRefreshOptions(int)

getRowset

public IRowset getRowset(IGroupPath groupPath,
                         IRowsetMetaData metaData)
                  throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

getRowsetBatchSize

public int getRowsetBatchSize()

Returns the number of records in each batch in the rowset. The default value is 100. Specify -1 to retrieve all records in one batch.

Returns:
An int that specifies the number of records in each batch in the rowset.
See Also:
RowsetController.setRowsetBatchSize(int)

getSQLStatement

public java.lang.String getSQLStatement(IGroupPath groupPath,
                                        java.lang.String specialStatement)
                                 throws ReportSDKException

Returns the SQL statement that is used to return records from the database. If the database does not support SQL, the returned string will be empty. The SQL statement may differ depending on the GroupPath for push-down group-by reports; the grouping for these reports is done on the database server.

Parameters:
groupPath - The group path from the Totaller indicating which records you require an SQL statement for.
specialStatement - Reserved for future use.
Returns:
A String that specifies the SQL statement used to return records from the database.
Throws:
ReportSDKException

getSubTotallerNodes

public TotallerNodes getSubTotallerNodes(IGroupPath parentGroup)
                                  throws ReportSDKException

Returns the subnodes that belong to the root node of a specified parent group path.

Parameters:
parentGroup - This is the group path to the parent of the nodes you want to retrieve. That is, the subnodes from the node represented by this group path will be retrieved.
Returns:
A TotallerNodes object containing the subnodes that belong to the root node of a specified parent group path.
Throws:
ReportSDKException -

getTotallerNode

public ITotallerNode getTotallerNode(IGroupPath pGroupPath)
                              throws ReportSDKException

Returns the TotallerNode object in the given group path.

Parameters:
pGroupPath - The group path of the node you want to retrieve. Use null to retrieve the root Totaller node.
Returns:
The ITotallerNode object in the given group path.
Throws:
ReportSDKException

isServerCacheFilled

public boolean isServerCacheFilled()
                            throws ReportSDKException

For internal use only.

Throws:
ReportSDKException

refresh

public void refresh()
             throws ReportSDKException

Clears both the client's cache and the server's cache. The next time data is requested, it will be retrieved directly from the database.

You must call refresh() explicitly whenever you make changes to the report that require a different set of records to be fetched from the database server. For example, if you modify links or delete a record selection filter, you will want to hit the database in order to retrieve the latest records. The only exception is when a new column is added; when you add a new result field to the report, the database will be hit automatically.

Throws:
ReportSDKException -

setDefaultNumOfBrowsingRecords

public void setDefaultNumOfBrowsingRecords(int defaultNumOfBrowsingRecords)

Sets the number of records that are retrieved when using the various browse methods (browseFieldValues method, browseTableValues method) that examine the contents of the report's database.

The default value is 100. If this property is -1, then all records will be retrieved when the report is refreshed (not recommended).

Parameters:
defaultNumOfBrowsingRecords - An int that specifies the number of records that are retrieved when using various browse methods.
See Also:
RowsetController.getDefaultNumOfBrowsingRecords()

setMaxNumOfRecords

public void setMaxNumOfRecords(int maxNumOfRecords)

Sets the maximum number of records that are to be retrieved from the database. The default value is -1, which means that all records will be retrieved when the report is refreshed. The entire result set needs to be retrieved in order for summaries, such as grand totals, to be correct.

Parameters:
maxNumOfRecords - An int that specifies the maximum number of records that are to be retrieved from the database.
See Also:
RowsetController.getMaxNumOfRecords()

setNumOfCachedBatches

public void setNumOfCachedBatches(int maxNumOfCachedBatches)

Sets the number of rowset batches that will be cached in the RowsetCursor. The RowsetCursor object created by createCursor method inherits this number. The default value is -1, which means that all batches will be cached. If you are iterating through a large data set, you may want to set this value to a positive integer. For example, if you set the value to 2, then only two batches will be kept in memory.

Parameters:
maxNumOfCachedBatches - The maximum number of rowset batches that will be cached in the RowsetCursor.

setRefreshOptions

public void setRefreshOptions(int newOptions)

Sets the options used by the RowsetController.refresh() method for refreshing the rowset.

Parameters:
newOptions - An int that specifies the refresh options used when refreshing the rowset.
See Also:
RowsetController.getRefreshOptions()

setRowsetBatchSize

public void setRowsetBatchSize(int newRowsetBatchSize)

Sets the number of records in each batch in the rowset. The default value is 100. Specify -1 to retrieve all records in one batch.

Parameters:
newRowsetBatchSize - An int that specifies the number of records in each batch in the rowset.
See Also:
RowsetController.getRowsetBatchSize()

performFetchRowsetRequest

public ResultInfo performFetchRowsetRequest(RowsetRequest request,
                                            int requestOptions,
                                            java.lang.Object additionalFetchRowsetInfo)
                                     throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

performFetchSearchResultRequest

public ResultInfo performFetchSearchResultRequest(RowsetRequest request,
                                                  int requestOptions,
                                                  java.lang.Object additionalFetchSearchResultInfo)
                                           throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

fireOnRowsetMoreBatchChanged

public void fireOnRowsetMoreBatchChanged(IRowset rowset,
                                         int batchNumber)
For internal use only.


fireOnRowsetBatchChanged

public void fireOnRowsetBatchChanged(IGroupPath groupPath,
                                     IRowset rowset)
For internal use only.


fireOnSearchResultChanged

public void fireOnSearchResultChanged(RowsetSearchResult searchHandle,
                                      boolean moreRecords)
For internal use only.


getLOVRowsetProcessorHost

public LOVRowsetProcessorHost getLOVRowsetProcessorHost()
                                                 throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

getProductLocale

public java.util.Locale getProductLocale()