Creating distributed applications

User's Guide
PART 3. Java in the Database
CHAPTER 18. Data Access Using JDBC

Creating distributed applications

In a distributed application, parts of the application logic run on one machine, and parts run on another machine. With Adaptive Server Anywhere, you can create distributed Java applications, where part of the logic runs in the database server, and part on the client machine.

Adaptive Server Anywhere is capable of exchanging Java objects with an external, Java client.

The key task in a distributed application is for the client application to retrieve a Java object from a database. This section describes how to accomplish that task.

Related tasks

In other parts of this chapter, we have described how to retrieve several tasks that are related to retrieving objects, but which should not be confused with retrieving the object itself.

Querying Java objects describes how to retrieve an object into a SQL variable. This does not solve the problem of getting the object into your Java application.
Querying Java objects also describes how to retrieve the public fields and the return value of Java methods. Again, this is distinct from retrieving an object into a Java application.
Inserting and retrieving objects describes how to retrieve objects into server-side Java classes. Again, this is not the same as retrieving them into a client application.

Requirements for distributed applications

There are several tasks in building a distributed application.

To build a distributed application:

Any class running in the server must implement the Serializable interface. This is very simple.
The client-side application must import the class, so that the object can be reconstructed on the client side.
Use the sybase.sql.ASAUtils.toByteArray method on the server side to serialize the object.
Use the sybase.sql.ASAUtils.fromByteArray method on the client side to reconstruct the object.

These tasks are described in the following sections.

Implementing the Serializable interface

Objects are passed from the server to a client application in what is called serialized form. For an object to be sent to a client application, it must implement the Serializable interface. Fortunately, this is a very simple task.

To implement the Serializable interface:

Add the words implements java.io.Serializable to your class definition.

For example, the Product class in the jxmp\asademo subdirectory implements the Serializable interface by virtue of the following declaration:
```
public class Product implements java.io.Serializable 
```
Implementing the Serializable interface amounts to simply declaring that your class can be serialized.

The Serializable interface contains no methods and no variables. Serializing an object converts it into a byte stream which allows it to be saved to disk or sent to another Java application where it can be reconstituted, or deserialized.

A Java object that has been serialized in a database server, sent to a client application and deserialized, is identical in every way to its original state. Some variables in an object, however, either don't need to or, for security reasons, should not be serialized. Those variables are declared using the keyword transient, as in the following variable declaration.

transient String password;

When an object with this variable is deserialized, the variable will always contain its default value, null.

Custom serialization can be accomplished by adding writeObject() and readObject() methods to your class.

For more information about serialization, see Sun Microsystems' Java Development Kit (JDK).

Importing the class on the client side

On the client side, any class that retrieves an object has to have access to the proper class definition in order to use the object. To use the Product class, which is part of the asademo package, you must include the following line in your application:

import asademo.*

The asademo.jar file must be included in your CLASSPATH for this package to be located.

A sample distributed application

The JDBCExamples.java class contains three methods that illustrate distributed Java computing. These are all called from the main method. This method is called in the connection example described in Connecting from a JDBC client application, and is an example of a distributed application.

In this section we describe how one of these examples works. You can study the code for the other examples.

Serializing and deserializing query results

Here is the serializeColumn method of the JDBCExamples class.

private static void serializeColumn() throws Exception {
  Statement stmt;
  ResultSet rs;
  byte arrayb[]; 
  asademo.ContactInfo ci;
  String name;
  
  if ( conn != null ) {
    stmt = conn.createStatement();
    rs = stmt.executeQuery( "SELECT 
      sybase.sql.ASAUtils.toByteArray( JName.getName() ) AS Name, 
      sybase.sql.ASAUtils.toByteArray( jdba.contact.JContactInfo ) 
      FROM jdba.contact" );
    
    while ( rs.next() ) {
      arrayb = rs.getBytes("Name");
      name = ( String )sybase.sql.ASAUtils.fromByteArray( arrayb );
      arrayb = rs.getBytes(2);
      ci = (asademo.ContactInfo)sybase.sql.ASAUtils.fromByteArray( arrayb );
      System.out.println( "Name: " + name + 
                          "\n\tStreet: " + ci.street + 
                          "\n\tCity: " + ci.city + 
                          "\n\tState: " + ci.state + 
                          "\n\tPhone: " + ci.phone + 
                          "\n" );
      }
      System.out.println( "\n\n" );
    }
  }

Here is how the method works:

A connection already exists when the method is called. The connection object is checked, and as long as it exists, the code is executed.
A SQL query is constructed and executed. The query is as follows:
```
SELECT 
sybase.sql.ASAUtils.toByteArray( JName.getName() ) 
AS Name, 
sybase.sql.ASAUtils.toByteArray( jdba.contact.JContactInfo ) 
      FROM jdba.contact
```
This statement queries the jdba.contact table. It gets information from the JName and the JContactInfo columns. Instead of just retrieving the column itself, or a method of the column, the sybase.sql.ASAUtils.toByteArray function is used. This function converts the values to a byte stream so it can be serialized.
The client loops over the rows of the result set. For each row, the value of each column is deserialized into an object.
The output (System.out.println ) shows that the fields and methods of the object can be used as they could in their original state.

Other features of distributed applications

There are two other methods in JDBCExamples.java that use distributed computing:

serializeVariable This method creates a native Java object referenced by a SQL variable on the database server and passes it back to the client application.
serializeColumnCastClass This method is like the serializeColumn method, but demonstrates how to reconstruct subclasses. The column that is queried (JProd from the product table) is of data type asademo.Product. Some of the rows are asademo.Hat, which is a subclass of the Product class. The proper class is reconstructed on the client side.