Chapter 1 An Introduction

to Java in the Database

Java in Adaptive Server Enterprise

Chapter 2 Preparing for and Maintaining Java in the Database

Chapter 2

Preparing for and Maintaining Java in the Database

This chapter describes the Java runtime environment, how to enable Java on the server, and how to install and maintain Java classes in the database.

The Java Runtime Environment

The Adaptive Server runtime environment for Java requires a Java VM, which is available as part of the database server, and the Sybase runtime Java classes, or Java API. If you are running Java applications on the client, you may also require the Sybase JDBC driver, jConnect, on the client.

Java Classes in the Database

You can use either of the following sources for Java classes:

Sybase runtime Java classes
User-defined classes

Sybase Runtime Java Classes

The Sybase Java VM supports a subset of JDK version 1.1.6 (UNIX and Windows NT) classes and packages.

The Sybase runtime Java classes are the low-level classes installed to Java-enable a database. They are downloaded when Adaptive Server is installed and are available thereafter from $SYBASE /$SYBASE_ASE/lib/runtime.zip (UNIX) or %SYBASE%\%SYBASE_ASE%\lib\runtime.zip (Windows NT). You do not need to set the CLASSPATH environment variable specifically for Java in Adaptive Server.

Sybase does not support runtime Java packages and classes that assume a screen display, deal with networking and remote communications, or handle security. See Chapter 7, "Reference Topics" for a list of supported and not-supported packages and classes.

User-Defined Java Classes

You install user-defined classes into the database using the installjava utility. Once installed, these classes are available from other classes in the database and from SQL as user-defined datatypes.

JDBC Drivers

The Sybase internal JDBC driver that comes with Adaptive Server supports JDBC version 1.1.

If your system requires a JDBC driver on the client, you must use jConnect version 4.1, which also supports JDBC version 1.1.

Enabling the Server for Java

To enable the server and its databases for Java, enter this command from isql:

sp_configure "enable  java", 1

Then shutdown and reboot the server.

By default, Adaptive Server is not enabled for Java. You cannot install Java classes or perform any Java operations until the server is enabled for Java.

You can increase or decrease the amount of memory available for Java in Adaptive Server and optimize performance using the sp_configure system procedure. Java configuration parameters are described in the System Administration Guide.

Disabling the Server for Java

To disable Java in the database, enter this command from isql:

sp_configure "enable java",  0

Creating Java Classes and JARs

The Sybase-supported classes from the JDK are installed on your system when you install Adaptive Server version 12 or later. This section describes the steps for creating and installing your own Java classes.

To make your Java classes (or classes from other sources) available for use in the server, follow these steps:

Write and save the Java code that defines the classes.
Compile the Java code.
Create Java archive (JAR) files to organize and contain your classes.
Install the JARs/classes in the database.

Writing the Java Code

Use the Sun Java SDK or a development tool such as Sybase PowerJ to write the Java code for your class declarations. Save the Java code in a file with an extension of .java. The name and case of the file must be the same as that of the class.

Make certain that any Java API classes used by your classes are among the supported API classes listed in Chapter 7, "Reference Topics" .

Compiling Java Code

This step turns the class declaration containing Java code into a new, separate file containing byte code. The name of the new file is the same as the Java code file but has an extension of .class. You can run a compiled Java class in a Java runtime environment regardless of the platform on which it was compiled or the operating system on which it runs.

Saving Classes in a JAR File

You can organize your Java classes by collecting related classes in packages and storing them in JAR files.

To install Java classes in a database, the classes or packages must first be saved in a JAR file, in uncompressed form. To create an uncompressed JAR file that contains Java classes, use the Java jar cf0 command.

In this UNIX example, the jar command creates an uncompressed JAR file that contains all .class files in the jcsPackage directory:

jar cf0 jcsPackage.jar jcsPackage/*.class

Note that the "0" in cf0 is "zero."

JAR files allow you to install or remove related classes as a group.

Installing Java Classes in the Database

To install Java classes from a client operating system file, use the installjava (UNIX) or instjava (Windows NT) utility from the command line.

Refer to Adaptive Server Utilities Programs for your platform for detailed information about these utilities. Both utilities perform the same tasks; for simplicity, this document uses UNIX examples.

Using installjava

installjava copies a JAR file into the Adaptive Server system and makes the Java classes contained in the JAR available for use in the current database. The syntax is:

installjava 
 -f file_name
 [-new | -update]
 [-j jar_name]
 ...

For example, to install classes in the addr.jar file, enter:

installjava -f "/home/usera/jars/addr.jar"

The -f parameter specifies an operating system file that contains a JAR. You must use the complete path name for the JAR.

This section describes retained JAR files (using -j) and updating installed JARs and classes (using new and update). For more information about these and the other options available with installjava, see the Utility Programs manual for your platform.

Retaining the JAR File

When a JAR is installed in a database, the server disassembles the JAR, extracts the classes, and stores them separately. The JAR is not stored in the database unless you specify installjava with the -j parameter.

Use of -j determines whether the Adaptive Server system retains the JAR specified in installjava or uses the JAR only to extract the classes to be installed.

If you do not specify the -j parameter, the Adaptive Server system does not retain any association of the classes with the JAR. This is the default option.
If you do specify the -j parameter, Adaptive Server installs the classes contained in the JAR in the normal manner, and then retains the JAR and its association with the installed classes.

If you retain the JAR file:

You can remove the JAR and all classes associated with it, all at once, with the remove java statement. Otherwise, you must remove each class or package of classes one at a time.
Other systems may request that the class associated with a given Java column be downloaded with the column value. If a class retains its association with the JAR, the Adaptive Server system can download the JAR, rather than individual classes.

Updating Installed Classes

The new and update clauses of installjava indicate whether you want new classes to replace currently installed classes.

If you specify new, you cannot install a class with the same name as an existing class.
If you specify update, you can install a class with the same name as an existing class, and the newly installed class replaces the existing class.
Warning!
If you alter a class used as a column datatype by reinstalling a modified version of the class, make sure that the modified class can read and use existing objects (rows) in tables using that class as a datatype. Otherwise, you may be unable to access existing objects without reinstalling the class.

Substitution of new classes for installed classes depends also on whether the classes being installed or the already installed classes are associated with a JAR. Thus:

If you update a JAR, all classes in the existing JAR are deleted and replaced with classes in the new JAR.
A class can only be associated with a single JAR. You cannot install a class in one JAR if a class of that same name is already installed and associated with another JAR. Similarly, you cannot install a class not-associated with a JAR if that class is currently installed and associated with a JAR.
You can, however, install a class in a retained JAR with the same name as an installed class not associated with a JAR. In this case, the class not associated with a JAR is deleted and the new class of the same name is associated with the new JAR.

If you want to reorganize your installed classes in new JARs, you may find it easier to first disassociate the affected classes from their JARs. See "Retaining Classes" for information about disassociating classes from JARs.

Referencing Other Java-SQL Classes

Installed classes can reference other classes in the same JAR file and classes previously installed in the same database, but they cannot references classes in other databases.

If the classes in a JAR file do reference undefined classes, an error may result:

If an undefined class is referenced directly in SQL, it causes a syntax error for "undefined class."
If an undefined class is referenced within a Java method that has been invoked, it throws a Java exception that may be caught in the invoked Java method or cause the general SQL exception described in "Exceptions in Java-SQL Methods" .

The definition of a class can contain references to unsupported classes and methods as long as they are not actively referenced or invoked. Similarly, an installed class can contain a reference to a user-defined class that is not installed in the same database as long as the class is not instantiated or referenced.

Viewing Information about Installed Classes and JARs

To view information about classes and JARs installed in the database, use the sp_helpjava system procedure.The syntax is:

sp_helpjava ['class' [, name [,detail]] | 'jar' [, name]]

To view detailed information about the Address class, for example, log in to isql and enter:

sp_helpjava "class",  Address, detail

Refer to "sp_helpjava" in the Reference Manual for more information.

Downloading Installed Classes and JARs

You can download copies of Java classes installed on one database for use in other databases or applications.

Use the extractjava system utility to download a JAR file and its classes to a client operating system file. For example, to download addr.jar to ~/home/usera/jars/addrcopy.jar, enter:

extractjava -j 'addr.jar'   -f
     '~/home/usera/jars/addrcopy.jar'

Refer to the Adaptive Server Utility Programs manual for more information about this utility.

Removing Classes and JARs

Use the Transact-SQL remove java statement to uninstall one or more Java-SQL classes from the database. remove java can specify one or more Java class names, Java package names, or retained JAR names. For example, to uninstall the package utilityClasses, from isql enter:

remove  java package "utilityClasses"

Adaptive Server does not allow you to remove classes that are used as the datatypes for columns and parameters. Make sure that you do not remove subclasses or classes that are used as variables or UDF return types.

When you specify remove java package the command deletes all classes in the specified package and all of its sub-packages.

See the Reference Manual for more information about remove java.

Retaining Classes

You can delete a JAR file from the database but retain its classes as classes no longer associated with a JAR. Use remove java with the retain classes option if, for example, you want to rearrange the contents of several retained JARs.

For example, from isql enter:

remove java jar 'utilityClasses' retain  classes

Once the classes are disassociated from their JARs, you can associate them with new JARs using installjava update.


	Expand Search