Creating or connecting to an UltraLite or UltraLite Java edition database

Java applications must connect to a database before operations can be performed on the data. This section explains how to create or connect to an UltraLite or UltraLite Java edition database with a specified password using the UltraLiteJ API.

Note

To create an UltraLite database without using the UltraLiteJ API, you can use Sybase Central or UltraLite command line utilities. For more information, see UltraLite database creation.

To create an UltraLite Java edition database without using the UltraLiteJ API, you can perform one of the following tasks:

Create the database using the ULjLoad utility. See UltraLite Java Edition Database Load utility (ULjLoad).
Use the ulunload and ULjLoad utilities to convert an UltraLite database. See UltraLite Database Unload utility (ulunload).
Deploy a Java SE application to a BlackBerry smartphone by copying the UltraLite Java database to an SD card or transferring it from MobiLink using the file transfer mechanism. See MobiLink file transfers.

For more information about the differences between an UltraLite and an UltraLite Java edition database, see UltraLite and UltraLite Java edition databases.

A Configuration object is used to configure a database store. Several implementations of a Configuration object are provided. A unique implementation exists for every type of database store supported by the UltraLiteJ API. Each implementation provides a set of methods used to configure the database store.

The following table lists the available Configuration object implementations for the supported database stores:

Store type	UltraLiteJ API support
Android file system	See ConfigFileAndroid interface [Android] [UltraLiteJ].
RIM object (BlackBerry)	See ConfigObjectStore interface [BlackBerry] [UltraLiteJ].
Record	See ConfigRecordStore interface (J2ME only) [UltraLiteJ].
Java SE file system	See ConfigFile interface [UltraLiteJ].
Non-persistent (in memory)	See ConfigNonPersistent interface [BlackBerry] [UltraLiteJ].
Internal flash and SD card	See ConfigFileME interface [BlackBerry] [UltraLiteJ].

When creating a persistent database store, you can set the form of persistence for your Java application using your Configuration object. By default, shadow paging persistence is enabled. You can use simple paging persistence as an alternative by setting the setShadowPaging method of your persistent Configuration object to false. When simple paging persistence is enabled, you can set write-at-end persistence by setting the setWriteAtEnd method of your persistent Configuration object to true.

Note

Write-at-end and simple paging persistence should only be used in applications when the loss of data can be tolerated, the database can be easily recreated, or the database is not updated.

For more information about setting persistent and non-persistent stores using a Configuration object, see:

After creating and configuring a Configuration object, you use a Connection object to create or connect to the database. Connection objects can also be used to perform the following operations:

Transactions A transaction is the set of operations between commits or rollbacks. For persistent database stores, a commit makes permanent any changes since the last commit or rollback. A rollback returns the database to the state it was in when the last commit was invoked.
Each transaction and row-level operation in UltraLite is atomic. An insert involving multiple columns either inserts data to all the columns or to none of the columns.

Transactions must be committed to the database using the commit method of the Connection object.
Prepared SQL statements Methods are provided by the PreparedStatement interface to handle SQL statements. A PreparedStatement can be created using the prepareStatement method of the Connection object.
Synchronizations A set of objects governing MobiLink synchronization is accessed from the Connection object.

Create or connect to a database from your Java application.

Prerequisites

An existing Java application for an Android device or a BlackBerry smartphone that implements the UltraLiteJ API.

Context and remarks

Many.

Create or connect to a database from your Java application

Create a new Configuration object that references the database name and is appropriate for your platform.

In the following examples, config is the Configuration object name and DBname is the database name.

For Android smartphones:

ConfigFileAndroid config = 
    DatabaseManager.createConfigurationFileAndroid("DBname.udb");

For BlackBerry smartphones:

ConfigObjectStore config = 
    DatabaseManager.createConfigurationObjectStore("DBname.ulj");

ConfigFileME config =
DatabaseManager.createConfigFileME( "file:///store/home/user/DBname.ulj" );

ConfigFileME config =
DatabaseManager.createConfigFileME( "file:///SDCard/DBname.ulj" );

For all other Java ME devices:

ConfigRecordStore config = 
    DatabaseManager.createConfigurationRecordStore("DBname.ulj");

For Java SE platforms:

ConfigFile config = 
    DatabaseManager.createConfigurationFile("DBname.ulj");

For any platform, you can create a non-persistent database Configuration object:

ConfigNonPersistent config = 
    DatabaseManager.createConfigurationNonPersistent("DBname.ulj");

Set database properties using methods of the Configuration object.

For example, you can set a new database password using the setPassword method:

config.setPassword("my_password");

For BlackBerry smartphones, you can also set the database persistence using the Configuration object. The following example illustrates how to set write-at-end persistence prior to creating the database:

config.setShadowPaging(false);
config.setWriteAtEnd(true);

For Android smartphones, you can use the setCreationString and setConnectionString methods to set additional creation and connection parameters, respectively.

For more information about creation and connection parameters, see:

Create a Connection object to create or connect to the database:

To create a new database, use the following code to create the Connection object:
Connection conn = DatabaseManager.createDatabase(config);
The DatabaseManager.createDatabase method creates the database and returns a connection to it.

To connect to an existing database, use the following code to create the Connection object:
Connection conn = DatabaseManager.connect(config);
The connect method finalizes the database connection process. If the database does not exist, an error is thrown.

Results

You can execute SQL statements from your Java application to create the tables and indexes in your database but you cannot change certain database creation parameters, such as the database name, password, or page size.

Next

None.