Configuring orman for mysql, sqlite and android

As always –unfortunately– you need to setup different environments in order to use different DBMSes with in your project.

This document is about how to setup working environment for various database systems and registering them to the framework so that it can recognize and take specific actions for it.

MySQL

To use MySQL, you should download a MySQL Connector/J archive, extract it and copy the file (named like) mysql-connector-java-5.*.jar under your lib/ folder then add it to your classpath. (Around 700 kb.)

After that you can use the following code to configure a MySQL database for the framework.

Database db = new MySQL(new MySQLSettingsImpl("myUsername", "myPassword", "myDb"));
MappingSession.registerDatabase(db);

There are a few constructors for MySQLSettingsImpl:

• MySQLSettingsImpl(String username, String password, String db)
• MySQLSettingsImpl(String username, String password, String db, String host)
• MySQLSettingsImpl(String username, String password, String db, String host, int port)

Default hostname is localhost and default port is 3306 when omitted. After registering the database, framework now knows about the datasource.

Don't forget to create a database named myDb before executing program. ORMAN does not execute CREATE DATABASE commands for you.

SQLite

As a design choice we work with sqlite4java library distributed under Apache License 2.0. It is a minimalistic high-performance Java wrapper for SQLite. However it supports only one thread for querying database, therefore it is efficient for your command-line Java applications.

The disadvantage is, it is a JNI (Java native interface) for C libraries of SQLite. Therefore you should ship binary files for each platform (Windows, Linux, Mac OS) if you want your Java program to be platform independent. They sum up to 6 MB.

Download a sqlite4java build from http://code.google.com/p/sqlite4java/downloads/list , extract the archive. Copy all .dll, .jnilib and .so files under your lib/ folder, copy also sqlite4java.jar file under your lib/ folder.

After that you can use the following code to configure a SQLite database for the framework. Database db = new SQLite("dbfile.db"); MappingSession.registerDatabase(db);

In the constructor you specify a database file. You can also specify absolute path for your database file, however it is not recommended. If your program (owner user of process) does not have read and write permissions to the target folder, exception will be thrown. Make sure that you have these permissions set.

Android

Important Notice:

Due to limitations of Dalvik VM of Android, you need to manually register your Entity classes as follows MappingSession.registerEntity(MyEntity.class);, otherwise it may throw AnnotatedClassNotFoundInPackageException. (see issue #27)

Awesomely, you don't need to include any extra files to setup an Android SQLite environment. You can use the following code to configure in onCreate() method of your callee Application class.

public class MyAndroidApplication extends Application {
    
    @Override
    public void onCreate() {
        Database db = new SQLiteAndroid(this, "dbfile.db");
        MappingSession.registerDatabase(db);
        MappingSession.start();
    }
}

Also remember to include the name of the Application class in your AndroidManifest.xml

<application android:name="MyAndroidApplication" android:label="@string/app_name" />

Note that if you want to use Android logging mechanism see the article Setting a custom logger. It is recommended for Android apps.