borland Packages  Class Hierarchy  sql.dataset Package  Index 

Database component

java.lang.Object
   +----borland.sql.dataset.Database

About the Database component

Variables  Constructors  Properties  Methods  Event Listeners

Implements Serializable

The Database component is a required element of any application accessing data stored on a SQL server. It encapsulates a database connection through JDBC to the SQL server and also provides lightweight transaction support.

When used with a QueryDataSet or ProcedureDataSet component, data is retrieved from the external database into a local cache (DataSet) on the user's system. All row data for a particular DataSet is cached on the user's system as a single unit. Changes made to the local copy of the data in the DataSet are internally recorded as deletes, inserts and updates. When all changes to the DataSet are complete, you then save the changes back to the original database by calling the saveChanges() method with one or more DataSet components.

You can connect several QueryDataSet or ProcedureDataSet components to a Database component, however, some SQL servers allow only one active query at a time on a connection. Check your server documentation to see if this is applicable to the SQL server you are accessing.

The Database component has an associated connection property that stores the connection properties of userName, password, and connectionUrl of the database. These properties are stored in the ConnectionDescriptor object. When the necessary properties for the connection have been supplied, the connection can be opened explicitly or automatically. When explicitly connecting, use the openConnection() method. The connection is opened automatically when you explicitly open the DataSet, or when a UI control requests data that is obtained through the database connection.

The information stored in the ConnectionDescriptor object is accessible through the user interface by inspecting the connection property of a Database object. This displays the Connection custom property editor.

If all needed properties have been set, a connection is attempted when any of the following situations occur:

When attempting to make the connection to the Database, the appropriate driver needed to access the remote server is loaded. If the remote server driver information is not available in the system registry, you can specify the driver using the addDriver() method, in the ConnectionDescriptor object, or in the Connection custom property editor dialog.

The isolation level, specified by the transactionIsolation property, is used when saving data changes back to the external database table.

When you no longer need a Database connection, you should explicitly call the Database.closeConnection() method in your application. This ensures that Database classes which hold references to JDBC connections are automatically closed when the Database object is garbage collected.

Use the saveChanges(borland.jbcl.dataset.DataSet[], boolean, boolean, boolean) method when you need special transaction logic. By setting its final parameter (resetPendingStatus) to false, this method offers the flexibility of not resetting the pending resolved status bits through the call to the saveChanges method. When you want to reset the pending resolved status bit, call the resetPpendingStatus method. This allows you, for example, to save changes made to several DataSets in a single transaction, and to rollback all changes while still retaining all the changed data in both DataSets.

For more information and examples on connecting to a database server, see Connecting to a database using JDBC in the Database Application Developer's Guide.


Database variables

Variables implemented in this class

Database constructors

Database properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in java.lang.Object

Database methods

Methods implemented in this class

Methods implemented in java.lang.Object

Database event listeners


Database variables

DEFAULT_DRIVERS

  public static String DEFAULT_DRIVERS = "sun.jdbc.odbc.JdbcOdbcDriver"
The default driver to use; the JDBC-ODBC Bridge driver from JavaSoft.

Database constructors

Database()

  public Database()
Creates a Database object and sets the transaction isolation level to ReadCommitted.

Database properties

autoCommit

 public final void setAutoCommit(boolean enable)
Specifies whether autoCommit is enabled (true) or not (false). If true, each SQL statement is executed and implicitly committed as an individual transaction. If false, all SQL statements are executed in a single transaction that is explicitly terminated by a commit() or rollback(). Where a SQL statement returns a result set that is stored in a QueryDataSet or a ProcedureDataSet, the statement completes when the last row of the result set has been retrieved.

This property defaults to true. On failure, it throws a DataSetException or a SQLException as applicable.

connection

 public ConnectionDescriptor getConnection()
 public void setConnection(borland.sql.dataset.ConnectionDescriptor connectionDescriptor)
The connection property is a complex property, containing all the information needed by the Database to establish a JDBC connection (including a Universal Resource Locator, a user name, and a password). The values are stored in a ConnectionDescriptor object.

You can read from or write to this property at any time, however, the new ConnectionDescriptor will not be applied until the next time the Database is explicitly opened.

identifierQuoteChar

 public final char getIdentifierQuoteChar()
Read-only property that returns the server's quote character. If not supported, the default quote character is set to '\0'.

jdbcConnection

 public final java.sql.Connection getJdbcConnection()
 public final void setJdbcConnection(java.sql.Connection connection)
Specifies the connection object to use. Use the setter method when a JDBC connection has already been established and you want JBuilder JBCL dataset components to share that connection. To use an explicit Connection object when connecting to a Database:
  1. create a java.sql.Connection object
  2. set this property to the Connection object
  3. instantiate the Database

Note: Be aware of any issues that sharing a Connection can have. If the connection is closed while the DataSet is still using it, unknown behavior can result. Additionally, there may be issues with servers that only allow one active query per Connection.

Use the getter of this property to obtain the JDBC Connection object.

maxStatements

 public final int getMaxStatements()
Read-only property that returns the maximum number of statements that the server supports.

metaData

 public final synchronized DatabaseMetaData getMetaData()
Read-only property that returns the meta data for the Database object. Meta data is that information that describes the database, for example, a listing of available tables. On failure, this method throws a SQLException. For more information on meta data, see Working with Columns in the Database Application Developer's Guide.

open

 public boolean isOpen()
Read-only property that returns whether the database connection is open.

runtimeMetaData

 public final synchronized RuntimeMetaData getRuntimeMetaData()
 public final synchronized void setRuntimeMetaData(borland.sql.dataset.RuntimeMetaData runtimeMeta)
This property is used internally by other classes in the JBCL. You should never use this property directly.

SQLDialect

 public final int getSQLDialect()
 public final void setSQLDialect(int dialect)
Specify SQL dialect that your server is based on. This is not required, but may be useful. Valid values for dialect are defined in SQLDialect.

transactionIsolation

 public final int getTransactionIsolation()
 public final synchronized void setTransactionIsolation(int level)
Specifies the transaction isolation level for the Database object. A single transaction is used when making changes to the external database table. On failure, this method throws a SQLException. Accepted values for the transaction isolation are listed under java.sql.connection.

The setTransactionIsolation() method checks to see if the driver supports transactions and if so, if the specified isolation level is set. If it isn't, a higher level of isolation (more restrictive) is attempted according to the following table:

Level failed Next level attempted
TRANSACTION_NONE none
TRANSACTION_READ_UNCOMMITTED TRANSACTION_READ_COMMITTED
TRANSACTION_READ_COMMITTED TRANSACTION_REPEATABLE_READ
TRANSACTION_REPEATABLE_READ TRANSACTION_SERIALIZABLE
TRANSACTION_SERIALIZABLE DataSetException thrown

If the connection is open, this property may be set at a higher level than you selected. If a supported isolation level is not found, a DataSetException of TransactionIsolationLevelNotSupported is thrown. This method also throws a SQLException as appropriate.

You can change the transaction isolation level only on a newly opened connection--attempting to do so in the middle of a transaction will generate a SQLException.

These transaction isolation rules apply when working with the Database component in the JBuilder UI Designer as well as in manually in code.

When working in the UI Designer, the Exception generated when setting the transaction isolation level on an open connection is suppressed, however, no code is written for the changed setting. To set the transaction isolation level in the UI Designer, set it before the connection is opened.

See also: java.sql.DatabaseMetaData#supportsTransactionIsolationLevel

useSchemaName

 public boolean isUseSchemaName()
 public void setUseSchemaName(boolean useSchemaName)
Determines whether the user name (that was used to connect to the Database) should be included with all metadata discovery requests sent to the server. This property does not apply to queries executed against the server.

Note: This property is required for some servers; check your server software documentation to determine whether your server software requires an explicit user name for metadata discover requests. This property defaults to false. For more information on metadata, see the Metadata and how it is obtained topic in the Database Application Developer's Guide.

useSetObjectForStreams

 public boolean isUseSetObjectForStreams()
 public void setUseSetObjectForStreams(boolean useSetObjectForStreams)
Controls which method is used to save a binaryStream value when resolving data. If true, the setObject() method is used. If false, setBinaryStream() is used on the PreparedStatement. This property defaults to false for the ODBC bridge and true for all other drivers.

useSetObjectForStrings

 public boolean isUseSetObjectForStrings()
 public void setUseSetObjectForStrings(boolean useSetObjectForStrings)
Controls which method is used to save a String value when resolving data. If true, the setObject() method is used. If false, setString() is used on the PreparedStatement. This property defaults to true.

useSpacePadding

 public boolean isUseSpacePadding()
 public void setUseSpacePadding(boolean useSpacePadding)
Controls if a CHAR field should be space padded or not. This can sometimes help to work around certain database driver bugs.

useStatementCaching

 public boolean isUseStatementCaching()
 public void setUseStatementCaching(boolean useStatementCaching)
Controls whether the jdbc statements should be reused.

useTableName

 public boolean isUseTableName()
 public void setUseTableName(boolean useTableName)
Determines whether the table name should be prepended to all field names in all queries executed against SQL server data. This property defaults to false.

Note: This property is required for some servers; check your server software documentation to determine whether your server software requires an explicit table name for query execution. This property can be helpful for drivers that have difficulty in parsing quoted field names, for example, local databases such as Paradox and dBASE. When accessing Paradox and dBASE tables using DataGateway, set this property to true.

useTransactions

 public boolean isUseTransactions()
 public void setUseTransactions(boolean useTransactions)

Database methods

addDriver(java.lang.String)

  public final void addDriver(java.lang.String driver)
Adds the specified driver name to the jdbc.drivers property in the system property list (if it hasn't already been registered) and instructs JDBC to load the driver prior to attempting the database connection. For example, to add the JDBC-ODBC bridge driver, include the following code in your application:
addDriver("sun.jdbc.odbc.JdbcOdbcDriver");

Parameters:

driver
The class name of the driver to register.

addDriver(java.lang.String, boolean)

  public static void addDriver(java.lang.String driver, boolean multiple)
Adds the specified driver name to the jdbc.drivers property in the system property list (if it hasn't already been registered) and instructs JDBC to load the driver prior to attempting the database connection.

Applets will throw a security Exception during the execution of this method, which will be swallowed silently. On error, this method throws a DataSetException.

addDrivers(java.lang.String)

  public static void addDrivers(java.lang.String driver)

closeConnection()

  public final synchronized void closeConnection()
Closes an active database connection by setting the JDBC Connection object's transaction mode to AutoCommit, invoking the Connection object's close() method, then resetting the Connection object to null. On failure, this method throws a SQLException.

You should explicitly call this method in your application when you no longer need a Database connection to assure that all connection objects (Database, Connection and so on) are properly released when garbage collection occurs.

commit()

  public void commit()
Commits changes back to the server.

createCallableStatement(java.lang.String)

  public final synchronized CallableStatement createCallableStatement(java.lang.String query)
Opens a database connection, parses a SQL stored procedure query string that can contain zero or more "?" parameters, prepares, and returns it in a CallableStatement. A SQL statement with IN and/or OUT parameters can be pre-compiled and stored in a CallableStatement object.

Check the documentation for your driver software to see if callable statements are supported by your driver.

createPreparedStatement(java.lang.String)

  public final synchronized PreparedStatement createPreparedStatement(java.lang.String query)
Opens a database connection, parses a query string, prepares it, and returns it in a PreparedStatement object. This PreparedStatement object can then be used to efficiently execute the statement, instead of the Statement object which must be compiled at each execution. A PreparedStatement object is used in situations where the exact same query is executed frequently. A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object.

To the end user of your application, there is no difference between using a pre-compiled PreparedStatement object or a non-compiled equivalent. The developer however, may find slight differences when exception events are thrown. Precompiling a query into a PreparedStatement can offer improved performance however not all queries can be precompiled and not all drivers support precompilation. Check the documentation for your driver software to see if precompilation is possible and the conditions under which it is possible.

On failure, this method throws a SQLException or DataSetException as appropriate.

createStatement()

  public final synchronized Statement createStatement()
Opens the Connection to the database and returns a Statement object. The Statement object returned can be used for executing a static query (a query without parameters). On failure, this method throws a SQLException.

executeStatement(java.lang.String)

  public int executeStatement(java.lang.String statementString)
Executes the SQL statement specified by the statementString parameter. Use this method to execute arbitrary SQL statements including DDL.

This method does not execute parameterized SQL statements. JBuilder passes the statement string directly to the JDBC driver without parsing for named parameters. Equivalent methods that permit parameter passing are available as static methods of the QueryProvider (executeStatement()) and ProcedureProvider (callProcedure()) components.

finalize()

  protected void finalize()
Closes the connection to the database server and releases all objects for garbage collection.

Overrides: java.lang.Object.finalize()

openConnection()

  public final synchronized void openConnection()
Connects to a driver using the ConnectionDescriptor object property values of userName, password and connectionURL. Each registered driver is loaded until one is found that can process the specified URL. The transaction isolation level is set and DatabaseMetaData object is obtained. The DatabaseMetaData object contains information about the Database, for example, the list of available tables and views in a database.

On failure, this method throws a SQLException.

resetPendingStatus(borland.jbcl.dataset.DataSet[], boolean)

  public void resetPendingStatus(borland.jbcl.dataset.DataSet[] dataSets, boolean markResolved)
Resets the pending status bits. The saveChanges(borland.jbcl.dataset.DataSet[], boolean, boolean, boolean) method allows you to call saveChanges without resetting the pending resolved status bits. In such cases, use the resetPendingStatus method to reset the pending resolved status bits when appropriate. This feature is useful when you want special transaction logic, for example, when changes made to several DataSets should be saved in a single transaction. This method allows you to rollback all the changes and still have all the updates in the DataSets.

Parameters:

dataSets
The array of DataSet objects to reset status bits of.
markResolved
If true, status bits are reset after changes are saved (the default). If false, status bits are left in a pending state.

resultSetToDataSet(java.sql.ResultSet)

  public StorageDataSet resultSetToDataSet(java.sql.ResultSet result)
Creates a StorageDataSet object that contains data from the result set of a JDBC query or prepared statement. On failure, this method throws a SQLException or a DataSetException as appropriate.

Parameters:

result
The JDBC ResultSet.

rollback()

  public void rollback()
Rolls back changes made to data since the last commit or rollback() operation.

saveChanges(borland.jbcl.dataset.DataSet)

  public final void saveChanges(borland.jbcl.dataset.DataSet dataSet)
Save changes made to the local copy of the data specified by dataSet back to the data source. Changes to the local data are done through DataSet methods, either programmatically or using a data-aware control.

Parameters:

dataSet
The DataSet that contains the modified data.

saveChanges(borland.jbcl.dataset.DataSet[])

  public final void saveChanges(borland.jbcl.dataset.DataSet[] dataSets)
Saves changes made to data contained in the DataSet components listed in the array. Changes to the local data are done programmatically or using a data-aware control.

Parameters:

dataSets
An array of DataSet components that contain modified data to save back to the data source.

saveChanges(borland.jbcl.dataset.DataSet[], boolean)

  public final void saveChanges(borland.jbcl.dataset.DataSet[] dataSets, boolean doTransactions)
Saves changes made to one or more DataSet objects to the database data source.

Parameters:

dataSets
An array of DataSet components that contain modified data to save back to the data source.
doTransactions
Determines whether any transactions are used while resolving (true) or whether the user must explicitly commit or rollback changes (false).

saveChanges(borland.jbcl.dataset.DataSet[], boolean, boolean, boolean)

  public final void saveChanges(borland.jbcl.dataset.DataSet[] dataSets, boolean doTransactions, boolean postEdits, boolean resetPendingStatus)
Saves changes made to one or more DataSet changes to the database.

Parameters:

dataSets
Array of DataSet components to save changes for.
doTransactions
If true, all changes will be in a single transaction (the default). If false, no transactions calls will be made.
postEdits
If true, all edits are posted before changes are saved (the default). If false, edits are not automatically saved.
resetPendingStatus
If true, status bits are reset after changes are saved (the default). If false, status bits are left in pending state. This allows you to reset the pending resolved bits outside the call to the saveChanges method. For more information see the resetPendingStatus() method.

start()

  public void start()
Explicitly starts a transaction.

storesLowerCaseIdentifiers()

  public boolean storesLowerCaseIdentifiers()
Returns whether the database stores identifiers in lower case (true) or not (false).

storesUpperCaseIdentifiers()

  public boolean storesUpperCaseIdentifiers()
Returns whether the database stores identifiers in upper case (true) or not (false).

Database event listeners

This component is a source for the following event sets. For information on the JBCL event sets, see Events in JBCL.

connectionUpdate

 public final void addConnectionUpdateListener(borland.sql.dataset.ConnectionUpdateListener listener)
 public final void removeConnectionUpdateListener(borland.sql.dataset.ConnectionUpdateListener listener)