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

Installing Java classes into a database

Before you install a Java class into a database, you must compile it. This section describes how you install Java classes once you have compiled them.

You can install Java classes into a database in several ways:

• As a single class     You can install a single class into a database from a compiled class file. Class files typically have extension .class.

• As a jar     You can install a set of classes all at once if they are held in a jar file. The jar file must be uncompressed. Jar files typically have extension .jar or .zip.

DBA authority is required to install a class or jar.

  Creating a class

Overall, the steps involved in creating your own class include the following. The details of each step may differ, depending on whether a Java development tool such as Sybase PowerJ is being used:

  To create a class:

1. Define your class     Write the Java code that defines your class. If you are using the Sun Java SDK then you can use a text editor. If you are using a development tool such as Sybase PowerJ, the development tool provides instructions.

   Use only supported classes     If your class uses any Java API classes, make certain they are among the list of supported API classes as listed in Built-in Java classes.

2. Name and save your class     Save your class declaration (Java code) in a file with an extension of .java. Make certain the name of the file is the same as the name of the class and that the case of both names is identical.

   For example, a class called Utility should be saved in a file called Utility.java.

3. Compile your class     This step turns your 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. A compiled Java class can be run in a Java runtime environment, regardless of the platform it was compiled on or the operating system of the runtime environment.

   The Sun JDK contains a Java compiler, Javac.exe.

   Java-enabled databases only     Any compiled Java class file can be installed in a database. However, Java operations using an installed class can only take place if the Java runtime libraries have been installed: that is, if the database has been Java-enabled as described in Java-enabling a database.

  Installing a class

To make your Java class available within the database, you install the class into the database.

You can install a class from Sybase Central, or using the INSTALL statement from Interactive SQL or other application.

You require DBA authority to install a class.

Installing a class from Sybase Central 

  To install a class from Sybase Central:

1. From Sybase Central, connect to a database as a user with DBA authority.

2. Open the Java Objects folder for the database.

3. Double-click Add Java Class or JAR, and follow the instructions in the wizard.

Installing a class from Interactive SQL 

From Interactive SQL, you use the INSTALL statement to install a class. You must know the path and file name of the class you wish to install.

  To install a class, using Interactive SQL:

1. From Interactive SQL, connect to a database as a user with DBA authority.

2. Enter the following statement:

   INSTALL JAVA NEW
   FROM FILE 'path\\ClassName.class'

   where path is the directory in which the class file is held, and ClassName.class is the name of the class file.

   The double backslash ensures that the backslash is not treated as an escape character.

For example, to install a class held in a file named Utility.class held in the directory c:\source, you would enter the following statement:

INSTALL JAVA NEW
FROM FILE 'c:\\source\\Utility.class'

If you use a relative path, it must be relative to the current working directory of the database server.

You can use any other application that can send SQL statements to the server to send the INSTALL statement.

  Installing a JAR

It is useful and common practice to collect sets of related classes together in packages, and to store one or more packages in a JAR file. For information on JAR files and packages, see the accompanying online book, Thinking in Java, or another book on programming in Java.

You install a JAR file the same way as installing a class file. A JAR file can have the extension JAR or ZIP. Only uncompressed files can be used.

jar cf0 myjar.jar *.class

Each JAR file must have a name in the database. Usually, you will use the same name as the JAR file, without the extension. For example, if you install a JAR file named myjar.zip, you would generally give it a JAR name of myjar.

Installing a JAR from Sybase Central 

You can install a JAR file from Sybase Central in the same way you install a single class file. For instructions, see Installing a class. The only additional information you need to provide is the JAR name to be used in the database.

Installing a JAR from Interactive SQL 

The steps to install a JAR are very similar to installing a single class.

  To install a JAR, using Interactive SQL:

1. From Interactive SQL, connect to a database as a user with DBA authority.

2. Enter the following statement:

   INSTALL JAVA NEW
   JAR 'jarname'
   FROM FILE 'path\\JarName.jar'

  Updating classes and Jars

You can update classes and Jars using Sybase Central or by entering an INSTALL statement in Interactive SQL or some other client application.

To update a class or JAR, you must have a newer version of the compiled class file or JAR file available in a file on disk.

You must have DBA authority to update a class or jar.

  To update a class or JAR from Sybase Central:

1. In Sybase Central, locate the class or jar you wish to update.

2. Right-click the class or JAR, and select Update from the popup menu.

3. Enter the name of the file holding the updated compiled class in the field provided, and click OK to update the class or JAR.

  To update a class or jar from Interactive SQL:

1. In Interactive SQL, enter the following statement:

   INSTALL JAVA UPDATE
   [ JAR 'jarname' ]
   FROM FILE 'filename'

   If you are updating a JAR, you must enter the name by which the JAR is known in the database.

Existing Java objects and updated classes 

You may have instances of a Java class stored as Java objects in your database, as values in a column that uses the class as its data type.

You can still update the class as long as the fields and methods stored in the tables are compatible with the new class definition. For example, you can fix bugs in a method and install the new class definition, and all existing Java objects will use the new definition.

When updated classes take effect 

The new definition is only used by connections established after the class is installed, or which use the class for the first time after the class is installed. Once a class definition is loaded by the Virtual Machine, it is held in memory until the connection is closed.

If you have been using a Java class, or objects based on a class, in the current connection, you need to disconnect and reconnect in order to use the new class definition.

     To understand why the updated classes take effect in this manner, you need to know a little about how the VM works. For information, see Configuring memory for Java.

Objects stored in serialized form 

Java objects can use the updated class definition because they are stored in serialized form. The serialization format used is designed specifically for the database, and is not the Sun Microsystems serialization format. This does not produce compatibility issues, because all serialization and deserialization is carried out by the internal Sybase VM.