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)
          For internal use only
 void addDataSource(IDataSet newDataSet)
           Adds a IDataSet as a data source for the report.
 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)
          For internal use only
 void addTable(ITable table, TableLinks relatedTableLinks)
           Adds a new table from the data source to the report.
 void addTableJoin(ITableJoin tableJoin)
          For internal use only
 void addTableLink(ITableLink tableLink)
           Adds one or more links between two tables.
 boolean canExecuteSQL()
           Returns true if the database supports SQL, and false otherwise.
 VerifyDatabaseFeedbacks checkDatabase(boolean pushedDataSourceOnly)
          For internal use only.
 void closeConnection(IConnection connection)
          For internal use only
 void doSmartLinking()
           Attempts to automatically link the tables in the report using TableLink objects.
 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)
          For internal use only
 ITableJoin findTableJoin(java.lang.Object fromTable, java.lang.Object toTable)
          For internal use only
 ITableLink findTableLink(int fromTableIndex, int toTableIndex)
           Returns a link between two tables.
 ITableLink findTableLink(java.lang.Object fromTable, java.lang.Object toTable)
           Returns a link between two tables.
 BlobFieldImageAttributes getBlobFieldImageAttributes(IDBField dbField)
          For internal use only.
 ConnectionInfos getConnectionInfos(PropertyBag promptProperties)
           Returns the collection of all database logons that exist in a report.
 PropertyBag getConnectionProperties(IConnectionInfo connection)
          For internal use only.
 IDatabase getDatabase()
           Returns the tables and fields available in the report.
 ForeignKeyInfos getForeignKeyInfo(IConnection connection, ITable pkTable, ITable fkTable)
          For internal use only.
 FieldLinks getOrderedLinks()
          For internal use only.
 java.util.Locale getProductLocale()
           
 java.lang.String getQuerySpec(java.lang.String connectionName)
          For internal use only.
 IStrings getServerNames()
          Returns the names of all servers used in the report.
static boolean isAliasValid(java.lang.String tableAlias)
          For internal use only.
 boolean isConnectionOpen(IConnection connection)
          For internal use only
 void logon(IConnectionInfo connectionInfo, java.lang.String sUser, java.lang.String sPassWord)
          For internal use only
 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.
 FieldMappingInfos mapFields(FieldMappingInfos mapInfos)
          For internal use only
 void modifyFieldHeading(IDBField dbField, java.lang.String newFieldHeadingText)
           Modifies a field's heading.
 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)
          For internal use only
 void modifyTableLink(ITableLink oldTableLink, ITableLink newTableLink)
           Modifies the linking options for a particular table.
 void openConnection(IConnection connection)
          For internal use only
 void removeConnection(IConnection connection)
          For internal use only.
 void removeTable(java.lang.String tableAlias)
           Removes a table from the report.
 void removeTableJoin(ITableJoin tableJoin)
          For internal use only
 void removeTableLink(ITableLink tableLink)
           Removes one or more links between two tables.
static java.lang.String replaceAliasInvalidCharacters(java.lang.String tableAlias)
          For internal use only
 void replaceConnection(IConnection oldConnection, IConnection newConnection, int options)
          For internal use only
 void replaceConnection(IConnectionInfo oldConnection, IConnectionInfo newConnection, Fields parameterFields, int options)
          Changes the database location of a report at runtime.
 void replaceConnection(IConnectionInfo oldConnection, IConnectionInfo newConnection, Fields parameterFields, PropertyBag tablePrefixMap, int options)
          Internal use only
 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)
          For internal use only
 void setDataSource(CrystalResultSet data, java.lang.String oldTableAlias, java.lang.String newTableName)
          For internal use only.
 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 setLinksOrder(FieldLinks orderedLinks)
          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)
          For internal use only
 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)
          For internal use only
 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(IDataSet newDataSet)
                   throws ReportSDKException

Adds a IDataSet 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 IDataSet object to be added
Throws:
ReportSDKException

addDataSource

public void addDataSource(java.util.Collection domainData,
                          java.lang.Class domainClass)
                   throws ReportSDKException
For internal use only

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 SAP 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,
                     TableLinks relatedTableLinks)
              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.
relatedTableLinks - An ITableLinks object that represents how tables are linked in the report.
Throws:
ReportSDKException
See Also:
Setting ConnectionInfo

addTable

public void addTable(ITable table,
                     TableJoins relatedTableJoins)
              throws ReportSDKException
For internal use only

Throws:
ReportSDKException

addTableLink

public void addTableLink(ITableLink tableLink)
                  throws ReportSDKException

Adds one or more links between two tables. Note: If the table link you are adding to the report requires logon information, and this logon information has not been set, this method will fail. See the setConnectionInfos method.

Parameters:
tableLink - The ITableLink object that specifies how the two tables should be linked.
Throws:
ReportSDKException

addTableJoin

public void addTableJoin(ITableJoin tableJoin)
                  throws ReportSDKException
For internal use only

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.

doSmartLinking

public void doSmartLinking()
                    throws ReportSDKException

Attempts to automatically link the tables in the report using TableLink objects. Smart linking is attempted by Name and then by Type only.

Throws:
ReportSDKException

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
For internal use only

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", "databasename", "username", "password");
 

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

Modifies a field's heading. If the field has already been added to the report, changes to this value will not update the column heading in the report. To change a field heading that already appears in the report, you must remove the field, modify the field heading, and then re-add the field.

Parameters:
dbField - The field whose field heading is modified. The field can be obtained by using the getDatabase method in the DatabaseController object, DataDefController object, or ReportClientDocument object.
newFieldHeadingText - The new text for the heading.
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

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

Throws:
ReportSDKException

modifyTableLink

public void modifyTableLink(ITableLink oldTableLink,
                            ITableLink newTableLink)
                     throws ReportSDKException

Modifies the linking options for a particular table. To modify the table linking options, find the table whose options you wish to change, clone the TableLink object using its clone() method, modify the clone and then pass this to this method as the newTableLink parameter.

Parameters:
oldTableLink - The original TableLink object.
newTableLink - The modified TableLink object.
Throws:
ReportSDKException

modifyTableJoin

public void modifyTableJoin(ITableJoin oldTableJoin,
                            ITableJoin newTableJoin)
                     throws ReportSDKException
For internal use only

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

removeTableLink

public void removeTableLink(ITableLink tableLink)
                     throws ReportSDKException

Removes one or more links between two tables. To remove all of the links between a particular source table and target table, find the TableLink object whose source and target table aliases match the ones you are looking for, and then call removeTableLink. Links between the source table and any table that is not the target will remain intact.

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

Note: If you do not specify a table alias as an argument, it is taken as null and all of the table's links are removed.

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

Parameters:
tableLink - The TableLink object that specifies how the two tables should be linked. Table links can be obtained by using the DatabaseController.getDatabase() method in the DatabaseController object, DataDefController object, or ReportClientDocument object.
Throws:
ReportSDKException

removeTableJoin

public void removeTableJoin(ITableJoin tableJoin)
                     throws ReportSDKException
For internal use only

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 DatabaseController.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 DatabaseController.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(CrystalResultSet data,
                          java.lang.String oldTableAlias,
                          java.lang.String newTableName)
                   throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

setDataSource

public void setDataSource(java.util.Collection domainData,
                          java.lang.Class domainClass,
                          java.lang.String oldTableAlias,
                          java.lang.String newTableName)
                   throws ReportSDKException
For internal use only

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 DatabaseController.addDataSource(ResultSet) method.

NOTE: This method is only supported when you are running managed RAS (RAS is running as part of SAP 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 oldTable = tables.getTable(index);
 IProcedure newTable = (IProcedure)oldTable.clone(true);  
 ParameterField paramField = (ParameterField)newTable.getParameters().get(0);
 Values currentValues = new Values();
 ParameterFieldDiscreteValue parameterValue = new ParameterFieldDiscreteValue();
 parameterValue.setValue(new Integer (1));
 currentValues.add(parameterValue);
 paramField.setCurrentValues(currentValues);
 databaseController.setTableLocation(oldTable, newTable);
 

Parameters:
curTable - The table whose database location you want to change. A table can be obtained by using the DatabaseController.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", "databasename", "username", "password");
 

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

findTableLink

public ITableLink findTableLink(int fromTableIndex,
                                int toTableIndex)
                         throws ReportSDKException

Returns a link between two tables.

If no match is found, the return value is null.

Example:

This sample shows how to use a DatabaseController object to return a TableLink object that represents a link between two tables in a report. A TableLink object represents a link between two tables that may be in different databases. A field from the one table (called the source table) and a field from the other table (called the target table) are used to link the two tables together.

 DatabaseController databaseController = clientDoc.getDatabaseController();
 ITableLink link = databaseController.findTableLink(0, 2);
 

Parameters:
fromTableIndex - the index of the table from which the link originates
toTableIndex - the index of the table where the link terminates
Returns:
ITableLink a reference to the ITableLink object
Throws:
ReportSDKException

findTableJoin

public ITableJoin findTableJoin(int fromTableIndex,
                                int toTableIndex)
                         throws ReportSDKException
For internal use only

Throws:
ReportSDKException

findTableLink

public ITableLink findTableLink(java.lang.Object fromTable,
                                java.lang.Object toTable)
                         throws ReportSDKException

Returns a link between two tables.

If no match is found, the return value is null.

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:
ITableLink a reference to the ITableLink object
Throws:
ReportSDKException

findTableJoin

public ITableJoin findTableJoin(java.lang.Object fromTable,
                                java.lang.Object toTable)
                         throws ReportSDKException
For internal use only

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

replaceConnection

public void replaceConnection(IConnectionInfo oldConnection,
                              IConnectionInfo newConnection,
                              Fields parameterFields,
                              PropertyBag tablePrefixMap,
                              int options)
                       throws ReportSDKException
Internal use only

Throws:
ReportSDKException

mapFields

public FieldMappingInfos mapFields(FieldMappingInfos mapInfos)
                            throws ReportSDKException
For internal use only

Throws:
ReportSDKException

setJNDIOptionalName

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

Throws:
ReportSDKException

getQuerySpec

public java.lang.String getQuerySpec(java.lang.String connectionName)
                              throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

getForeignKeyInfo

public ForeignKeyInfos getForeignKeyInfo(IConnection connection,
                                         ITable pkTable,
                                         ITable fkTable)
                                  throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

getConnectionProperties

public PropertyBag getConnectionProperties(IConnectionInfo connection)
                                    throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

getOrderedLinks

public FieldLinks getOrderedLinks()
                           throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

setLinksOrder

public void setLinksOrder(FieldLinks orderedLinks)
                   throws ReportSDKException
For internal use only.

Throws:
ReportSDKException

setTableLocationEx

public void setTableLocationEx(java.lang.Object curTable,
                               java.lang.Object newObject,
                               FieldMappingInfos fieldInfos)
                        throws ReportSDKException
For internal use only

Throws:
ReportSDKException

setTableLocation

public void setTableLocation(ITable curTable,
                             ITable newTable,
                             FieldMappingInfos fieldInfos)
                      throws ReportSDKException
For internal use only

Throws:
ReportSDKException

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
For internal use only

Throws:
ReportSDKException

isConnectionOpen

public boolean isConnectionOpen(IConnection connection)
                         throws ReportSDKException
For internal use only

Throws:
ReportSDKException

openConnection

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

Throws:
ReportSDKException

closeConnection

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

Throws:
ReportSDKException

replaceAliasInvalidCharacters

public static java.lang.String replaceAliasInvalidCharacters(java.lang.String tableAlias)
For internal use only


isAliasValid

public static boolean isAliasValid(java.lang.String tableAlias)
For internal use only.


getProductLocale

public java.util.Locale getProductLocale()