borland.jbcl Packages  borland.jbcl Class Hierarchy  borland.jbcl.dataset 

Database component

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

About the Database component

Variables  Constructors  Properties  Methods  Event Listeners
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.

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

NoTransactionSupport

  public static final int NoTransactionSupport = Connection.TRANSACTION_NONE
Transactions are not supported. Not all JDBC drivers are SQL servers, for example, a text file. In such cases, the driver may not support transactions.

ReadCommitted

  public static final int ReadCommitted = Connection.TRANSACTION_READ_COMMITTED
You are able to view new or changed rows as other users commit their work.

ReadDirty

  public static final int ReadDirty = Connection.TRANSACTION_READ_UNCOMMITTED
You are able to view new/changed rows as other users have performed them (regardless of whether they have committed the work).

ReadRepeatable

  public static final int ReadRepeatable = Connection.TRANSACTION_REPEATABLE_READ
Reads on all rows of a result are repeatable. This means that you will not see anyone else's updates until your transaction is ended by committing or rolling back changes. This gives a consistent view of the data stored in the database.

ReadSerializable

  public static final int ReadSerializable = Connection.TRANSACTION_SERIALIZABLE
Same as ReadRepeatable but "phantom reads" are prevented.

Database constructors

Database()

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

Database(java.sql.Connection)

  public Database(java.sql.Connection connection)
Creates a Database object. Use this constructor when a JDBC connection has already been established and you want JBuilder JBCL dataset components to share that connection. There is no ConnectionDescriptor associated with the Database when this constructor is used since it uses the connection that is already open.

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.

Parameters:

connection
The JBDC Connection object to use for the Database component.

Database properties

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.

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.jbcl.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'.

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.

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 Database Variables.

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
NoTransactionSupport none
ReadDirty ReadCommitted
ReadCommitted ReadRepeatable
ReadRepeatable ReadSerializable
ReadSerializable 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.

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.

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.


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.

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.

finalize()

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

Overrides: java.lang.Object.finalize()

jdbcConnection()

  public final Connection jdbcConnection()
Attempts to make the JDBC connection if it is not already connected. If successful, jdbcConnection() returns the Connection object. On failure, this method throws a SQLException or DataSetException as applicable.

Use the jdbcConnection() method to gain access to or have more control over the JDBC Connection object.

See also: openConnection()

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.

See also: jdbcConnection()

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 explictly commit or rollback changes (false).

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.jbcl.dataset.ConnectionUpdateListener listener)
 public final void removeConnectionUpdateListener(borland.jbcl.dataset.ConnectionUpdateListener listener)