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 2.0 (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 automatically 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 12, "Reference Topics" for a list of supported and unsupported 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 native JDBC driver that comes with Adaptive Server supports JDBC version 1.2. It is compliant with and supports several classes and methods of JDBC version 2.0. See Chapter 12, "Reference Topics," for a complete list of supported and not supported classes and methods.

If your system requires a JDBC driver on the client, you must use jConnect version 5.2 or later, which supports JDBC version 2.0.

The Java VM

To ensure that each invoked method is executed as quickly as possible, Sybase provides a Java VM. The Java VM runs on the server. The Java VM requires little or no administration once installation is complete.

Configuring memory for Java in the database

Use the sp_configure system procedure to change memory allocations for Java in Adaptive Server. You can change the memory allocation for:

size of global fixed heap - specifies memory space for internal data structures.
size of process object fixed heap - specifies the total memory space available for all user connections using the Java VM.
size of shared class heap - specifies the shared memory space for all Java classes called into the Java VM.

See "Java Services" in the System Administration Guide for complete information about these configuration parameters.

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 shut down and restart 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 sp_configure. 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 12, "Reference Topics".

Compiling Java code

This step turns the class declaration containing Java code into a new, separate file containing bytecode. 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. JAR files allow you to install or remove related classes as a group.

Installing uncompressed JARs

To install Java classes in a database, save the classes or packages in a JAR file, in uncompressed form. To create an uncompressed JAR file that contains Java classes, use the Java jar cf0 ("zero") 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

Installing compressed JARs

You can also install a compressed JAR file if you first expand the compressed file using the x option of the jar command. In this UNIX example, abcPackage is a compressed file.

Place the compressed JAR file in an empty directory and expand it:
```
jar xf0 abcPackage.jar
```
Delete the compressed JAR file so that it won't be included in the new, uncompressed JAR file:
```
rm abcPackage.jar
```
Create the uncompressed JAR file:
```
jar cf0 abcPackage.jar*
```

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.

See the Adaptive Server Enterprise Utilities Guide 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]
[ -S server_name ]
[ -U user_name ]
[ -P password ]
[ -D database_name ]
[ -I interfaces_file ]
[ -a display_charset ]
[ -J client_charset ]
[ -z language ]
[ -t timeout ]

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

When you install a JAR file, Application Server copies the file to a temporary table and then installs it from there. If you install a large JAR file, you may need to expand the size of tempdb using the alter database command.

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 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 do not specify the -j parameter, Adaptive Server does not retain any association of the classes with the JAR. This is the default option.

Sybase recommends that you specify a JAR name so that you can better manage your 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.
You can use extractjava to download the JAR to an operating system file. See "Downloading installed classes and JARs".

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 original 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 be associated only 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 more information.

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 reference 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 syntax is:

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

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

sp_helpjava "class", Address, detail

See "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'

See the Utility Guide manual for more information.

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 or that are referenced by SQLJ functions or stored procedures.

You must make sure that you do not remove subclasses or classes that are used as variables or UDF return types.

remove java package 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 with the new keyword.


	Expand Search