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

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

public class SubreportController
extends java.lang.Object

Use the SubreportController object to import a report as a subreport and to add or remove subreport links. In addition, this object can be used to retrieve the names of all of the subreports in a report. Use the subreport name to access the associated SubreportClientDocument object, which provides access to the various controllers that are necessary to modify a subreport. You can also use the subreport name to get a list of tables in the subreport, or to set a table's database to a different location.

The SubreportObject object is defined in the com.crystaldecisions.sdk.occa.report.definition package. Use this object to access subreport properties such as layout and formatting of the subreport.


Method Summary
 ISubreportClientDocument getSubreport(java.lang.String subreportName)
           Returns the specified Subreport object.
 IDatabase getSubreportDatabase(java.lang.String subreportName)
           Returns the subreport's Database object, which contains a collection of tables from one or more databases.
 SubreportLinks getSubreportLinks(java.lang.String subreportName)
           Returns the SubreportLinks object, which contains the links between the main report fields and the subreport fields.
 IStrings getSubreportNames()
           Returns a list of the names of subreports that are contained in a report.
 SubreportObject getSubreportObject(java.lang.String subreportName)
          For internal use only.
 ISubreportClientDocument importSubreport(java.lang.String name, java.lang.String reportURL, ISection section)
           Imports an existing report as a subreport and sets intelligent default values for left, top, width, and height.
 ISubreportClientDocument importSubreport(java.lang.String name, java.lang.String reportURL, ISection section, int left, int top, int width, int height)
           Imports an existing report as a subreport with user-defined values for left, top, width, and height.
 IStrings querySubreportNames()
          Deprecated. As of Version 11. Use the getSubreportNames() method instead.
 void setDataSource(java.lang.String subreportName, IDataSet dataSet, java.lang.String oldTableAlias, java.lang.String newTableName)
          Updates the data source on the subreport using the specified dataset.
 void setDataSource(java.lang.String subreportName, IXMLDataSet dataSet, java.lang.String oldTableAlias, java.lang.String newTableName)
          Updates the data source on the subreport using the specified dataset.
 void setDataSource(java.lang.String subreportName, java.lang.Object newDataSource)
           Updates the data source on the subreport using the specified object.
 void setDataSource(java.lang.String subreportName, java.sql.ResultSet dataSet, java.lang.String oldTableAlias, java.lang.String newTableName)
           Updates the data source on the subreport using the specified dataset.
 void setSubreportLinks(java.lang.String subreportName, SubreportLinks subreportLinks)
           Sets the SubreportLinks object, which contains the links between the main report fields and the subreport fields.
 void setTableLocation(java.lang.String subreportName, ITable curTable, ITable newTable)
           Sets the location of a table to a database that is different from the one originally specified when creating the subreport.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getSubreportDatabase

public IDatabase getSubreportDatabase(java.lang.String subreportName)
                               throws ReportSDKException

Returns the subreport's Database object, which contains a collection of tables from one or more databases.

Example:

This sample shows how to use the SubreportController to return and modify a SubreportClientDocument. The SubreportClientDocument provides access to the report data definition and controllers that are required to modify a subreport. Properties that can be accessed include the name, database controller, data definition controller, search controller, rowset controller, report definition controller, enable on demand, and report options of the SubreportClientDocument.

 SubreportController subreportController = clientDoc.getSubreportController();
 ISubreportClientDocument subreportClientDocument = subreportController.getSubreport("subreportName");
 subreportClientDocument.setEnableOnDemand(true);
 

Parameters:
subreportName - The name of the subreport.
Returns:
An IDatabase containing a collection of tables from one or more databases.
Throws:
ReportSDKException

querySubreportNames

public IStrings querySubreportNames()
                             throws ReportSDKException
Deprecated. As of Version 11. Use the getSubreportNames() method instead.

Returns a list of the names of subreports contained in a report. Use this method to retrieve the name of a subreport whose table you want to retrieve or set a new database location for.

Returns:
An IStrings object containing a list of the names of subreports contained in a report.
Throws:
ReportSDKException

getSubreportNames

public IStrings getSubreportNames()
                           throws ReportSDKException

Returns a list of the names of subreports that are contained in a report.

Returns:
An IStrings object containing a list of the names of subreports contained in a report.
Throws:
ReportSDKException

setTableLocation

public void setTableLocation(java.lang.String subreportName,
                             ITable curTable,
                             ITable newTable)
                      throws ReportSDKException

Sets the location of a table to a database that is different from the one originally specified when creating the subreport. Use this method to change the location of a database table that is active in a subreport. This is especially useful if a subreport uses a database that has a different location on your system, or if you have changed the directory or disk location of a database.

Note: This method does not physically move the database. It simply looks for the database table in a location other than the one originally specified when setting up the subreport.

This method also allows you to change the database driver DLL being used. For example, you can change from crdb_odbc.dll to crdb_oracle.dll. See the Crystal Reports Developer Runtime Help for a list of database driver DLLs.

Parameters:
subreportName - The name of the subreport.
curTable - The table whose database location you want to change.
newTable - The new table. Set database information for this table using the ITable object and its setConnectionInfo method. The subreport's collection of tables can be retrieved with the getSubreportDatabase method.
Throws:
ReportSDKException

setDataSource

public void setDataSource(java.lang.String subreportName,
                          java.sql.ResultSet dataSet,
                          java.lang.String oldTableAlias,
                          java.lang.String newTableName)
                   throws ReportSDKException

Updates the data source on the subreport using the specified dataset.

Parameters:
subreportName - the name of the subreport whose data source you will update
dataSet - the new java.sql.ResultSet object that will replace the existing data source
oldTableAlias - the alias of the current table. This is an optional parameter that can be an empty string. If it is an empty string, RAS will look at each table name and attempt to find a matching table in the new dataset as a replacement. If no matching table is found, the original table will be kept.
newTableName - the name of the table from the dataSet. This parameter will be ignored if the dataSet parameter is a Crystal Business View object. This is an optional parameter that can be an empty string. If it is an empty string and oldTableAlias is a valid name, the old table name will be used as the new table name. If the oldTableAlias parameter is an empty string, this parameter must also be an empty string.
Throws:
ReportSDKException

setDataSource

public void setDataSource(java.lang.String subreportName,
                          IDataSet dataSet,
                          java.lang.String oldTableAlias,
                          java.lang.String newTableName)
                   throws ReportSDKException
Updates the data source on the subreport using the specified dataset.

Parameters:
subreportName - the name of the subreport whose data source you will update
dataSet - the new IDataSet object that will replace the existing data source
oldTableAlias - the alias of the current table. This is an optional parameter that can be an empty string. If it is an empty string, RAS will look at each table name and attempt to find a matching table in the new dataset as a replacement. If no matching table is found, the original table will be kept.
newTableName - the name of the table from the dataSet. This parameter will be ignored if the dataSet parameter is a Crystal Business View object. This is an optional parameter that can be an empty string. If it is an empty string and oldTableAlias is a valid name, the old table name will be used as the new table name. If the oldTableAlias parameter is an empty string, this parameter must also be an empty string.
Throws:
ReportSDKException

setDataSource

public void setDataSource(java.lang.String subreportName,
                          java.lang.Object newDataSource)
                   throws ReportSDKException

Updates the data source on the subreport using the specified object.

NOTE: The BusinessView object is only supported when you are running managed RAS (RAS is running as part of BusinessObjects Enterprise). You must query BusinessObjects Enterprise to retrieve a BusinessView. The Query should be in the form "Select SI_CUID from CI_APPOBJECTS WHERE SI_NAME = 'YourBusinessView'" Pass the object you get from the query into the setDataSource method. See the BusinessObjects Enterprise Java SDK Guide for how to query the InfoStore.

Parameters:
subreportName - the name of the subreport whose data source you will update
newDataSource - the object to be added. Can be a DataSet, java.sql.ResultSet, or BusinessView object.
Throws:
ReportSDKException

setDataSource

public void setDataSource(java.lang.String subreportName,
                          IXMLDataSet dataSet,
                          java.lang.String oldTableAlias,
                          java.lang.String newTableName)
                   throws ReportSDKException
Updates the data source on the subreport using the specified dataset.

Parameters:
subreportName - the name of the subreport whose data source you will update
dataSet - the new java.sql.IXMLDataSet object that will replace the existing data source
oldTableAlias - the alias of the current table. This is an optional parameter that can be an empty string. If it is an empty string, RAS will look at each table name and attempt to find a matching table in the new dataset as a replacement. If no matching table is found, the original table will be kept.
newTableName - the name of the table from the dataSet. This parameter will be ignored if the dataSet parameter is a Crystal Business View object. This is an optional parameter that can be an empty string. If it is an empty string and oldTableAlias is a valid name, the old table name will be used as the new table name. If the oldTableAlias parameter is an empty string, this parameter must also be an empty string.
Throws:
ReportSDKException

importSubreport

public ISubreportClientDocument importSubreport(java.lang.String name,
                                                java.lang.String reportURL,
                                                ISection section)
                                         throws ReportSDKException

Imports an existing report as a subreport and sets intelligent default values for left, top, width, and height.

This method sets intelligent default values for left, top, width, and height. The default values for the left and top positions of the subreport are 0 (in twips). These positions are relative to the section where the subreport is imported. The default value for the height and width of the subreport is the height and width of the section where the subreport is imported.

NOTE: If the reportURL is empty, a blank report will be imported. This method returns the imported report as a subreport object.

Parameters:
name - the name of the report to import as a subreport
reportURL - the URL of the report to import. The URL must be an absolute physical path accessible to the client SDK. Web URLs and file paths managed by BusinessObjects Enterprise are not currently supported.
section - the section of the report into which the subreport is imported
Throws:
ReportSDKException

importSubreport

public ISubreportClientDocument importSubreport(java.lang.String name,
                                                java.lang.String reportURL,
                                                ISection section,
                                                int left,
                                                int top,
                                                int width,
                                                int height)
                                         throws ReportSDKException

Imports an existing report as a subreport with user-defined values for left, top, width, and height.

NOTE: If the reportURL is empty, a blank report will be imported. This method returns the imported report as a subreport object.

Parameters:
name - the name of the report to import as a subreport
reportURL - the URL of the report to import. The URL must be an absolute physical path accessible to the client SDK. Web URLs and file paths managed by BusinessObjects Enterprise are not currently supported.
section - the section of the report into which the subreport is imported
left - the position of the subreport object relative to the left of the section (in twips)
top - the position of the subreport object relative to the top of the section (in twips)
width - the width of the subreport object (in twips)
height - the height of the subreport object (in twips)
Throws:
ReportSDKException

getSubreport

public ISubreportClientDocument getSubreport(java.lang.String subreportName)
                                      throws ReportSDKException

Returns the specified Subreport object.

Note: Use the getSubreportNames method to get the names of the subreports in a report.

Parameters:
subreportName - The name of the subreport.
Returns:
An ISubreportClientDocument object.
Throws:
ReportSDKException

getSubreportLinks

public SubreportLinks getSubreportLinks(java.lang.String subreportName)
                                 throws ReportSDKException

Returns the SubreportLinks object, which contains the links between the main report fields and the subreport fields.

Parameters:
subreportName - The name of the subreport.
Returns:
An SubreportLinks object, which contains the links between the main report fields and the subreport fields..
Throws:
ReportSDKException

setSubreportLinks

public void setSubreportLinks(java.lang.String subreportName,
                              SubreportLinks subreportLinks)
                       throws ReportSDKException

Sets the SubreportLinks object, which contains the links between the main report fields and the subreport fields.

Parameters:
subreportName - The name of the subreport.
subreportLinks - The SubreportLinks object, which contains the links between the main report fields and the subreport fields.
Throws:
ReportSDKException

getSubreportObject

public SubreportObject getSubreportObject(java.lang.String subreportName)
                                   throws ReportSDKException
For internal use only.

Throws:
ReportSDKException