3 Calling Java Methods in Oracle Database

JDBC

JDBC is an industry-standard API developed by Sun Microsystems that lets you embed SQL statements as Java method arguments. JDBC is based on the X/Open SQL Call Level Interface (CLI) and complies with the Entry Level of SQL-92 standard. Each vendor, such as Oracle, creates its JDBC implementation by implementing the interfaces of the standard java.sql package. Oracle provides the following JDBC drivers that implement these standard interfaces:

• The JDBC Thin driver, a 100 percent pure Java solution that you can use for either client-side applications or applets and requires no Oracle client installation.

• The JDBC OCI driver, which you use for client-side applications and requires an Oracle client installation.

• The server-side JDBC driver embedded in Oracle Database.

Using JDBC is a step-by-step process of performing the following tasks:

1. Obtaining a connection handle

2. Creating a statement object of some type for your desired SQL operation

3. Assigning any local variables that you want to bind to the SQL operation

4. Carrying out the operation

5. Optionally retrieving the result sets

This process is sufficient for many applications, but becomes cumbersome for any complicated statements. Dynamic SQL operations, where the operations are not known until run time, require JDBC. However, in typical applications, this represents a minority of the SQL operations.

SQLJ

SQLJ offers an industry-standard way to embed any static SQL operation directly into the Java source code in one simple step, without requiring the multiple steps of JDBC. Oracle SQLJ complies with the X3H2-98-320 American National Standards Institute (ANSI) standard.

SQLJ consists of a translator, which is a precompiler that supports standard SQLJ programming syntax, and a run-time component. After creating your SQLJ source code in a .sqlj file, you process it with the translator. The translator translates the SQLJ source code to standard Java source code, with SQL operations converted to calls to the SQLJ run time. In Oracle Database SQLJ implementation, the translator calls a Java compiler to compile the Java source code. When your SQLJ application runs, the SQLJ run time calls JDBC to communicate with the database.

SQLJ also enables you to catch errors in your SQL statements before run time. JDBC code, being pure Java, is compiled directly. The compiler cannot detect SQL errors. On the other hand, when you translate SQLJ code, the translator analyzes the embedded SQL statements semantically and syntactically, catching SQL errors during development, instead of allowing an end user to catch them when running the application.

Example Comparing JDBC and SQLJ

The following is an example of a JDBC code and a SQLJ code that perform a simple operation:

JDBC:

// Assume you already have a JDBC Connection object conn
// Define Java variables
String name;
int id=37115;
float salary=20000;

// Set up JDBC prepared statement.
PreparedStatement pstmt = conn.prepareStatement
("SELECT ename FROM emp WHERE empno=? AND sal>?");
pstmt.setInt(1, id);
pstmt.setFloat(2, salary);

// Execute query; retrieve name and assign it to Java variable.
ResultSet rs = pstmt.executeQuery();
while (rs.next())
{
  name=rs.getString(1);
  System.out.println("Name is: " + name);
}

// Close result set and statement objects.
rs.close()
pstmt.close();

Assume that you have established a JDBC connection, conn. Next, you must do the following:

1. Define the Java variables, name, id, and salary.

2. Create a PreparedStatement instance.

   You can use a prepared statement whenever values in the SQL statement must be dynamically set. You can use the same prepared statement repeatedly with different variable values. The question marks (?) in the prepared statement are placeholders for Java variables. In the preceding example, these variables are assigned values using the pstmt.setInt() and pstmt.setFloat() methods. The first ? refers to the int variable id and is set to a value of 37115. The second ? refers to the float variable salary and is set to a value of 20000.

3. Run the query and return the data into a ResultSet object.

4. Retrieve the data of interest from the ResultSet object and display it. In this case, the ename column. A result set usually contains multiple rows of data, although this example has only one row.

SQLJ:

String name;
int id=37115;
float salary=20000;
#sql {SELECT ename INTO :name FROM emp WHERE empno=:id AND sal>:salary};
System.out.println("Name is: " + name);

In addition to allowing SQL statements to be directly embedded in Java code, SQLJ supports Java host expressions, also known as bind expressions, to be used directly in the SQL statements. In the simplest case, a host expression is a simple variable, as in this example. However, more complex expressions are allowed as well. Each host expression is preceded by colon (:). This example uses Java host expressions, name, id, and salary. In SQLJ, because of its host expression support, you do not need a result set or equivalent when you are returning only a single row of data.

Complete SQLJ Example

This section presents a complete example of a simple SQLJ program:

import java.sql.*;
import sqlj.runtime.ref.DefaultContext;
import oracle.sqlj.runtime.Oracle;

#sql ITERATOR MyIter (String ename, int empno, float sal);

public class MyExample
{
  public static void main (String args[]) throws SQLException
  {
    Oracle.connect("jdbc:oracle:thin:@oow11:5521:sol2", "scott", "tiger");
    #sql { INSERT INTO emp (ename, empno, sal) VALUES ('SALMAN', 32, 20000) };
    MyIter iter;
    #sql iter={ SELECT ename, empno, sal FROM emp };
    while (iter.next())
    {
      System.out.println(iter.ename()+" "+iter.empno()+" "+iter.sal());
    }
  }
}

In the preceding example, you do the following:

1. Declare your iterators.

   SQLJ uses a strongly-typed version of JDBC result sets, known as iterators. An iterator has a specific number of columns of specific data types. You must define your iterator types before using them, as in this example.

   #sql ITERATOR MyIter (String ename, int empno, float sal);
   

   This declaration results in SQLJ creating an iterator class, MyIter. Iterators of type MyIter can store results whose first column maps to a Java String, second column maps to a Java int, and third column maps to a Java float. This definition also names the three columns as ename, empno, and sal, to match the column names of the referenced table in the database. MyIter is a named iterator.

2. Connect to the database.

   Oracle.connect("jdbc:oracle:thin:@oow11:5521:sol2","scott", "tiger");
   

   SQLJ provides the Oracle class and its connect() method accomplishes the following important tasks:

   1. Registers Oracle JDBC drivers that SQLJ uses to access the database, in this case, the JDBC Thin driver.

   2. Opens a database connection for the specified schema, in this case, user scott with password tiger, at the specified URL. In this case, the URL points to host oow11, port 5521, and SID so12.

   3. Establishes this connection as the default connection for the SQLJ statements. Although each JDBC statement must explicitly specify a connection object, a SQLJ statement can either implicitly use a default connection or optionally specify a different connection.

3. Process a SQL statement. The following is accomplished:

   1. Insert a row into the emp table:

      #sql {INSERT INTO emp (ename, empno, sal) VALUES ('SALMAN', 32, 20000)};
      

   2. Instantiate and populate the iterator:

      MyIter iter;
      #sql iter={SELECT ename, empno, sal FROM emp};
      

4. Access the data that was populated within the iterator.

   while (iter.next())
   {
     System.out.println(iter.ename()+" "+iter.empno()+" "+iter.sal());
   }
   

   The next() method is common to all iterators and plays the same role as the next() method of a JDBC result set, returning true and moving to the next row of data, if any rows remain. You can access the data in each row by calling iterator accessor methods whose names match the column names. This is a characteristic of all named iterators. In this example, you access the data using the methods ename(), empno(), and sal().

SQLJ Strong Typing Paradigm

SQLJ uses strong typing, such as iterators, instead of result sets. This enables the SQL instructions to be checked against the database during translation. For example, SQLJ can connect to a database and check your iterators against the database tables that will be queried. The translator will verify that they match, enabling you to catch SQL errors during translation that would otherwise not be caught until a user runs your application. Furthermore, if changes are subsequently made to the schema, then you can determine if these changes affect the application by rerunning the translator.

Translating a SQLJ Program

Integrated development environments (IDEs), such as Oracle JDeveloper, can translate, compile, and customize your SQLJ program as you build it. Oracle JDeveloper is a Microsoft Windows-based visual development environment for Java programming. If you are not using an IDE, then use the front-end SQLJ utility, sqlj. You can run it as follows:

%sqlj MyExample.sqlj

The SQLJ translator checks the syntax and semantics of your SQL operations. You can enable online checking to check your operations against the database. If you choose to do this, then you must specify an example database schema in your translator option settings. It is not necessary for the schema to have data identical to the one that the program will eventually run against. However, the tables must have columns with corresponding names and data types. Use the user option to enable online checking and specify the user name, password, and URL of your schema, as in the following example:

%sqlj -user=scott@jdbc:oracle:thin:@oow11:5521:sol2 MyExample.sqlj
Password: password

Running a SQLJ Program in the Server

Many SQLJ applications run on a client. However, SQLJ offers an advantage in programming stored procedures, which are usually SQL-intensive, to run on the server.

There is almost no difference between writing a client-side SQLJ program and a server-side SQLJ program. The SQLJ run-time packages are automatically available on the server. However, you must consider the following:

• There are no explicit database connections for code running on the server. There is only a single implicit connection. You do not need the usual connection code. If you are porting an existing client-side application, then you do not have to remove the connection code, because it will be ignored.

• The JDBC server-side internal driver does not support auto-commit functionality. Use SQLJ syntax for manual commits and rollbacks of your transactions.

• On the server, the default output device is a trace file, not the user screen. This is, typically, an issue only for development, because you would not write to System.out in a deployed server application.

To run a SQLJ program on the server, presuming you developed the code on a client, you have two options:

• Translate your SQLJ source code on the client and load the individual components, such as the Java classes and resources, on the server. In this case, it is easy to bundle them into a .jar file first and then load them on the server.

• Load your SQLJ source code on the server for the embedded translator to translate.

In either case, use the loadjava tool to load the file or files to the server.

Converting a Client Application to Run on the Server

To convert an existing SQLJ client-side application to run on the server, after the application has already been translated on the client, perform the following steps:

1. Create a .jar file for your application components.

2. Use the loadjava tool to load the .jar file on the server.

3. Create a SQL wrapper in the server for your application. For example, to run the preceding MyExample application on the server, run the following statement:

   CREATE OR REPLACE PROCEDURE sqlj_myexample AS LANGUAGE JAVA NAME `MyExample.main(java.lang.String[])';
   

You can then run sqlj_myexample, similar to any other stored procedure.

Interacting with PL/SQL

All Oracle JDBC drivers communicate seamlessly with Oracle SQL and PL/SQL, and it is important to note that SQLJ interoperates with PL/SQL. You can start using SQLJ without having to rewrite any PL/SQL stored procedures. Oracle SQLJ includes syntax for calling PL/SQL stored procedures and also lets you embed anonymous PL/SQL blocks in SQLJ statements.