Native UltraLite for Java User's Guide
  Tutorial: An Introductory Application

Lesson 1: Connect to the database

In this lesson you write, compile, and run a Java application that connects to a database using a schema you have created.

UltraLite database files have an extension of .udb. If an application attempts to connect to a database and the specified database file does not exist, UltraLite uses the schema file to create the database.

Before you begin

1. Create a directory to hold the files you create in this tutorial.

   This tutorial assumes the directory is c:\tutorial\java. If you create a directory with a different name, use that directory instead of c:\tutorial\java throughout the tutorial.

2. Create a database schema with the following characteristics using either ulinit or the UltraLite Schema Painter:

   Schema file name: tutcustomer.usm

   Table name: customer

   Columns in customer:

   Column Name	Data Type (Size)	Column allows NULL values?	Default value
   id	integer	No	autoincrement
   fname	char(15)	No	None
   lname	char(20)	No	None
   city	char(20)	Yes	None
   phone	char(12)	Yes	555-1234

   Primary key: ascending id

For more information, see the UltraLite Schema Painter Tutorial.

To connect to an UltraLite database

1. In your tutorial directory, create a file named Customer.java with the following content:

   import ianywhere.native_ultralite.*;
   import java.sql.SQLException;
   
   public class Customer
   {
     static Connection conn;
   
     public static void main( String args[] )
     {
       try{
         Customer cust = new Customer();
   
         // Clean up
         conn.close();
       } catch( SQLException e ){
         System.out.println(
           "Exception: " + e.getMessage() +
           " sqlcode=" + e.getErrorCode()
             );
         e.printStackTrace();
       }
     }
   }

   This code carries out the following tasks:

   • Imports the UltraLite library and the JDBC SQLException class

   • Declares a class named Customer.

   • Declares a static variable to hold the database connection object. This object will be shared among several methods later in the tutorial.

   • Invokes the class constructor, which is described in the next numbered step.

   • If an error occurs, prints the error code and a stack trace. For more information on the error code, you can look it up in the Adaptive Server Anywhere Error Messages book that is part of this documentation set.

2. Add a constructor to the class.

   The class constructor establishes a connection to the database.

   public Customer() throws SQLException
   {
     // Connect
     DatabaseManager dbMgr = new DatabaseManager();
     CreateParms parms = new CreateParms();
     parms.databaseOnDesktop = "c:\\tutorial\\java\\tutcustomer.udb";
     parms.schema.schemaOnDesktop = "c:\\tutorial\\java\\tutcustomer.usm";
     try {
       conn = dbMgr.openConnection( parms );
       System.out.println(
               "Connected to an existing database." );
     } catch( SQLException econn ) {
       if( econn.getErrorCode() ==
           SQLCode.SQLE_DATABASE_NOT_FOUND ){
         conn = dbMgr.createDatabase( parms );
         System.out.println(
               "Connected to a new database." );
       } else {
         throw econn;
       }
     }
   }

   This code carries out the following tasks:

   • Instantiates a new DatabaseManager object. All UltraLite objects are created from the DatabaseManager object.

   • Instantiates and defines a new CreateParms object. CreateParms stores the parameters necessary to connect to or create a database. Here, the parameters are the location of the database file on the desktop, and the location of the schema file on the desktop to use if the database does not exist.

     In this example, the locations are hardcoded for convenience. In a real application, they would not be hardcoded. In addition, these parameters are sufficient only for connections in the development environment; additional parameters are needed for the application to run on a Windows CE device. These additional parameters are described later in the tutorial.

   • If the database file does not exist, a SQLException is thrown. The code that catches this exception uses the schema file to create a new database and establish a connection to it.

   • If the database file does exist, a connection is established.

3. Compile the Customer class.

   It is recommended that you use Sun JDK 1.1.8 to compile the class. In addition, you must add the UltraLite library jul9.jar to your classpath. This library is in the ultralite\NativeUltraLiteForJava subdirectory of your SQL Anywhere or UltraLite Component Suite installation.

   The following command compiles the application. It should be entered on a single line at a command prompt:

   javac -classpath
   "%ASANY9%\ultralite\NativeUltraLiteForJava\jul9.jar;%classpath%"
   Customer.java

4. Run the application.

   The classpath must include the UltraLite library jul9.jar, as in the previous step.

   The application must also be able to load the DLL that holds UltraLite native methods. The DLL is jul9.dll in the ultralite\NativeUltraLiteForJava\win32 subdirectory of your SQL Anywhere or UltraLite Component Suite installation. This DLL can be in your system path or you can specify it on the java command line, as follows:

   java -classpath
   ".;%ASANY9%\ultralite\NativeUltraLiteForJava\jul9.jar"
   -Djul.library.dir=
   "%ASANY9%\ultralite\NativeUltraLiteForJava\win32" Customer

   This command must be all on one line, with no spaces inside the individual arguments.

The first time you run the application, it should write the following text to the command line:

Connected to a new database.

Subsequent times, it writes the following text to the command line:

Connected to an existing database.