= Embedding a Derby database =
Derby can serve as an embedded relational database in Java applications.  This may be a solution for use cases that need real-time access to relatively stable data, such as gene aliases and annotations.  Getting Derby to work within a Cytoscape plugin was not trivial, so I wanted to share that experience.

-----

== Important Links ==

 * Offical [[http://db.apache.org/derby/|Apache Derby]] site
 * Useful [[http://db.apache.org/derby/quick_start.html|Quick Start]] site for newbies
 * [[http://db.apache.org/derby/derby_downloads.html#Software+required+to+build+Derby|Reference]] to OSGi (osgi.jar)
  * Relevant discussion threads relating to OSGi wrt Derby 
   * [[http://mail-archives.apache.org/mod_mbox/db-derby-dev/200512.mbox/%3C001001c602ae$adcdd270$6400a8c0@Apollo%3E|thread#1]] 
   * [[http://mail-archives.apache.org/mod_mbox/incubator-felix-dev/200603.mbox/%3C44061826.7010505@ungoverned.org%3E|thread#2]]

== Getting It To Work ==

 1. Like other libraries to be included in a plugin, you have to unjar the classes and include them in your build folder.  
 1. In order to get my application running, I needed to include both derby.jar and derbytools.jar.  Leaving the other out helps keep the size down.  These two jars add ~2.3MB.
 1. One of the classes in derby.jar throws an exception while the plugin is being loaded by Cytoscape. Embedded''''''Activator.class (org.apache.derby.osgi) implements Bundle''''''Activator.class which is ''not'' included in the Derby distribution.
  a. Turns out this class is part of an "optional" OSGi package which is under a proprietary license, not Apache!
  a. Rather than going down that dark and treacherous road, I simply removed the osgi folder containing only the Embedded''''''Activator class and jared the remaining classes along with my plugin.  No problems.

== Materials ==

Here is a sinlge jar file containing derby.jar plus derbytools.jar minus the offending class: [[attachment:derby-slim.jar]] 

And here is sample code for your build.xml to unjar and include the derby classes in your build file:
{{{#!java
<unjar overwrite="Yes" dest="${build}">
    <fileset dir="${lib.derby}">
        <include name="lib/derby-slim.jar"/>
    </fileset>
</unjar>
}}}

== Next ==

 * I plan on testing performance by loading a GenMAPP Gene Database exceding 500MB into Derby and seeing how it runs.
 * I'd like to work on a general Derby Interface: a plugin that loads derby-slim.jar once and offers generic methods for all other plugins

-----

=== Comments ===