Java-enabling a database

User's Guide
PART 3. Java in the Database
CHAPTER 17. Using Java in the Database

Java-enabling a database

The Adaptive Server Anywhere Runtime environment for Java requires a Java VM and the Sybase runtime Java classes. The Java VM is always available as part of the database server, but you need to Java-enable a database in order for it to be able to use the runtime Java classes.

New databases are Java-enabled by default
By default, when you create a database with Adaptive Server Anywhere, it is Java-enabled. You can also Java-enable a database when you upgrade.

Java is a single-hierarchy language, meaning that all classes you create or use eventually inherit from one class. This means the low-level classes (classes further up in the hierarchy) must be present before higher-level classes can be used. The base set of classes required to run Java applications is called the runtime Java classes, or the Java API.

When not to Java-enable a database

Java-enabling a database adds many entries into the system tables. This adds to the size of the database and, more significantly, adds about 200K to the memory requirements for running the database. If you are not going to use Java, and if you are running in a limited-memory environment, you may wish to not Java-enable your database.

The Sybase runtime Java classes

The Sybase runtime Java classes are held in the following system zip files, in the Java subdirectory of your Adaptive Server Anywhere installation directory:

classes.zip This file, licensed from Sun Microsystems, contains the Sun Microsystem Java runtime classes.
asajdbc.zip This file contains Sybase internal JDBC driver classes.
jdbcdrv.zip This file contains Sybase external JDBC driver classes.

Where the runtime classes are held

The Sybase runtime Java classes are treated specially in that, unlike other classes, they are not stored in a database. Instead, they are held on disk.

When a database is Java-enabled, the system tables are updated with a list of available classes from the system Jar files. You can then browse the class hierarchy from Sybase Central, but the classes themselves are not present in the database.

JAR files

The runtime class names are stored in the database under the following Jar files:

ASAJDBC Class names from asajdbc.zip are held here.
ASAJDBCDRV Class names from jdbcdrv.zip are held here.
ASASystem Class names from classes.zip are held here.

Installed packages

These runtime classes include the following packages:

java Packages under here are the supported Java runtime classes from Sun Microsystems. For a list of the supported Java runtime classes, see Built-in Java classes.
com.sybase Packages under here provide server-side JDBC support.
sun Packages under here are provided by Sun Microsystems.
sybase.sql Packages under here are part of the Sybase server-side JDBC support.

Caution: do not install classes from another version of Sun's JDK
Classes in Sun's JDK shares names with the Sybase runtime Java classes that must be installed in any database intended to execute Java operations.

You must not replace the classes.zip file included with Adaptive Server Anywhere. Using another version of these classes could cause compatibility problems with the Sybase Java Virtual Machine.

You must only Java-enable a database using the methods outlined in this section.

Ways of Java-enabling a database

Databases can be Java-enabled when they are created, when they are upgraded, or at a later time.

Creating databases

You can create a database that is Java-enabled in the following ways:

Using the CREATE DATABASE statement. For details of the syntax, see CREATE DATABASE statement.
Using the dbinit command-line utility. For details, see The DBINIT command-line utility.
Use Sybase Central. For details, see Creating a database in Sybase Central.

Upgrading databases

You can upgrade a Version 5 database to be a Java-enabled Version 6 database in the following ways:

Using the ALTER DATABASE statement. For details of the syntax, see ALTER DATABASE statement.
Using the dbupgrad.exe upgrade utility. For details, see The DBUPGRAD command-line utility.
Using Sybase Central. For details, see Upgrading a database from Sybase Central.

In databases where the Sybase runtime Java classes are not installed, all database operations that do not involve Java operations are fully functional and work as expected.

New databases and Java

By default, all new databases are Java-enabled: the Sybase runtime Java classes are installed when the database is created. The installation of these classes is optional. Control of the installation of these classes is determined by the method used to create the database.

CREATE DATABASE options

The CREATE DATABASE SQL statement has an option called JAVA. The option can be set to ON to Java-enable a database or OFF which will cause the Sybase runtime Java classes to not be installed. This option is not required and if it is not explicitly set, it is by default set to ON.

For example, the following statement creates a Java-enabled database file named temp.db:

CREATE DATABASE 'c:\\sybase\\asa6\\temp'

The following statement creates a database file named temp2.db, which does not support Java.

CREATE DATABASE 'c:\\sybase\\asa6\\temp2'
JAVA OFF

Database initialization utility

Databases can be created using the dbinit.exe command-line database initialization utility. The utility has a -j switch that controls whether the Sybase runtime Java classes are installed in the newly-created database. If the switch is not used, the Java classes are installed by default. Using the -j switch prevents the Sybase runtime Java classes from being installed.

The same option is available when creating databases using Sybase Central.

Upgrading databases and Java

Existing databases created with Sybase SQL Anywhere Version 5 or earlier can be upgraded using the command-line database upgrade utility or from Sybase Central.

Database upgrade utility

Databases can be upgraded to Adaptive Server Anywhere Version 6 standards using the dbupgrad.exe command-line utility. If the -j switch is not specified when using this utility, the Sybase runtime Java classes are automatically installed.

Java-enabling a Version 6 database

If you have created a Version 6 database, or upgraded a database to Version 6 standards, but have chosen not to Java-enable the database, you can add the necessary Java classes at a later date.

You can Java-enable a Version 6 database from either Sybase Central or Interactive SQL.

To add the Java runtime classes to a database from Sybase Central:

Connect to the database from Sybase Central as a user with DBA authority.
Open the Java Objects folder.
Double click Install Base Java Class Support. If this icon is not present, it means that your database already has the Java runtime classes installed.
Follow the instructions in the Wizard.

To add the Java runtime classes to a database from Interactive SQL:

Connect to the database from Interactive SQL as a user with DBA authority.
Run the script instjava.sql from the scripts directory:
```
read "path/scripts/instjava.sql"
```
where path is the name of your Adaptive Server Anywhere installation directory.

Using Sybase Central to Java-enable a database

Sybase Central has the ability to both create and upgrade databases. Both functions are accomplished with the use of wizards. During the creation or upgrade of a database the wizard prompts the user to choose if the Sybase runtime Java classes are installed. By default, this option is checked to Java-enable the database.

Using Sybase Central, you can create or upgrade a database by:

Choosing Create database from the Utilities folder, or
Choosing Upgrade database from the Utilities folder to upgrade a Version 5 or Version 4 database to a Version 6 database with Java capabilities.