Connecting to a Repository

by Andrew Taylor <andy@benow.ca>
This tutorial covers connecting to a JDBC database for use with the BeNOW Repository API. The repository API facilitates object persistence in JDBC databases, which speeds development and leads to more natural database usage (from an object oriented perspective). After connecting to a repository, you'll be ready for storing, retrieving and deleting persisted objects.
Contents
  1. Project Preparation
  2. The Easy Way
  3. Preparing the Database Server
  4. Connecting to the Repository
  5. Using the Repository
Project Preparation
The easiest way to create a new repository project is to use the BeNOW launch ProjectMaker.
  1. Ensure that Ant is installed and functioning (Windows users might want to install ant via the winant installer)
  2. Download benow-launch.jar to a new directory named for the new project.
  3. From a terminal, change to the download directory and run:

    java -jar benow-launch.jar ProjectMaker --with repository

    which will create the project structure including the repository requirements.
For more info about project creation, check out the BeNOW Launch Project Creation tutorial.
The Easy Way
The easiest way to use the repository is to do no configuration. The default configuration has JavaDB as the prefered database, as it is fast, is distributed in recent JDKs and runs in embedded mode, without the need of a seperate server process. There is no need to configure anything when used this way. The JavaDB libraries are included in the project and, when spooled up, the database will be created in the database directory within the project root. The easy way has the db running in embedded mode, which is fine for single application use, but if you wish to have multiple applications accessing the data or a different database server, please read the Preparing the Database Server section. Otherwise, if you're OK with the default JavaDB, you can proceed to Connecting to the Repository.
Preparing the Database Server
The Repository API is designed to work with JavaDB (aka Derby), firebird and mysql databases. Generic JDBC database support is coming, but for now, those three are tested and work. JavaDB is the default database backend and it requires no specific configuration unless it is to be used as a server across multiple applications.
Preparing JavaDB as Server

If your data will be accessed by other applications, you'll want to run JavaDB in server mode.

  1. Open etc/config/org.benow.repository.jdbc.xml in an editor
  2. *To be determined*
Preparing MySQL
  1. Download and install the most recent MySQL as appropriate to your computer.
  2. Ensure the MySQL server is running
  3. Open etc/config/org.benow.repository.jdbc.xml in an editor
  4. Change the entry with the name of org.benow.repository.jdbc.JDBCRepository.driver to have a value of com.mysql.jdbc.Driver
  5. Change the entry with the name of org.benow.repository.jdbc.JDBCRepository.url to use mysql and point to the database directory, ie jdbc:mysql:basic
  6. Change the entry with the name of org.benow.repository.jdbc.JDBCRepository.user to be a user capable of managing the database
  7. Change the entry with the name of org.benow.repository.jdbc.JDBCRepository.pass to be the password for the above user
Preparing Firebird
  1. Download and install the most recent Firebird SuperServer as appropriate to your computer. Ensure to get the SuperServer version.
  2. Ensure the Firebird server is running
  3. Open etc/config/org.benow.repository.jdbc.xml in an editor
  4. Change the entry with the name of org.benow.repository.jdbc.JDBCRepository.driver to have a value of org.firebirdsql.jdbc.FBDriver
  5. Change the entry with the name of org.benow.repository.jdbc.JDBCRepository.url to use firebird and point to the database directory, ie jdbc:firebirdsql:/path/to/project/database/basic.gdb
  6. Change the entry with the name of org.benow.repository.jdbc.JDBCRepository.pass to be the password for the sysda user for connecting to firebird, if required, ie masterkey
Notes:
Connecting to the Repository
At this point, the repository should be able to talk to the database, and we're ready to test the connection. The repository test application is included in the project configuration and can be seen by opening src/java/test/org/benow/repository/Tutorial.java in an editor and looking at doConnect(). The code which connects to the repository is: 
    Transaction tx =null;
    ObjectRepository repo=null;
    ObjectRepositoryConnection conn=null;
    try {
      // get the repository
      repo = RepositoryManager.getRepository();
      // take a connection
      conn = repo.takeConnection();
      // take a transaction 
      tx = conn.getTransaction();
      // the transaction can now be used.
      log.info("The repository is ready to be used!");
      // commit the transaction
      tx.commitTransaction();
    } catch (Throwable t) {
      log.error("Error during run", t);
      if (tx!=null)
      tx.rollbackTransaction();
    } finally {
      // return the connection so that it may be reused.
      repo.returnConnection(conn);
    }
As you can see, it's quite simple. When the repository is taken, the database is created, as it does not exist. A connection to the repository is taken, which can be used for working with the repository. From the connection, a transaction is taken, which group repository operations. You can run the connection tester application using the included launcher from a terminal: sh bin/tutorial_repoitory.sh connect in un*x (linux, solaris, osx) or bin\tutorial_repository.bat connect in windows. You will see the logging showing the creation of the database, and should see 'The repository is ready to be used!'. This is only the basic connect to the repository and is actually more complicated than typical use.
Using the Repository

Now that you've made a connection to the repository, you'll probably want to use it. To create, store, retrieve and delete objects within the repository see the Using the Repository tutorial.

The BeNOW tutorials are a work in progress. If you have any comments or suggestions, please email <andy@benow.ca>.