DerbyTax Demo

Overview

Requirements

Manually install the demo

Auto-install the demo

Using the demo application

What is included?

### Overview

The DerbyTax application demonstrates how an embedded database such as Java DB (Sun's open source, supported distribution of the Apache Derby database) can be used to persist data locally from a tax return using a browser-based client that can be accessed either online or offline. The persistence is done by Java DB running embedded in a web browser. Many other examples of web services with local persistence can use the same technology.

In this demo, as the user enters or modifies data in a field, it is automatically saved locally in the Java DB database, making the application's Save button a useless widget. The cost of accessing the database is very low, so we can afford to save the data as it is being updated. If the system or application crashes, there is no data loss or corruption because Java DB meets the ACID (Atomic, Consistent, Isolation, Durable) properties of a relational database system. Data will be retrieved automatically the next time the application is run.

Several technologies are used in the demo. The client interface is pure dynamic HTML to render the forms. JavaScript is used to navigate and validate forms' content but more importantly to interact with Java DB running embedded locally. LiveConnect, a technology developed by Netscape and found in most browsers, is used to invoke the ClientStoreService from JavaScript. This Java class, instantiated in a tiny (10k) hidden Java applet, is used to communicate with Java DB.

The demo installs automatically as a Java Extension using Sun's Java Plug-in. Alternatively, you may download a zip archive, which includes the source files, and install it locally. Other deployment options include Java Web Start, an installer, or a browser extension (with a dependency on the Java runtime environment browser plug-in). With either Sun's Java Plug-in or Java Web Start deployment the Java DB downloadable footprint can be reduced considerably using Pack200 Java 5 compression. For more information, see Compressing Apache Derby w/ Pack200.

As written, the demo runs only on Mozilla Firefox. Multiple browser support is possible with some simple modifications to the HTML and JavaScript code. If an application requires greater data security, Java DB's data encryption can be used. Ajax (Asynchronous JavaScript and XML) can be used in place of JavaScript with LiveConnect to persist the data asynchronously, but this increases both the start-up time and footprint of the application, as it requires a local embedded web server.

### Requirements

These are the software requirements to run the demo:

1. Mozilla Web Browser 1.0.7 or 1.5.0.1

2. Sun's Java Plug-in 1.5.0 or greater. The Java Plug-in is part of the Java SE JRE download. To find out what JVM you are running, go to http://javatester.org/version.html. To install the latest Java plug-in for Windows, go to http://www.java.com/en/download/windows_xpi.jsp and cick Download Now.
   For Solaris/Linux, go to http://www.java.com/en/download/manual.jsp.

3. Java must be enabled in your web browser. To verify, check the Tools->Options->Content window.

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

### Manually install the demo

When you manually install the demo, you get the source files. See What is included? for a listing of included files.

1. Download EmbeddedDerbyDemo.zip.

2. Extract it to a directory of your choice.

3. Determine the path of the JVM used by your browser. On Windows, start the Java control panel from Start->Settings->Control Panel->Java, then select the 'Java' tab and then the view button from the Java Applet Runtime Setting' panel. On Unix (Solaris), the Java control panel is usually found in the Application Preferences menu of the KDE. If multiple versions are listed, you may have to uninstall previous versions.

4. Copy derby.jar to the lib/ext directory of the JRE used by the browser. Jars in this directory do not need to be signed, so you will not receive any security warnings. You can use this feature in debugging your own applications.

### Auto-install the demo

This is the way a user would typically deploy an application offered as a web service. The first time you access the DerbyTax demo from the web server, the start page opens in your browser and the signed derby.jar is downloaded and archived locally by the browser with a particular version number. With subsequent invocations, the required jar file is not downloaded again unless the version has changed, providing a much faster response time. Running online is the same as 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 a Warning - Security pop-up window upon loading the demo, please grant trust to the demo application by clicking on the Yes button. Because derby.jar was signed with a test certificate for this demo, it cannot be fully trusted by the web browser.

For more information, see the Security and How to Deploy RSA-Signed Applets in Java Plug-in sections in the Java Deployment Guide.

### Using the demo application

Launch the demo by loading the index page in your browser, online at http://developers.sun.com/javadb/demo/index.html or, if you manually installed the demo, at the path where you installed it. It is useful to view the database interactions in the Java console as you run the application. To open it, use the Java entry in the Windows Control Panel or the Tools->Java Console menu item in Firefox.

On the login screen, you can enter any username and password, then click Continue Return to use the pre-populated data for the demo. Alternatively, you can create a new return by clicking the Create Return button, which overwrites the current pre-populated tax return. You can then enter new data or update the fields on the application pages. Click Next to move to the next page or Back to revisit a previous page. As you update fields on Filing Status, Personal Info and W2 Info pages, check the Java console. You can see how fast the Java DB store interaction is and view the XML returned from the client store service.

You can verify that the demo is working by closing Firefox after updating some fields in Personal Info or W2 forms. The newly entered data will be there when you restart the demo. If you installed the demo manually and encounter a Security Permission error, it is likely that the derby.jar archive has not been copied correctly under the /lib/ext directory of the JRE used by Firefox.

### What is included?

After manually installing the demo, the following files and directories will be in the derby/demo/ directory:

- The i ndex.html file contains all the HTML and JavaScript that compose the client web application.

- The Java/ directory contains the two jar files, demo.jar and derby.jar.

- The Java/derby/embedded/ directory contains the Java source code for the Client Store Service: ClientStoreService.java and Util.java. The class files will also be found here.

- The images/ directory contains some bitmaps used by the client web application user interface.

After running the demo, there will be some new files and directories under the Firefox home directory:

- DerbyTaxDB (directory)

  The directory that makes up the DerbyTaxDB database. Do not modify anything in this directory, or you will corrupt the database. The directory was created when the application connected with Java DB, 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 this file.

- derby.log

  The log file with Java DB progress and error messages.

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

This file was last updated 21 May 2007.