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

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

public class DatabaseController
extends java.lang.Object

This object is used to manipulate the Database objects that are contained in a report. It allows you to add, modify, remove, and link tables.


Method Summary
 void addConnection(IConnection connection)
          For internal use only.
 void addDataSource(java.util.Collection domainData, java.lang.Class domainClass)
           
 void addDataSource(IXMLDataSet newDataSet)
           Adds an IXMLDataSet as a data source for the report.
 void addDataSource(java.lang.Object newDataSource)
           Adds a new data source to the report.
 void addDataSource(java.sql.ResultSet data)
           Adds a java.sql.ResultSet or RAS data set as a data source for the report.
 void addTable(ITable table, TableJoins relatedTableJoins)
           Adds a new table from the data source to the report.
 void addTableJoin(ITableJoin tableJoin)
           Joins two tables by linking one or more fields between them.
 boolean canExecuteSQL()
           Returns true if the database supports SQL, and false otherwise.
 VerifyDatabaseFeedbacks checkDatabase(boolean pushedDataSourceOnly)
          For internal use only.
 void closeConnection(IConnection connection)
          Closes the specified data source connection.
 IConnectionInfo findConnectionInfoByDBServerName(java.lang.String serverName)
          Returns the IConnectionInfo object, when that object is found by a search for the server name.
 ITableJoin findTableJoin(int fromTableIndex, int toTableIndex)
          Returns the join between two tables, if one exists.
 ITableJoin findTableJoin(java.lang.Object fromTable, java.lang.Object toTable)
          Returns the join between two tables, if one exists.
 BlobFieldImageAttributes getBlobFieldImageAttributes(IDBField dbField)
          For internal use only.
 ConnectionInfos getConnectionInfos(PropertyBag promptProperties)
           Returns the collection of all database logons that exist in a report.
 IDatabase getDatabase()
           Returns the tables and fields available in the report.
 IStrings getServerNames()
          Returns the names of all servers used in the report.
 boolean isConnectionOpen(IConnection connection)
          Checks if the specified data source connection is open.
 void logon(IConnectionInfo connectionInfo, java.lang.String sUser, java.lang.String sPassWord)
          Sets the logon information for a specified data source connection.
 void logon(java.lang.String sUser, java.lang.String sPassword)
           Sets all of the tables in the report with a specified user name and password.
 void logonEx(java.lang.String sServerName, java.lang.String sDatabaseName, java.lang.String sUser, java.lang.String sPassword)
           Sets the user and password on the specified server and database.
 Strings mapFields(FieldMappingInfos mapInfos)
          Maps database fields to new locations based on the information specified by a FieldMappingInfos collection.
 void modifyFieldHeading(IDBField dbField, java.lang.String newFieldHeadingText)
          For internal use only.
 void modifyTableAlias(ITable table, java.lang.String newTableAlias)
           Modifies the table's alias.
 void modifyTableConnectionInfo(java.lang.String tableAlias, IConnectionInfo newConnectionInfo)
          Deprecated. As of Version 10, replaced by logon and logonEx
 void modifyTableJoin(ITableJoin oldTableJoin, ITableJoin newTableJoin)
           Modifies the join options of a join between two tables.
 void openConnection(IConnection connection)
          Opens the specified data source connection.
 void removeConnection(IConnection connection)
          For internal use only.
 void removeTable(java.lang.String tableAlias)
           Removes a table from the report.
 void removeTableJoin(ITableJoin tableJoin)
           Removes a join between two tables.
 void replaceConnection(IConnection oldConnection, IConnection newConnection, int options)
          Changes the database location of a report at runtime.
 void replaceConnection(IConnectionInfo oldConnection, IConnectionInfo newConnection, Fields parameterFields, int options)
          Changes the database location of a report at runtime.
 void setConnectionInfos(ConnectionInfos connectionInfos)
          Sets database logon information in the report.
 void setDataSource(java.util.Collection domainData, java.lang.Class domainClass, java.lang.String oldTableAlias, java.lang.String newTableName)
           
 void setDataSource(IDataSet dataSet, java.lang.String oldTableAlias, java.lang.String newTableName)
           Updates the data source used by the report with the specified IDataSet data set.
 void setDataSource(IXMLDataSet dataSet, java.lang.String oldTableAlias, java.lang.String newTableName)
           Updates the data source used by the report with the specified IXMLDataSet data set.
 void setDataSource(java.lang.Object newDataSource)
           Updates the data source used by the report.
 void setDataSource(java.sql.ResultSet dataSet, java.lang.String oldTableAlias, java.lang.String newTableName)
           Updates the data source used by the report with the specified java.sql.ResultSet or RAS data set.
 void setJNDIOptionalName(IConnectionInfo connectionInfo, java.lang.String optionalName)
          For internal use only.
 void setTableLocation(ITable curTable, ITable newTable)
           Sets the location of a table to a database that is different from the one originally specified when creating the report.
 void setTableLocation(ITable curTable, ITable newTable, FieldMappingInfos fieldInfos)
          This method is the same as setTableLocationEx(ITable, ITable), except it will try to use the given FieldMappingInfos to map the fields to the new location.
 void setTableLocationByServerDatabaseName(java.lang.String tableAlias, java.lang.String serverName, java.lang.String databaseName, java.lang.String userName, java.lang.String password)
           Sets the location of a table to a database, when the report uses a database that is different from the one that was specified when the report was created.
 void setTableLocationEx(int curTableIndex, java.lang.Object newObject)
          Sets the location of a table to a database, when the report uses a database that is different from the one that was specified when the report was created.
 void setTableLocationEx(java.lang.Object curTable, java.lang.Object newObject)
          Sets the location of a table to a database, when the report uses a database that is different from the one that was specified when the report was created.
 void setTableLocationEx(java.lang.Object curTable, java.lang.Object newObject, FieldMappingInfos fieldInfos)
          This method is the same as setTableLocationEx(Object, Object), except it will try to use the given FieldMappingInfos to map the fields to the new location.
 boolean verifyTableConnectivity(int tableIndex)
           Tests the status of the database connection to a table by querying the server to see if a connection to this table is active.
 boolean verifyTableConnectivity(java.lang.Object table)
           Tests the status of the database connection to a table by querying the server to see if a connection to this table is active.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

addDataSource

public void addDataSource(java.sql.ResultSet data)
                   throws ReportSDKException

Adds a java.sql.ResultSet or RAS data set as a data source for the report. To set a runtime data source into a report, the report must be created with a data source using Crystal Reports, or added to the report using this, or one of the other three add methods. Set the data source in the report using the setDataSource method.

Parameters:
data - the java.sql.ResultSet object to be added
Throws:
ReportSDKException

addDataSource

public void addDataSource(java.util.Collection domainData,
                          java.lang.Class domainClass)
                   throws ReportSDKException
Throws:
ReportSDKException

addDataSource

public void addDataSource(java.lang.Object newDataSource)
                   throws ReportSDKException

Adds a new data source to the report. To set a runtime data source into a report, the report must be created with a data source using Crystal Reports, or added to the report using this, or one of the other three add methods. Set the data source in the report using the setDataSource method.

NOTE: This method is only supported when you are running managed RAS (RAS is running as part of BusinessObjects Enterprise).

Parameters:
newDataSource - the object to be added. Can be a DataSet, java.sql.ResultSet, IXMLDataSet, or BusinessView object.
Throws:
ReportSDKException

addDataSource

public void addDataSource(IXMLDataSet newDataSet)
                   throws ReportSDKException

Adds an IXMLDataSet as a data source for the report. To set a runtime data source into a report, the report must be created with a data source using Crystal Reports, or added to the report using this, or one of the other three add methods. Set the data source in the report using the setDataSource method.

Parameters:
newDataSet - the IXMLDataSet object to be added
Throws:
ReportSDKException

addTable

public void addTable(ITable table,
                     TableJoins relatedTableJoins)
              throws ReportSDKException

Adds a new table from the data source to the report. This method does not place any fields on the report itself. Rather, it makes the table available for selection by the user. Therefore, to add the table, the ConnectionInfo must be correct, but the fields do not have to be specified.

Parameters:
table - The new table to be added. If the table you are adding to the report requires logon information, and this logon information has not been set, this method will fail.
relatedTableJoins - An ITableJoins object that represents how tables are linked in the report. May be null.
Throws:
ReportSDKException
See Also:
Setting ConnectionInfo

addTableJoin

public void addTableJoin(ITableJoin tableJoin)
                  throws ReportSDKException

Joins two tables by linking one or more fields between them. If the tables are already joined, the existing table join properties are modified. Note: This method fails if the table join requires logon information and the logon information has not already been set. See the setConnectionInfos method.

Parameters:
tableJoin - The ITableJoin object that specifies how the two tables are joined.
Throws:
ReportSDKException

canExecuteSQL

public boolean canExecuteSQL()

Returns true if the database supports SQL, and false otherwise. This method returns true only if all connections are SQL executable.

Returns:
true if the database supports SQL, and false otherwise.

getConnectionInfos

public ConnectionInfos getConnectionInfos(PropertyBag promptProperties)
                                   throws ReportSDKException

Returns the collection of all database logons that exist in a report. This method returns logon information for both reports and subreports. You can obtain similar information using the getConnectionInfo() method in the Table object; however, this method does not return the logon information for subreports.

Logon information must be set using the modifyTableConnectionInfo method or the setConnectionInfos method. The setConnectionInfos method handles subreports, whereas the modifyTableConnectionsInfos does not.

As of version 11, managed RAS will respect the custom database logon settings specified in the Central Management Console (CMC). For example:

In most cases, the database connection information that is returned is the most recent database connection information. But if a report that is saved with data is published to the CMC, the RAS returns the database logon settings that belong to the saved data, rather than the custom database logon settings that were published to the CMC.

CMC database connection settings are applied when the saved data is regenerated automatically when, for example, a parameter value is changed, the report data is refreshed, a new field is added or referenced in the report, and so on.

Parameters:
promptProperties - Information about the database logons and parameter prompts that are to be returned when the user makes a request to view a report or subreport.
Returns:
A ConnectionInfos object containing a collection of all database logons that exist in a report.
Throws:
ReportSDKException
See Also:
setConnectionInfos

getDatabase

public IDatabase getDatabase()

Returns the tables and fields available in the report. Note, to modify any database property, you must use the methods in the DatabaseController object. These methods also allow you to add and remove tables or fields.

Returns:
An IDatabase object containing the tables and fields available in the report.

getBlobFieldImageAttributes

public BlobFieldImageAttributes getBlobFieldImageAttributes(IDBField dbField)
                                                     throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

logon

public void logon(java.lang.String sUser,
                  java.lang.String sPassword)
           throws ReportSDKException

Sets all of the tables in the report with a specified user name and password. This is a helper function that applies logon information to all of the database connections used in the report; use this method instead of setting the ConnectionInfo for each.

Parameters:
sUser - the user name
sPassword - the password
Throws:
ReportSDKException

logon

public void logon(IConnectionInfo connectionInfo,
                  java.lang.String sUser,
                  java.lang.String sPassWord)
           throws ReportSDKException
Sets the logon information for a specified data source connection.

Parameters:
connectionInfo - the data source connection to set the username and password for
sUser - the user name
sPassWord - the password
Throws:
ReportSDKException

logonEx

public void logonEx(java.lang.String sServerName,
                    java.lang.String sDatabaseName,
                    java.lang.String sUser,
                    java.lang.String sPassword)
             throws ReportSDKException

Sets the user and password on the specified server and database.

Example:

This sample shows how to set the user name and password to enable users to log on to a secure database.

 DatabaseController databaseController = clientDoc.getDatabaseController();
 databaseController.logonEx("SERVERNAME", "Xtreme", "user1", "passwd");
 

Parameters:
sServerName - the name of the server on which the user and password is set
sDatabaseName - the name of the database on the specified server
sUser - the user name to be set on the server
sPassword - the password to be set on the server
Throws:
ReportSDKException

modifyFieldHeading

public void modifyFieldHeading(IDBField dbField,
                               java.lang.String newFieldHeadingText)
                        throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

modifyTableAlias

public void modifyTableAlias(ITable table,
                             java.lang.String newTableAlias)
                      throws ReportSDKException

Modifies the table's alias.

Remarks

Database names and locations often change. If you create a report and then change the name or location of a table or file, the Report Application Server must be able to find the new name or location. This is especially important when you create formulas in your report that access a table that has been renamed or moved. Fixing the reference for a single field is not difficult, but to find every formula that uses that field can be a difficult and time-consuming task.

To solve this problem, the Report Application Server uses aliases to refer to database tables and files. An alias is a string that serves as a unique identifier for a table. If you change the name or location of the database, the name of the alias does not change, so your formulas are not affected. The Report Application Server looks to the alias for the location and name of the database, goes to the new location for the database field, and executes the formula.

Parameters:
table - The table whose alias is to be modified. A table can be obtained by using the getDatabase method in the DatabaseController object, DataDefController object, or ReportClientDocument object.
newTableAlias - The new value for the alias.
Throws:
ReportSDKException

modifyTableConnectionInfo

public void modifyTableConnectionInfo(java.lang.String tableAlias,
                                      IConnectionInfo newConnectionInfo)
                               throws ReportSDKException
Deprecated. As of Version 10, replaced by logon and logonEx

Throws:
ReportSDKException

modifyTableJoin

public void modifyTableJoin(ITableJoin oldTableJoin,
                            ITableJoin newTableJoin)
                     throws ReportSDKException

Modifies the join options of a join between two tables. To modify table join options, find the table whose options you wish to change, clone() the ITableJoin object, modify the clone and then pass it to this method as the newTableLink parameter.

Parameters:
oldTableJoin - The original ITableJoin object.
newTableJoin - The modified ITableJoin object.
Throws:
ReportSDKException

removeTable

public void removeTable(java.lang.String tableAlias)
                 throws ReportSDKException

Removes a table from the report. If the table is being used because fields in the table are being displayed by the report, the method will notify the DataDefController. The DataDefController will remove all of the references to this table, as well as all of the table's links. Note, however, that while it removes related database fields, it will not remove parameter, SQL expression, or formula fields.

Parameters:
tableAlias - The alias of the table that is to be removed. A table's alias can be obtained by using the getDatabase method in the DatabaseController object, DataDefController object, or ReportClientDocument object.
Throws:
ReportSDKException

removeTableJoin

public void removeTableJoin(ITableJoin tableJoin)
                     throws ReportSDKException

Removes a join between two tables. To remove a join between two tables, find or create an ITableJoin whose source and target table aliases match the ones you are looking for, and then call removeTableJoin.

To remove all of the links to or from a particular table, remove all of the ITableJoin objects whose source or target table aliases match the given table alias.

Existing source and target table aliases can be obtained by using the getDatabase() method in the DatabaseController object, DataDefController object, or ReportClientDocument object.

Parameters:
tableJoin - An ITableJoin object specifying the source and target tables whose join should be removed. Existing joins can be obtained by using the getDatabase() method in the DatabaseController object, DataDefController object, or ReportClientDocument object.
Throws:
ReportSDKException

setConnectionInfos

public void setConnectionInfos(ConnectionInfos connectionInfos)
                        throws ReportSDKException

Sets database logon information in the report.

NOTE: It is recommended that you use the replaceConnection method, which is designed for enhanced performance, instead of this one.

This method sets the collection of database logons in the report to ConnectionInfos. It can be used in conjunction with the getConnectionInfos method to modify the collection. The setConnectionInfos and getConnectionInfos methods handle database information in both reports and subreports.

Note: If the table you are adding to the report requires logon information and this logon information has not been set, then the addTable method will fail.

As of version 11, managed RAS will respect the custom database logon settings specified in the Central Management Console (CMC). For example:

In most cases, the database connection information that is returned is the most recent database connection information. But if a report that is saved with data is published to the CMC, the RAS returns the database logon settings that belong to the saved data, rather than the custom database logon settings that were published to the CMC.

CMC database connection settings are applied when the saved data is regenerated automatically when, for example, a parameter value is changed, the report data is refreshed, a new field is added or referenced in the report, and so on.

Although the PromptProperties parameter is optional in VBScript, in JavaScript, you must supply it.

To apply the same logon information to all of the database connections in the report, use the logon method.

Parameters:
connectionInfos - The collection of database connections that users need to enter logon information for.
Throws:
ReportSDKException
See Also:
getConnectionInfos

setDataSource

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

Updates the data source used by the report with the specified java.sql.ResultSet or RAS data set. This sets a runtime data source into the report. The data that is used is not saved with the report; this means that the next time you open the report, you must reset the data source in order to see valid data.

To set a runtime data source into a report, the report must be created with a data source using Crystal Reports, or added to the report using the addDataSource(ResultSet) method.

Parameters:
dataSet - The java.sql.ResultSet object that will replace the current data source.
oldTableAlias - The alias of the current table. A table's alias can be obtained by using the getDatabase() method in the DatabaseController object, DataDefController object, or ReportClientDocument object. This parameter will be ignored if the data parameter is a Crystal Business View object. 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.util.Collection domainData,
                          java.lang.Class domainClass,
                          java.lang.String oldTableAlias,
                          java.lang.String newTableName)
                   throws ReportSDKException
Throws:
ReportSDKException

setDataSource

public void setDataSource(IDataSet dataSet,
                          java.lang.String oldTableAlias,
                          java.lang.String newTableName)
                   throws ReportSDKException

Updates the data source used by the report with the specified IDataSet data set. This sets a runtime data source into the report. The data that is used is not saved with the report; this means that the next time you open the report, you must reset the data source in order to see valid data.

To set a runtime data source into a report, the report must be created with a data source using Crystal Reports, or added to the report using the addDataSource(ResultSet) method.

Parameters:
dataSet - the IDataSet object that will replace the current data source
oldTableAlias - The alias of the current table that will be replaced with the new table specified by newTableName. A table's alias can be obtained by using the getDatabase() method in the DatabaseController object, DataDefController object, or ReportClientDocument object. 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. This parameter will be ignored if the dataSet parameter is a Crystal Business View object.
newTableName - The alias of the table from the dataSet that will replace the current table. This is an optional parameter that can be an empty string but cannot be null. 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. If both parameters contain a value, the table specified by newTableName will replace the table specified by oldTableAlias. Both tables need to be valid or an error will be thrown. This parameter will be ignored if the dataSet parameter is a Crystal Business View object.
Throws:
ReportSDKException

setDataSource

public void setDataSource(IXMLDataSet dataSet,
                          java.lang.String oldTableAlias,
                          java.lang.String newTableName)
                   throws ReportSDKException

Updates the data source used by the report with the specified IXMLDataSet data set. This sets a runtime data source into the report. The data that is used is not saved with the report; this means that the next time you open the report, you must reset the data source in order to see valid data.

To set a runtime data source into a report, the report must be created with a data source using Crystal Reports, or added to the report using the addDataSource(ResultSet) method.

The report that is created using this addDataSource method cannot be refreshed in the Crystal Reports designer.

Note: The data structure and the data in this object will persist with the report if the setEnableSaveDataWithReport is set to true. The report cannot reconnect to the original data source, since the XMLDataSet object and other objects that are used to construct it only exist at run-time. To reconnect to the original data source, you must create these objects and call setDataSource again.

Parameters:
dataSet - the IXMLDataSet object that will replace the current data source
oldTableAlias - The alias of the current table that will be replaced with the new table specified by newTableName. A table's alias can be obtained by using the getDatabase() method in the DatabaseController object, DataDefController object, or ReportClientDocument object. 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. This parameter will be ignored if the DataSource parameter is a Crystal Business View object.
newTableName - The alias of the table from the dataSet that will replace the current table. This is an optional parameter that can be an empty string but cannot be null. 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. If both parameters contain a value, the table specified by newTableName will replace the table specified by oldTableAlias. Both tables need to be valid or an error will be thrown. This parameter will be ignored if the dataSet parameter is a Crystal Business View object.
Throws:
ReportSDKException

setDataSource

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

Updates the data source used by the report. This sets a runtime data source into the report. The data that is used is not saved with the report; this means that the next time you open the report, you must reset the data source in order to see valid data.

To set a runtime data source into a report, the report must be created with a data source using Crystal Reports, or added to the report using the addDataSource(ResultSet) method.

NOTE: This method is only supported when you are running managed RAS (RAS is running as part of BusinessObjects Enterprise).

Parameters:
newDataSource - the object to be added. Can be a DataSet, java.sql.ResultSet, IXMLDataSet, or BusinessView object.
Throws:
ReportSDKException

setTableLocation

public void setTableLocation(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 report. Use this method to change the location of a database table that is active in a report. This is especially useful if a report 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: It is recommended that you use the replaceConnection method, which is designed for enhanced performance, instead of this one.

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 report.

Example:

This sample shows how to modify parameter values in a command or stored procedures table.

 DatabaseController databaseController = reportClientDocument.getDatabaseController();
 Tables tables = databaseController.getDatabase().getTables();
 Int index = 0;
 IProcedure table = (IProcedure)tables.getTable(index).clone(true);  
 ParameterField paramField = (ParameterField)table.getParameters().get(0);
 Values currentValues = new Values();
 ParameterFieldDiscreteValue parameterValue = new ParameterFieldDiscreteValue();
 parameterValue.setValue(new Integer (1));
 currentValues.add(parameterValue);
 paramField.setCurrentValues(currentValues);
 databaseController.setTableLocation(table, tables.getTable(index));
 

Parameters:
curTable - The table whose database location you want to change. A table can be obtained by using the getDatabase() method in the DatabaseController object, DataDefController object, or ReportClientDocument object.
newTable - The new table. Set database information for this table using the Table object and its setConnectionInfo method.
Throws:
ReportSDKException

setTableLocationByServerDatabaseName

public void setTableLocationByServerDatabaseName(java.lang.String tableAlias,
                                                 java.lang.String serverName,
                                                 java.lang.String databaseName,
                                                 java.lang.String userName,
                                                 java.lang.String password)
                                          throws ReportSDKException

Sets the location of a table to a database, when the report uses a database that is different from the one that was specified when the report was created. This database is defined by a server name and a database name.

NOTE: It is recommended that you use the replaceConnection method, which is designed for enhanced performance, instead of this one.

NOTE: This method does not support JDBC data sources.

If the serverName parameter is empty, only the location of the database is changed on the current database server. If the databaseName parameter is empty, only the server location is changed; therefore, you must ensure that a database exists on the new server, and that it uses the same name as the current database name. If both serverName and databaseName are null or empty, just the logon info is set. Use the setTableLocationByServerDatabaseName method to change the location of a database table that is active in a report. This is especially useful if a report uses a database that has a different location on your system, or if you have changed the directory or disk location of a database.

The setTableLocationByServerDatabaseName 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 report. This method and its parameters are specifically designed to connect to a SQL server database, but can also be used to connect to other database types. Regardless of the database type, this method should only be used to change the table location from one database type to another database of the same type.

Example:

This sample shows how to set the location of a table to a database or server with a DatabaseController. The DatabaseController manipulates the database objects that are contained in a report by adding, modifying, removing, and linking tables.

 DatabaseController databaseController = clientDoc.getDatabaseController();
 databaseController.setTableLocationByServerDatabaseName("Customer", "SERVERNAME", "Xtreme", "user1", "passwd");
 

Parameters:
tableAlias - the table alias of the table whose database location you want to change
serverName - the name of the new database server
databaseName - the name of the database to be used for the new location
userName - the user id to be used to logon to the new database
password - the password to be used to logon to the new database
Throws:
ReportSDKException

checkDatabase

public VerifyDatabaseFeedbacks checkDatabase(boolean pushedDataSourceOnly)
                                      throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

verifyTableConnectivity

public boolean verifyTableConnectivity(int tableIndex)
                                throws ReportSDKException

Tests the status of the database connection to a table by querying the server to see if a connection to this table is active.

Example:

This sample shows how to test the status of the database connection to a database table.

 DatabaseController databaseController = clientDoc.getDatabaseController();
 if ( databaseController.verifyTableConnectivity(0) )
 { 
 //Code
 }
 

Parameters:
tableIndex - the index of the table whose database connection status is tested
Returns:
true if connection to this table is active false otherwise
Throws:
ReportSDKException

verifyTableConnectivity

public boolean verifyTableConnectivity(java.lang.Object table)
                                throws ReportSDKException

Tests the status of the database connection to a table by querying the server to see if a connection to this table is active.

Parameters:
table - the table whose database connection status is tested. Can be a ITable object, alias of the table or the table index.
Returns:
true if connection to this table is active false otherwise
Throws:
ReportSDKException

getServerNames

public IStrings getServerNames()
                        throws ReportSDKException

Returns the names of all servers used in the report.

A report may have one or more database servers. getServerNames queries the names of all database servers for the report, stores them in the Strings collection, and returns a reference to the collection.

Example:

This sample shows how to get all the database servers that a report uses. A report may have one or more database servers.

 DatabaseController databaseController = clientDoc.getDatabaseController();
 IStrings serverNames = databaseController.getServerNames();
 out.println( serverNames.getString(0) );
 

Returns:
a reference to the Strings collection
Throws:
ReportSDKException
See Also:
Strings

findConnectionInfoByDBServerName

public IConnectionInfo findConnectionInfoByDBServerName(java.lang.String serverName)
                                                 throws ReportSDKException

Returns the IConnectionInfo object, when that object is found by a search for the server name. If no match is found, the return value is null.

Example:

This sample shows how to find a ConnectionInfo object using a server name.

 DatabaseController databaseController = clientDoc.getDatabaseController();
 IConnectionInfo connectionInfo = databaseController.findConnectionInfoByDBServerName("SERVERNAME");
 

Parameters:
serverName - the server name that is used in the search
Returns:
IConnectionInfo a reference to the IConnectionInfo object.
Throws:
ReportSDKException

findTableJoin

public ITableJoin findTableJoin(int fromTableIndex,
                                int toTableIndex)
                         throws ReportSDKException

Returns the join between two tables, if one exists.

Example:

This sample shows how to use a DatabaseController object to return an ITableJoin object, which represents a join between two tables in a report. The tables may be from different databases. One or more fields linked between the source and target tables are used to join the tables together.

 DatabaseController databaseController = clientDoc.getDatabaseController();
 ITableJoin join = databaseController.findTableJoin(0, 2);
 

Parameters:
fromTableIndex - the index of the table from which the join originates
toTableIndex - the index of the table where the join terminates
Returns:
ITableJoin the join between the two tables, or null if no match was found
Throws:
ReportSDKException

findTableJoin

public ITableJoin findTableJoin(java.lang.Object fromTable,
                                java.lang.Object toTable)
                         throws ReportSDKException
Returns the join between two tables, if one exists.

Parameters:
fromTable - the table from which the link originates. Can be Integer (table index), String (table alias) or ITable object.
toTable - the table where the link terminates. Can be Integer (table index), String (table alias) or ITable object.
Returns:
ITableJoin the join between the two tables, or null if no match was found
Throws:
ReportSDKException

setTableLocationEx

public void setTableLocationEx(java.lang.Object curTable,
                               java.lang.Object newObject)
                        throws ReportSDKException

Sets the location of a table to a database, when the report uses a database that is different from the one that was specified when the report was created.

NOTE: It is recommended that you use the replaceConnection method, which is designed for enhanced performance, instead of this one.

The parameters of this method provide greater flexibility than the parameters of the setTableLocation method.

Use the setTableLocationEx method to change the location of a database that is active in a report. This method is especially useful if a report uses a database that has a different location on your system, or if you have changed the directory or disk location of a database. The setTableLocationEx method does not physically move the database. It simply looks for the database table in a location other than the one that was originally specified when the report was created.

Example:

This sample shows how to set the location of a table to a database or server with a DatabaseController. The DatabaseController manipulates the database objects that are contained in a report. It adds, modifies, removes, and links tables.

 DatabaseController databaseController = clientDoc.getDatabaseController();
 IDatabase database = databaseController.getDatabase();
 Tables tables = database.getTables();
 Table curTable = (Table)tables.getTable(0);
 ITable newObject = (ITable)curTable.clone(true);
 databaseController.setTableLocationEx(curTable, newObject);
 

Parameters:
curTable - the table whose database location you want to change. Can be an Integer (table index), String (table alias) or ITable object
newObject - the new ITable object or IConnectionInfo object
Throws:
ReportSDKException

setTableLocationEx

public void setTableLocationEx(int curTableIndex,
                               java.lang.Object newObject)
                        throws ReportSDKException

Sets the location of a table to a database, when the report uses a database that is different from the one that was specified when the report was created.

NOTE: It is recommended that you use the replaceConnection method, which is designed for enhanced performance, instead of this one.

The parameters of this method provide greater flexibility than the parameters of the setTableLocation method.

Use the setTableLocationEx method to change the location of a database that is active in a report. This method is especially useful if a report uses a database that has a different location on your system, or if you have changed the directory or disk location of a database. The setTableLocationEx method does not physically move the database. It simply looks for the database table in a location other than the one that was originally specified when the report was created.

Parameters:
curTableIndex - the index of the table whose database location you want to change
newObject - the new ITable object or IConnectionInfo object
Throws:
ReportSDKException

replaceConnection

public void replaceConnection(IConnectionInfo oldConnection,
                              IConnectionInfo newConnection,
                              Fields parameterFields,
                              int options)
                       throws ReportSDKException

Changes the database location of a report at runtime.

This method is the most flexible way to change the data source connection information at runtime. With this method, you do not need to set registry keys to control the behavior of mapping fields or use the verifyDatabase method to ensure that the report is using the most current data scheme from the new database. With the replaceConnection method you can specify parameter values for stored procedures in the parameterFields parameter. In addition, the options parameter allows for the concatenation of DBOptions options.

Certain parameter fields are mapped to the new datasource by the RAS server. Refer to the following table to see which fields can be mapped properly:

From / ToStringDateNumberBinaryBlobMemo
String Yes Yes Yes Yes No No
Date Yes Yes Yes Yes No No
Number Yes Yes Yes Yes No No
Binary Yes Yes Yes Yes No No
Blob No No No No Yes No
Memo Yes No No No No Yes

Example:

This example shows how to replace a database connection with an XML datasource.

 IConnectionInfo oldConnectionInfo =  new ConnectionInfo();
 IConnectionInfo newConnectionInfo = new ConnectionInfo();
 String strQETokens = null;
 PropertyBag logonProperties = new PropertyBag();
 PropertyBag QElogonProperties = new PropertyBag();
 Fields pFields = null;
 DatabaseController dbController = clientDoc.getDatabaseController();
 oldConnectionInfo = dbController.getConnectionInfos(null).getConnectionInfo(0);                                        
 QElogonProperties.putStringValue("Local XML File", "c:/myXMLFile.xml");
 QElogonProperties.putStringValue("Local Schema File", "c:/mySchemaFile.xsd");          
 logonProperties.putStringValue("Database DLL", "crdb_xml");
 logonProperties.putStringValue("QE_DatabaseType", "XML");
 logonProperties.put("QE_LogonProperties", QElogonProperties);
 newConnectionInfo.setAttributes(logonProperties);
 newConnectionInfo.setKind(ConnectionInfoKind.from_string("CRQE"));
 dbController.replaceConnection(oldConnectionInfo, newConnectionInfo, pFields, 0);
 

Example:

This example shows how to concatenate DBOptions integer fields when using replaceConnection.

replaceConnection(oldConnection, newConnection, parameterFields, DBOptions._ignoreCurrentTableQualifiers + DBOptions._doNotVerifyDB);
 

Parameters:
oldConnection - The object that contains connnection information for the current database.
newConnection - The connnection object that specifies how to connect to the new database location.
parameterFields - The Fields collection that contains parameterFields from the report. This parameter is used to specify parameter values for stored procedures.
options - The integer that specifies what option to use when connecting to the new data source. You can also use DBOptions integer fields to specify this option. The DBOptions integer fields can also be concatenated to provide greater flexibility in connection options. See the example for more information.
Throws:
ReportSDKException

mapFields

public Strings mapFields(FieldMappingInfos mapInfos)
                  throws ReportSDKException

Maps database fields to new locations based on the information specified by a FieldMappingInfos collection. Each IFieldMappingInfo specifies a source field in the report and its new target field name, the subreport that uses the field, and the new data source connection info.

Refer to the following table to see which fields can be mapped properly:

From / ToStringDateNumberBinaryBlobMemo
String Yes Yes Yes Yes No No
Date Yes Yes Yes Yes No No
Number Yes Yes Yes Yes No No
Binary Yes Yes Yes Yes No No
Blob No No No No Yes No
Memo Yes No No No No Yes

Returns:
a Strings list of unmapped fields
Throws:
ReportSDKException
See Also:
IFieldMappingInfo

setJNDIOptionalName

public void setJNDIOptionalName(IConnectionInfo connectionInfo,
                                java.lang.String optionalName)
                         throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

setTableLocationEx

public void setTableLocationEx(java.lang.Object curTable,
                               java.lang.Object newObject,
                               FieldMappingInfos fieldInfos)
                        throws ReportSDKException
This method is the same as setTableLocationEx(Object, Object), except it will try to use the given FieldMappingInfos to map the fields to the new location. An error will be returned to the user if there is any incompatible map in the specified mapping infos.

Two fields are considered to be compatible for mapping, if one of the following is true:

  1. The FieldValueType of the source field and target field is the same
  2. Both source field and target field are of numeric type, or datetime type
  3. The source field is of memo type and the target field is of String type (Note that String to memo is not supported)

Parameters:
curTable - The table whose database location you want to change. Can be an Integer (table index), String (table alias) or ITable object.
newObject - The new ITable object or IConnectionInfo object
fieldInfos - A set of IFieldMappingInfo objects that describe how to map fields from the current table to the new table.
Throws:
ReportSDKException
See Also:
IFieldMappingInfo

setTableLocation

public void setTableLocation(ITable curTable,
                             ITable newTable,
                             FieldMappingInfos fieldInfos)
                      throws ReportSDKException
This method is the same as setTableLocationEx(ITable, ITable), except it will try to use the given FieldMappingInfos to map the fields to the new location. An error will be returned to the user if there is any incompatible map in the specified mapping infos.

Two fields are considered to be compatible for mapping, if one of the following is true:

  1. The FieldValueType of the source field and target field is the same
  2. Both source field and target field are of numeric type, or datetime type
  3. The source field is of memo type and the target field is of String type (Note that String to memo is not supported)

Parameters:
curTable - The table whose database location you want to change. A table can be obtained by using the getDatabase() method in the DatabaseController object, DataDefController object, or ReportClientDocument object.
newTable - The new table. Set database information for this table using the Table object and its setConnectionInfo method.
fieldInfos - A set of IFieldMappingInfo objects that describe how to map fields from the current table to the new table.
Throws:
ReportSDKException
See Also:
IFieldMappingInfo

addConnection

public void addConnection(IConnection connection)
                   throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

removeConnection

public void removeConnection(IConnection connection)
                      throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

replaceConnection

public void replaceConnection(IConnection oldConnection,
                              IConnection newConnection,
                              int options)
                       throws ReportSDKException
Changes the database location of a report at runtime.

See the replaceConnection method for more info, which is the same, except that it also allows you to specify parameters for stored procedures.

Parameters:
oldConnection - The object that contains connnection information for the current database.
newConnection - The connnection object that specifies how to connect to the new database location.
options - The integer that specifies what option to use when connecting to the new data source. You can also use DBOptions integer fields to specify this option. The DBOptions integer fields can also be concatenated to provide greater flexibility in connection options. See the example for more information.
Throws:
ReportSDKException

isConnectionOpen

public boolean isConnectionOpen(IConnection connection)
                         throws ReportSDKException
Checks if the specified data source connection is open.

Parameters:
connection - the IConnection to check
Throws:
ReportSDKException

openConnection

public void openConnection(IConnection connection)
                    throws ReportSDKException
Opens the specified data source connection.

Parameters:
connection - the IConnection to open
Throws:
ReportSDKException

closeConnection

public void closeConnection(IConnection connection)
                     throws ReportSDKException
Closes the specified data source connection.

Parameters:
connection - the IConnection to close
Throws:
ReportSDKException