Login | Register
My pages Projects Community openCollabNet

Axion: Quick Start

This document provides a brief tutorial on getting up and running with Axion.


Installation

Obtain an Axion binary from the downloads page, or build Axion from scratch.

To run Axion, you'll need the following JARs in your classpath:

Commons-Collections (2.1 or later)

http://jakarta.apache.org/commons/collections.html

Commons-Primitives (1.0 or later)

http://jakarta.apache.org/commons/primitives

Commons-Logging (1.0 or later)

http://jakarta.apache.org/commons/logging.html

Commons-Codec (1.1 or later)

http://jakarta.apache.org/commons/codec/

(Only needed if you'd like to use the BASE64ENCODE and BASE64DECODE functions.)


Operating Modes

Currently Axion only runs as an in-process database. The database engine classes are executed in the same VM as your client code.

Axion supports both transient (in-memory) and persistent modes.

The data in a transient database disappears when the database is SHUTDOWN or the VM exits. These are suitable for unit testing database applications, or for temporary work areas.

Persistent databases are disk-based. Their data persists beyond the lifespan of a single Java VM. Note that it is possible to create transient tables within a persistent database. The transient tables will disappear on SHUTDOWN or when the VM exits, while the disk-based table will continue to persist.

Axion is thread-safe, and supports as many concurrent connections as your your client code creates. Like other JDBC engines, it's safest to use each Connection in at most one thread at a time.


Creating an Axion Database

To create a new Axion database you simply connect to it--if it doesn't already exist, it will be created. See Connecting to an Axion Database.


Connecting to an Axion Database

Axion databases can be accessed via the JDBC interface. AxionDriver is the factory for creating JDBC connections to an Axion database, and may be registered with the DriverManager in the common ways:

  1. By invoking Class.forName on (or otherwise instantiating) "org.axiondb.jdbc.AxionDriver": 
    Class.forName("org.axiondb.jdbc.AxionDriver");
  2. Using the jdbc.drivers property: 
    java -Djdbc.drivers=org.axiondb.jdbc.AxionDriver ...

JDBC Connections can then be obtained from the DriverManager: 

Connection conn = DriverManager.getConnection(axion-connect-string);

Where the axion-connect-string takes the form: 

jdbc:axiondb:database-name[:database-directory]

The database-name is the name of the database, similar to an Oracle SID. The optional database-directory specifies the (relative or absolute) directory in which the database files will be found or created. When the database-directory is omitted, a transient database is created.


Using Axion

To run Axion, you'll need the Axion's JAR (axiondb-*.jar) and the requisite third-party JARs in your CLASSPATH.

Using Axion's Console Client

Axion includes a simple console-based JDBC/SQL client application that you can use to experiment or interact with an Axion database. To use it, simple invoke: 

java -cp axiondb.jar:commons-collections.jar:commons-primitives.jar:commons-logging.jar \
     org.axiondb.tools.Console dbname [dbpath]

or on Windows: 

java -cp axiondb.jar;commons-collections.jar;commons-primitives.jar;commons-logging.jar \
     org.axiondb.tools.Console dbname [dbpath]

You can enter arbitrary SQL commands and queries via the console. For example:

Axion Console Example 

> java org.axiondb.Axion egdb
Type 'quit' to quit the program.
axion> create table PERSON ( FIRSTNAME varchar, LASTNAME varchar )
axion> insert into PERSON ( FIRSTNAME, LASTNAME ) values ( 'Jane', 'Doe' )
axion> insert into PERSON ( FIRSTNAME, LASTNAME ) values ( 'John', 'Doe' )
axion> select FIRSTNAME, LASTNAME from PERSON
+===========+==========+
| FIRSTNAME | LASTNAME |
+===========+==========+
|      Jane |      Doe |
+-----------+----------+
|      John |      Doe |
+-----------+----------+
axion> select FIRSTNAME, LASTNAME from PERSON where FIRSTNAME = 'John'
+===========+==========+
| FIRSTNAME | LASTNAME |
+===========+==========+
|      John |      Doe |
+-----------+----------+
axion> quit
>

See tools for more on the Axion console and other JDBC/SQL clients.


Using Axion via JDBC

Axion can be used like any other database that supports JDBC. Using Axion via JDBC shows a simple example.

(A complete tutorial on JDBC is beyond the scope of this document. For more on JDBC, see http://java.sun.com/jdbc/.)

Using Axion via JDBC 
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;

public class AxionExample {
    public static void main(String[] args) throws Exception {
        Class.forName("org.axiondb.jdbc.AxionDriver");
        AxionExample eg = new AxionExample();
        eg.createTables("jdbc:axiondb:egdb");
        eg.populateTables("jdbc:axiondb:egdb");
        eg.printReport("jdbc:axiondb:egdb");
    }

    public void createTables(String uri) throws SQLException {
        System.out.println("Creating tables");
        Connection conn = null;
        Statement stmt = null;
        try {
           conn = DriverManager.getConnection(uri);
           stmt = conn.createStatement();
           stmt.execute("create table PERSON ( PERSON_ID integer, " +
                        "FIRSTNAME varchar, LASTNAME varchar )");
           stmt.execute("create table PLACE ( PLACE_ID integer, " +
                        "CITY varchar, STATE varchar )");
           stmt.execute("create table PERSON_PLACE_MAP ( " +
                        "PERSON_ID integer, PLACE_ID integer )");
        } finally {
           try { stmt.close(); } catch(Exception e) { }
           try { conn.close(); } catch(Exception e) { }
        }
    }

    public void populateTables(String uri) throws SQLException {
        System.out.println("Populating tables");
        populatePersonTable(uri);
        populatePlaceTable(uri);
        populateMapTable(uri);
    }

    public void populatePersonTable(String uri) throws SQLException {
        Connection conn = null;
        PreparedStatement stmt = null;
        try {
           conn = DriverManager.getConnection(uri);
           stmt = conn.prepareStatement("insert into PERSON " +
                                        "( PERSON_ID, FIRSTNAME, LASTNAME ) " + 
                                        "values ( ?, ?, ?)");
           {
              stmt.setInt(1,1);
              stmt.setString(2,"John");
              stmt.setString(3,"Doe");
              stmt.executeUpdate();
           }
           {
              stmt.setInt(1,2);
              stmt.setString(2,"Jane");
              stmt.setString(3,"Doe");
              stmt.executeUpdate();
           }
           {
              stmt.setInt(1,3);
              stmt.setString(2,"Jack");
              stmt.setString(3,"Nimble");
              stmt.executeUpdate();
           }
        } finally {
           try { stmt.close(); } catch(Exception e) { }
           try { conn.close(); } catch(Exception e) { }
        }
    }

    public void populatePlaceTable(String uri) throws SQLException {
        Connection conn = null;
        Statement stmt = null;
        try {
           conn = DriverManager.getConnection(uri);
           stmt = conn.createStatement();
           stmt.executeUpdate("insert into PLACE " +
                              "( PLACE_ID, CITY, STATE ) " +
                              "values ( 1, 'Chicago', 'IL' )");
           stmt.executeUpdate("insert into PLACE " +
                              "( PLACE_ID, CITY, STATE ) " +
                              "values ( 2, 'New York', 'NY' )");
           stmt.executeUpdate("insert into PLACE " +
                              "( PLACE_ID, CITY, STATE ) " +
                              "values ( 3, 'Los Angeles', 'CA' )");
        } finally {
           try { stmt.close(); } catch(Exception e) { }
           try { conn.close(); } catch(Exception e) { }
        }
    }

    public void populateMapTable(String uri) throws SQLException {
        Connection conn = null;
        PreparedStatement stmt = null;
        try {
           conn = DriverManager.getConnection(uri);
           stmt = conn.prepareStatement("insert into PERSON_PLACE_MAP " +
                                        "( PERSON_ID, PLACE_ID ) " + 
                                        "values ( ?, ?)");
           {
              stmt.setInt(1,1);
              stmt.setInt(2,1);
              stmt.executeUpdate();
           }
           {
              stmt.setInt(1,2);
              stmt.setInt(2,1);
              stmt.executeUpdate();
           }
           {
              stmt.setInt(1,2);
              stmt.setInt(2,3);
              stmt.executeUpdate();
           }
           {
              stmt.setInt(1,3);
              stmt.setInt(2,2);
              stmt.executeUpdate();
           }
        } finally {
           try { stmt.close(); } catch(Exception e) { }
           try { conn.close(); } catch(Exception e) { }
        }
    }

    public void printReport(String uri) throws SQLException {
        System.out.println("Printing report");
        String query = "select FIRSTNAME, LASTNAME, CITY, STATE " +
                       "from PERSON A, PLACE B, PERSON_PLACE_MAP C " +
                       "where A.PERSON_ID = C.PERSON_ID and " +
                       "      B.PLACE_ID = C.PLACE_ID " +
                       "order by LASTNAME, FIRSTNAME, STATE";

        Connection conn = null;
        Statement stmt = null;
        ResultSet rset = null;
        try {
           conn = DriverManager.getConnection(uri);           
           stmt = conn.createStatement();
           rset = stmt.executeQuery(query);
           System.out.println("FIRST\tLAST\tCITY\tSTATE");
           while(rset.next()) {
             System.out.print(rset.getString(1));
             System.out.print("\t");
             System.out.print(rset.getString(2));
             System.out.print("\t");
             System.out.print(rset.getString(3));
             System.out.print("\t");
             System.out.println(rset.getString(4));
           }        
        } finally {
           try { rset.close(); } catch(Exception e) { }
           try { stmt.close(); } catch(Exception e) { }
           try { conn.close(); } catch(Exception e) { }
        }
    }
}

The test directory (and the test/org/axiondb/functional directory in particular) contains literally hundreds of examples of using Axion via JDBC.



Axion - Open Source Java Database Engine
$Id: quickstart.html,v 1.41 2007/11/15 15:09:27 rwald Exp $
Published 15 Nov 2007 at 3:07 PM GMT.