Mvessel: The new JDBC driver written in Scala

• by Fede Fernández Beltrán
• •
• November 10, 2015
• •
• scala• android• java• releases• open source
• |
• 5 minutes to read.

Introducing Mvessel

Mvessel is a JDBC driver written in Scala with the primary goal of allowing the use of ORMs in Android.

Based off of the SQLDroid, Mvessel has been completely rewritten in Scala with huge code coverage and using SBT as a build tool.

The project is organized in three modules:

• mockAndroid contains classes from the Android Open Source project without the final modifier in order to be mocked. It’s used only for test purposes.

• core contains all core classes but relies on some api classes to do all the work. The main benefit of this module is that it is not dependent of the Android API.

• androidDriver implements the api classes using SQLiteDatabase and derived classes.

It also includes the android-it subdirectory with instrumentation tests and subdirectory featuring samples and explanations on using them.

Using in Android:

Import your project

SBT

libraryDependencies += "com.fortysevendeg" %% "mvessel-android" % "0.1"

Gradle

compile 'com.fortysevendeg:mvessel-android_2.11:0.1'

Maven

<dependency>
    <groupId>com.fortysevendeg</groupId>
    <artifactId>mvessel-android_2.11</artifactId>
    <version>0.1</version>
</dependency>

Using the latest available version

You can use the SNAPSHOT version by adding the sonatype SNAPSHOT repository to your resolver list:

• https://oss.sonatype.org/content/repositories/snapshots/

And use the latest version: 0.2-SNAPSHOT

Create a SQLiteOpenHelper

Android comes with a helper class to manage the creation and version management of our database. This class is SQLiteOpenHelper. We can use this helper class to let Android platform create the database file for us and later access to that file through our JDBC driver or favorite ORM.

Our SQLiteOpenHelper could be something like:

Scala

class ContactsOpenHelper(context: Context)
  	  extends SQLiteOpenHelper(context, "database.db", null, 1) {

  def onCreate(db: SQLiteDatabase) {
    // Use this method to initialize your database
  }

  def onUpgrade(db: SQLiteDatabase, oldVersion: Int, newVersion: Int) = {
    // Use this method to upgrade your database
  }
}

Java

public class ContactsOpenHelper extends SQLiteOpenHelper {

    public ContactsOpenHelper(Context context) {
        super(context, "database.db", null, 1);
    }

    @Override
    public void onCreate(SQLiteDatabase db) {
        // Use this method to initialize your database
    }

    @Override
    public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
        // Use this method to upgrade your database
    }

}

Use java.sql classes

If you want to work directly with the java.sql classes you could create a method in your SQLiteOpenHelper that returns the java.sql.Connection.

Scala

def openConnection() = {
  // 1. Create the database and trigger the `onCreate` and `onUpgrade` methods.
  val database: SQLiteDatabase = getReadableDatabase()
  // 2. Register the driver, making available for `java.sql`
  com.fortysevendeg.mvessel.AndroidDriver.register()
  // 3. Open a connection using the path provided by the database
  DriverManager.getConnection("jdbc:sqlite:" + database.getPath)
}

Java

public Connection openConnection() {
    // 1. Create the database and trigger the `onCreate` and `onUpgrade` methods.
    SQLiteDatabase database = getReadableDatabase();
    // 2. Register the driver, making available for `java.sql`
    com.fortysevendeg.mvessel.AndroidDriver.register();
    // 3. Open a connection using the path provided by the database
    return DriverManager.getConnection("jdbc:sqlite:" + database.getPath);
}

Note: You should add a method to close the connection.

Use the Database class

You can directly create a connection with the Database class provided in the library. Again in your SQLiteOpenHelper:

Scala

def openDatabase() = {
  // 1. Create the database and trigger the `onCreate` and `onUpgrade` methods.
  val database: SQLiteDatabase = getReadableDatabase()
  // 2. Open the database using the path provided by the database
  new Database[AndroidCursor](
    databaseFactory = new AndroidDatabaseFactory,
    name = database.getPath,
    timeout = 50,
    retry = 0,
    flags = 0)
}

Java

public Database openDatabase() {
    // 1. Create the database and trigger the `onCreate` and `onUpgrade` methods.
    SQLiteDatabase database = getReadableDatabase();
    // 2. Open the database using the path provided by the database
    return new Database<AndroidCursor>(
        new AndroidDatabaseFactory(), database.getPath(), 50, 0, 0);
}

Review the sample in Java and the sample in Scala for more detailed instructions.

Use with Slick:

Review the sample with Slick for an example of usage.

Collaborate:

There are multiple ways you can collaborate with this project:

First, check out the GitHub issue tracking. If you find a bug that is not listed, please submit it along with a detailed description.

The samples can always use improvement (upgrade versions, make it more attractive, etc.). You can also contribute additional samples to the project.

Finally, there are a lot of functionalities that are not implemented yet. The tests are prepared to fail when a new functionality is added so don’t forget to add the test cases along with the new implementation.

The name of the driver is a play off of the murex vessel. Tyrian purple (a bromine-containing reddish-purple natural dye) is made from the secretions of several species of predatory sea snails referred to as murex. In ancient Rome, the dye was transported from the south of Spain to all of the Roman Empire’s cities in vessels.

Mvessel is an open source project licensed under MIT. We hope you find this library useful, and we encourage you to collaborate with us on the project. You can find more information about using this library in the Mvessel GitHub Repository.