The Sybase runtime environment for Java

User's Guide
PART 3. Java in the Database
CHAPTER 16. Welcome to Java in the Database

The Sybase runtime environment for Java

This section describes the Sybase runtime environment for Java, and how it differs from a standard Java runtime environment.

Java version

The Sybase Java VM executes a subset of JDK version 1.1.6.

Between release 1.0 of the Java Developer's Kit (JDK) and release 1.1, several new APIs where introduced and a number were deprecated, that is, the use of certain APIs became no longer recommended and support for them may be dropped in future releases.

A Java class file that uses deprecated APIs generates a warning when it is compiled, but does still execute on a Java virtual machine built to release 1.1 standards, such as the Sybase VM.

The internal JDBC driver supports JDBC version 1.1.

For Info For more information on the JDK 1.1 APIs that are supported, please see Built-in Java classes.

Java classes in the database

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

The Sybase runtime Java classes.
User-defined classes
Table values

Sybase runtime Java classes

The Sybase runtime Java classes are the low-level classes installed to Java-enable a database. These classes include a subset of the Java API.

Like all Java code, Java API functions take the form of classes. These classes are specialized in that, at a low level, they have functionality that no user-defined class could recreate. The Java API is always available to classes in the database.

The Java API classes can be used as pre-defined functions that perform specialized tasks.

Another way to use the Java APIs is to incorporate them in user-created classes: either inheriting their functionality from a Java API class or using it within a calculation or operation in a method.

Some API classes

Some Java API classes of interest include:

Primitive Java data types All primitive (native) data types in Java have a corresponding class. In addition to being able to create objects of these types, the classes have additional, often useful functionality.

The Java integer data type has a corresponding class in java.lang.Integer.
The utility package The package java.util.* contains a number of very helpful classes whose functionality has no parallel in the SQL functions available in Adaptive Server Anywhere.

Some of the classes include:
- Hashtable which maps keys to values.
- StringTokenizer which breaks a String down into individual words.
- Vector which holds an array of objects whose size can change dynamically
- Stack which holds a last-in, first-out stack of objects.
JDBC for SQL operations The package java.sql.* contains the classes needed by Java objects to extract data from the database using SQL statements.

API classes outside the database

Unlike other Java classes, the Java API is not installed into the database. Rather, they are present as files on disk.

User-defined classes

User-defined classes are installed into a database using the INSTALL statement.

Once installed, they are available from other classes in the database and are available from SQL as user-defined data types.

For information on installing classes, see Installing Java classes into a database.

Table values

Instances of classes that have been saved as a value in a table can be retrieved like any other data in a table.

For example, the following SQL statements would successfully return a reference to an instance of a Java class called JClass. The statements assume both the variable and the column named JCol are of type JClass; and the correct instance, as specified by the WHERE clause of the query, had been saved to the table named T1.

CREATE VARIABLE var JClass;
SET var = (SELECT JCol 
            FROM T1
            WHERE JCol.empName = 'John Smith');

Java syntax in SQL statements

The following table illustrates how some aspects of Java syntax are carried out when Java references are made from SQL.

Language feature

Java syntax

SQL syntax

"." dot operator

"." (dot)

>> or "." (dot)

"." dot identifier

"." (dot)

"."

String literal (quotes)

"String"

'String'

Import statement

import java_package.*;

Does not apply

System.out.println( str )

prints str to command line

prints str to server window

Language feature	Java syntax	SQL syntax
"." dot operator	"." (dot)	>> or "." (dot)
"." dot identifier	"." (dot)	"."
String literal (quotes)	"String"	'String'
Import statement	import java_package.*;	Does not apply
System.out.println( str )	prints str to command line	prints str to server window

The use of all the examples above, plus additional notes on Java syntax usage, are explained in the following sections.

Identifying Java methods and fields

The dot in SQL

In SQL statements, the dot is used to identify columns of tables, as in the following query:

SELECT employee.emp_id
FROM employee

The dot is also used in qualified object names to indicate object ownership:

SELECT emp_id
FROM dba.employee

The dot in Java

In Java instructions, the dot is used as an operator to invoke the methods and fields of a Java class or object. It is also used as an identifier to identify class name hierarchies, as in the fully qualified class name java.util.Hashtable.

The dot character gets used for two distinct purposes.

As an identifier, the dot identifies the word that follows it as a name. This helps locate the package, class or class method being referenced.
As an operator, the dot causes a method to be invoked.

In the following Java code fragment, the dot is an identifier on the left hand side of the first line of code. On right hand side of the first line, and on the second line of code, it is an operator.

java.util.Random rnd = new java.util.Random();
int i = rnd.nextInt();

Invoking Java methods from SQL

To indicate methods and fields of Java objects in a SQL statement, you can use either the dot or the double right angle bracket (>>). The dot operator looks more like Java, but the double right angle bracket is less ambiguous: it cannot be confused with a database object.

To indicate class names, you must use the dot.

>> in SQL is not the same as >> in Java
The double right angle bracket operator is only used in SQL statements where a Java dot operator is otherwise expected. Within a Java class, the double right angle bracket is not a replacement for the dot operator and has a completely different meaning in its role as the right bit shift operator.

For example, the following batch of SQL statements is valid:

CREATE    VARIABLE rnd java.util.Random;
SET rnd = NEW java.util.Random();
SELECT rnd>>nextInt();

The result of the SELECT statement is a randomly generated integer.

Using the variable created in the previous SQL code example, the following SQL statement illustrates the correct use of a class method.

SELECT java.lang.Math.abs( rnd>>nextInt() );

In the above statement, abs is a method, but it is a class method. It is only the name of the method at the end of the name of class. The dot preceding it is only used for identification, therefore it is not substituted with a double right angle bracket, as is the case for the nextInt() method.

The dot character is an operator when it is acting on an instance of a class.

For example the following code is valid, even though the ">>" substitute operator is being used with a static method.

CREATE VARIABLE mth java.lang.Math;
SET mth = NEW java.lang.Math();
SELECT mth>>abs( rnd>>nextInt() )

This is successful because the target of the operation is an object, not a class.

Java is case sensitive

Java syntax works as you would expect it to, and SQL syntax is unaltered by the presence of Java classes. This is true even if the same SQL statement contains both Java and SQL syntax. It's a simple statement but with far-reaching implications.

Java is case sensitive. The Java class FindOut is a completely different class from the class Findout. SQL is case insensitive in many ways: the case of SQL keywords and identifiers is ignored.

Java case sensitivity is preserved even when embedded in a SQL statement that is case insensitive. The Java parts of the statement must be case sensitive, even though the parts previous to and following the Java syntax can be written in upper or lower case.

For example the following SQL statements will successfully execute because the case of Java objects, classes and operators is respected, even though there is variation in the case of the remaining SQL parts of the statement.

SeLeCt java.lang.Math.random();

Data types

When a Java class is used as a data type for a column, it is being used as a user-defined SQL data type. However, it is still case sensitive. This convention prevents ambiguities with Java classes that differ only in case.

Strings in Java and SQL

String literals are identified in Java by a set of double quotes, as in the following Java code fragment.

String str = "This is a string";

In SQL, however, strings are marked by single quotes, and double quotes indicate an identifier, as illustrated by the following SQL statement.

INSERT INTO TABLE DBA.t1
VALUES( 'Hello' )

You should always use the double quote in Java source code, and single quotes in SQL statements.

For example, the following SQL statements are valid.

CREATE VARIABLE str char(20);
SET str = NEW java.lang.String( 'Brand new object' )

The following Java code fragment is also valid, if used within a Java class.

String str = new java.lang.String( 
            "Brand new object" );

Printing to the command line

Printing to the command line is a quick method of checking variable values and execution results at various points of code execution. When the method in the second line of the following Java code fragment is encountered, the string argument it accepts is printed out to the command line.

String str = "Hello world";
System.out.println( str );

In Adaptive Server Anywhere, this method causes the string argument to be printed out to the server window.

Executing the above Java code within the database is the equivalent of the following SQL statement.

MESSAGE 'Hello world'

Using the main method

When a class contains a main method that matches the following method declaration, it is executed automatically by most Java run time environments, such as the Sun Java interpreter. Normally, this static method will execute when the class is loaded, without needing to be explicitly invoked.

public static void main( String args[ ] ) { }

It is a useful class for testing the functionality of Java objects: you are always guaranteed this method will be called first, when the Sun Java runtime system is started.

In Adaptive Server Anywhere the main method is not automatically invoked. In Adaptive Server Anywhere the Java runtime system is always available. The functionality of objects and methods can be tested in an ad hoc, dynamic manner using SQL statements. In many ways this is a far more flexible method of testing Java class functionality.

Scope and persistence

SQL variables are persistent only for the duration of connection. This is unchanged from previous versions of Adaptive Server Anywhere, and is unaffected whether the type of the variable is a Java class or a native SQL data type.

The persistence of Java classes is analogous to tables in a database: Tables exist in the database until they are dropped, regardless of whether they hold data or ever get used. Java classes that have been installed to a database are similar: they are available for use until they are explicitly removed.

All installed Java classes are available until they are removed from the database with a REMOVE statement.

For Info For more information on removing classes, see REMOVE statement.

A class method in an installed Java class can be called at any time, from a SQL statement. The following statement can be executed anywhere SQL statements can be executed.

SELECT java.lang.Math.abs(-342)

A Java object is only available in two forms: as the value of a variable, or a value in a table. The scope of a specific instance of a Java class is limited to: whether or not it exists; and whether or not the field or method of the variable or table that contains the instance can be accessed (as determined by its access modifier: public, private or protected).

Java escape characters in SQL statements

In Java code, escape characters can be used to insert certain unique characters into strings when a string is being declared. Consider the following Java code, which inserts a new line and tab in front of a sentence containing an apostrophe.

String str = "\n\t\This is the object\'s string literal.";

The use of Java escape characters is permitted in Adaptive Server Anywhere only when it is being used by Java classes.

From within SQL, however, the rules that apply to strings in SQL must be followed.

For example, to pass a string value to a field using a SQL statement, the following statement could be used, but the Java escape characters could not.

SET obj>>str = '\nThis is the object''s string field';

For Info for more information on SQL string handling rules, see Statement elements.

Keyword conflicts

SQL keywords can conflict with the names of Java classes, including API classes. This occurs when the name of a class, such as the Date class, which is a member of the java.util.* package, is referenced. SQL reserves the word Date for use as a keyword, even though it also the name of a Java class.

When such ambiguities are encountered double quotes can be used to identify that the word in question is not being used as the SQL reserved word.

For example, the following SQL statement causes an error because Date is a keyword and its use is reserved within SQL.

-- This statement is incorrect
CREATE VARIABLE dt java.util.Date

However the following two statements work correctly because the word Date is quoted.

CREATE VARIABLE dt java.util."Date";
SET dt = NEW java.util."Date"(1997, 11, 22, 16, 11, 01)

The variable dt now contains the date: November 22, 1997, 4:11 p.m.

Use of import statements

It is common in a Java class declaration to include an import statement to access other, external classes. This makes classes that are members of Java package specified by the import statement available to the class being declared using only abbreviated names. External classes can always be accessed using a fully qualified name.

For example, the Stack class of the java.util package can be reference in a class two ways:

explicitly using the name java.util.Stack, or
implicitly using the name Stack if class declaration contains the following import statement.
```
import java.util.*;
```

All classes used in Adaptive Server Anywhere are compiled, therefore the Java compiler has already checked if a reference to a class is properly qualified.

The class being used within Adaptive Server Anywhere may or may not have used an import statement, depending on the Java developer's design.

Classes further up in the hierarchy must also be installed.

The only restriction on compiled classes is that a class referenced by another class, either explicitly with a fully qualified name or implicitly using an import statement, must also be installed in the database.

The import statement works as intended within compiled classes, however, within the Adaptive Server Anywhere runtime environment, there is no equivalent to the import statement. All class names used in SQL statements or stored procedures must be fully qualified.

For example, to create a variable of type String, the class is referenced using the fully qualified name: java.lang.String.

Using the CLASSPATH variable

The CLASSPATH environment variable is used by Sun's Java runtime environment and by the Sun JDK Java compiler to locate the classes that are referenced within Java code. A CLASSPATH variable provides the link between Java code such as ...

import java.io.*

... and the actual file path or URL location of the classes being referenced.

For example, the above statement allows all the classes in the java.io package to be referenced without a fully qualified name. Only the class name is required in the following Java code to use classes from the java.io package. The CLASSPATH environment variable on the system where the Java class declaration is to be compiled must include the location of the java directory, the root of the java.io package.

CLASSPATH ignored at runtime

The CLASSPATH environment variable does not affect the Adaptive Server Anywhere runtime environment for Java during the execution of Java operations.

When a class is installed to a database, its full package name is retained, and so the CLASSPATH environment variable is not used.

CLASSPATH used to install classes

The CLASSPATH variable can, however, be used to locate a file during the installation of classes. For example, the following statement installs a user-created Java class to a database, but only specifies the name of the file, not its full path and name. (Note that this statement involves no Java operations.)

INSTALL JAVA NEW
FROM FILE 'Invoice.class'

If the file specified is in a directory or zip file specified by the CLASSPATH environmental variable, Adaptive Server Anywhere will successfully locate the file and install the class.

Public fields

It is a common practice in object oriented programming to define class fields as private and make their values available only through public methods.

Many of the examples used in this documentation render fields as public so that examples are more compact and easier to read. It is also the case, however, that using public fields in Adaptive Server Anywhere does offer a performance advantage over accessing public methods. However, in order to update a field in a table, the class must have a method that sets the value of the field.

The general convention followed in this documentation is that a user-created Java class designed for use in Adaptive Server Anywhere exposes its main values in its fields. Methods are used to contain computational automation and logic that may act on these fields.

This applies to class-level variables only. Local variables, those declared within methods only, do not have the public or private access modifiers.