Java DB

This demo showcases Java DB (Apache Derby) running embedded within a web browser.

At the present time, this demo runs on Mozilla Firefox only - The HTML and java-script would have to be modified in order to run on other web browsers such as Microsoft Internet Explorer.

This Web application demonstrates how an embedded database can be used to persist data from a tax return being created either online or offline. The application can be deployed manually or automatically using Sun's Java Plug-in with installing the application as a Java Extension.

As data is being entered or modified in a tax return field, it is automatically saved locally against the database (Derby); therefore making the "Save" button a useless widget - the cost of accessing Apache Derby embedded is very low and for that reason, we can afford to save the data as it is being updated. If the system or application crashes, data persisted in Derby running embedded will be retrieved automatically the next time the application is run. As Derby meets the ACID (Atomic, Consistent, Isolation, Durable) properties of a relational database system, data will be recovered up to before the crash without loss of committed data or risk of corrupted database.

Several technologies are being used as part of this demo but first, the client interface is pure dynamic HTML to render the forms used to enter data - java-script is used to navigate and validate forms' content but it is mostly used to interact with the Client Store service (Derby running embedded locally), referred as the ClientStoreService Object throughout the source code. LiveConnect is used to interact from java-script to Java (the client store service is instantiated in a tiny (~10k) and hidden Java applet.

Requirements for this web application demo were:

• A fast, embeddable, portable and secure (authentication/authorization/encryption) local client storage engine

• Portability across most widely known Web browsers (at least 2 of them)

• Support for scripting standard asynchronous requests (Ajax mode) to the embedded client data store

• Various deployment options for the Web application and database engine

• Support for direct access via a client scripting engine (non-Ajax mode, via LiveConnect)

The deployment options for the database engine and application could be:

• JNLP

• Direct HTTP download and archival of JARs by using Sun's Java Plug-in Extension deployment capability

• Direct copy of files via an installer or manually extracting an archive into the proper location(s),

• Firefox extension (w/ a dependence on the J2SE runtime environment Firefox plug-in)

Before running this demo, you should look through the following files and directories in the /derby/demo directory:

• index.html

  This file contains all the HTML and java-script that compose the client web application.

• Java/derby/embedded/ClientStoreService.java and Util.java

  Java Source code for the Client Store Service - The application will automatically set-up a pre-populated database the first time it is run..

• images

  This includes some bitmaps required by the client web application user interface.

After running the demo, you will see some new files and directories under the home directory of Mozilla Firefox:

• DerbyTaxDB (directory)

  The directory that makes up the DerbyTaxDB database. You must not modify anything in this directory, or you will corrupt the database. The directory was created when the application connected with Derby, using the attribute create=true in the database connection URL. The database name, DerbyTaxDB, was also set in the database connection URL.

• DerbyTaxDB\log (directory)

  The directory that holds the database transaction logs for the DerbyTaxDB database.

• DerbyTaxDB\seg0 (directory)

  The directory that holds the data for the DerbyTaxDB database.

• DerbyTaxDB\service.properties

  An internal file that holds boot-time configuration parameters for the DerbyTaxDB database; do not edit.

• derby.LOG

  The log file with Derby progress and error messages.

These are the software requirements to run the demo

1. Mozilla Web Browser 1.0.7 or 1.5.1

2. Sun's Java Plug-in 1.5.0+
   http://www.java.com
   http://www.java.com/en/download/windows_xpi.jsp (for Windows) - click on Windows XPI download button to install it as a Mozilla Firefox extension
   http://www.java.com/en/download/manual.jsp (for Solaris / Linux)

   NOTE: This demo has been tested on Solaris 10, Linux (Fedora) and Microsoft Windows operating systems.

These are the steps to install and run the demo manually. For an automatic online installation and if you meet the requirements, please access the following section.

1. Once the EmbeddedDerbyDemo.zip has been downloaded, extract it to a directory of your choice on your system.

2. Ensure that Firefox Sun Java Plug-in extension is installed - should be at least Java 5 (I have tested with 1.5.05 & 1.5.06 (latest)) - you can test what JVM you are running in firefox by going to this URL:
   http://javatester.org/version.html
   check the pink box under method 1) paragraph - it should tell you what JVM it is using - if none appears then Java is not enabled or installed with Firefox (Tools->Options->Web Features if 1.0.7)
   If the pink box does not say Java 1.5 from Sun Microsystems, then please install the latest Java plug-in from:
   

3. Once installed, go back to 2. and make sure firefox is now using the JVM (Java Plug-in you just installed) via javatester.org as instructed previously

4. Retrieve which JVM directory Firefox is pointing at:
   On Windows, it should normally be 'C:\Program Files\Java\jre1.5.0_06' - in order to find out, start the Java control panel from Start->Control Panel->Java, then select the 'Java' tab and then the view button from the 'Java applet runtime settings' panel - you should then be able to see the JRE you installed with the location in one of the column - it should be the only one hopefully, otherwise you may have to uninstall some previous versions if they are listed)
   On Unix (Solaris), the Java control panel is also named Java and usually found in the 'Application Preferences' menu of the KDE.

5. Extract the included EmbeddedDerbyDemo.zip under a directory of your choice

6. Demo uses 2 JARs files - the Apache Derby engine jar (derby.jar) and the demo one (demo.jar) which can be found under the Java directory of the extracted zip file
   - For a manual installation, the trick is to copy derby.jar under the lib/ext directory of the JRE used by firefox (i.e. C:\Program Files\Java\jre1.5.0_06\lib\ext) (for instance)
   - Copy derby.jar under the lib/ext directory of the JRE used by firefox (see step 4.)
   - For an automatic and online nstallation, please access the following section..

7. To start the demo, load 'index.html' under firefox - you can enter any username and password for now.
   TIP: to start the Java console at the same time at the derby demo, launch the Java control panel, select tab 'Advanced', then open 'Java console' and check 'open console' radio button - This will allow to see database interactions as well as debugging in case of issues.

8. Once the demo has started, you can enter any username/password, then click 'Continue Return' (Rebecca's tax return) to have access to pre-populated data for the demo, you can then update any info here and on the next pages (click Next again) - You can create a new return by clicking on the 'Create Return' button which will reset the current pre-populated tax return (it does not add a new one) - The filling status is also a persistent field (everytime you change the filling status, it is saved automatically by the store service). As you update fields in personal info and w2 pages, check the Java console - you can then observe how fast the Derby store interaction is and the XML returned from the client store service.

NOTE: If you encounter a Security Permission error in the demo, it is very likely that the derby.jar archive has not been copied correctly under the proper lib\ext directory of the JRE used by Firefox...you can check if the demo is working by killing Firefox after having updating some fields in Personal Info or W2 forms - The new updated fields should be there when you restart the demo - the 'Save' buttons are useless with this demo since updates are persisted (saved) automatically at the field level.

You can download the EmbeddedDerbyDemo.zip archive and access the source code as well as application files directly.

Click here for an automatic installation of the demo as a Java Plug-in Extension. If you meet the requirements to run the demo, you should be able to get it downloaded, installed and run online. The first time the demo is accessed from the web server, the (signed) derby.jar and demo.jar will get downloaded and archived locally on the client platform with a particular version number - The next time you invoke the application online, the required demo JAR files will not be downloaded again if the version has not changed - hence the demo application will be accessible right away if the JARs on the server side haven't changed. Note that even in online mode, all the data persistence will be done locally against Derby running embedded as part of the demo and web browser. It is like running in disconnected mode, except the web application files are downloaded from the server and JAR versioning verification is done against the local archived JARs. If you see "Warning - Security" pop-up windows upon loading the demo, please grant trust to the demo application by clicking on the 'Yes' button - as derby.jar has been signed with a 'test' certificate, this last one cannot be fully trusted by the web browser - more information related to this security topic.

Apache Derby (core engine) downloadable footprint can be reduced considerably with online applications run via Sun Java Plug-in or JNLP . Effectively, derby.jar can be reduced from 2MB down to ~600KB by using Pack200 Java 5 compression. This makes even Apache Derby much faster to download for web applications requiring a local cache. You can find more information at the following blog.

More information as well as new updates and Q/A will be available at my blog. Francois Orsini Sun Microsystems Database Technology Group