Directions for Creating a Simple Database Enabled Enhydra Application

Author: G.W. Estep II

Author's Email: GW.Estep@riva.com

Authors Website: http://www.riva.com/
 

Overview

Unlike others, my initial experience with Enhydra was very frustrating.  I found the documentation to be quite scattered and there was not a tutorial example that was complete.  I realize that the DODS product is not complete and the documentation for is therefore incomplete also.  What I thought was going to be a one day job of creating a simple example that used "newapp", DODS and XMLC to create a simple database connected Enhydra application that I could run on my laptop (a part of the original Enhydra development requires BTW), turned out to be about 3 days.  Now keep in mind that I'm not a database guru or a java guru but I have done some work with both so maybe I was a little naive in my expectations.  There are others in my company that had similar experiences and so I took it upon myself to figure this out.

My simple requirements were as follows:

The following procedure should get you going on this.

Setup the project directory and test

cd directory under which you want your root project directory to be created.  We will assume here that it is /usr/prj and use this throughout the rest of this example text.  Obviously if you choose another directory you would  replace all occurances of /usr/prj/... below with your choice.
cd /usr/prj
Run the Enhydra newapp command to create the project tree.
newapp simpledb
Build your new Enhydra application
cd /usr/prj/simpledb

make
Run your new Enhydra application
cd /usr/prj/simpledb/output

./start
Test your new Enhydra application
Load the following URL in your browser.  Be patient, it takes a while (a minute or more) to load the page the first time.
http://localhost:9000/Welcome.po
Kill the Enhydra server
Ctl-C

Modify the default HMTL presentation file to include a simple references to the database

Modify the HTML file
cd /usr/prj/simpledb/simpledb/presentation
edit the Welcome.html file
Right before the </BODY> tag, insert the following line as is: <P><SPAN ID="name">This is the text that will be replaced when this application is completely working.</SPAN>Save the file

Build your new Enhydra application again

cd /usr/prj/simpledb    

make
Run your new Enhydra application again
cd /usr/prj/simpledb/output

./start
Test your new Enhydra application again
Load the following URL in your browser.  Be patient, it takes a while (a minute or more) to load the page the first time.
http://localhost:9000/Welcome.po
You should see the line you typed in the HMTL file at the bottom of the page.
At this point you haven't referenced the database yet.

Kill the Enhydra server

Ctl-C

Create a MS Access database that will work with Enhydra

Run Access

Select "Blank Database" option

<OK>

Save the file as /usr/prj/simpledb/simpledb.mdb

Create two tables as follows:
table#1: name = objectid

table#1:field#1: name = next, DataType = Number, designate as primary key
Add a record to the objectid table with the next field = 1
table#2: name = person

table#2:field#1: name = OId, DataType = Number, designate as primary key

table#2:field#2: name = version, DataType = Number

table#2:field#3: name = name, DataType = Text
Add a record to the person table with the name field = "simpledb works!",
oid=1, and vesion=1. Add one record to the OId table with next=2.
Quit Access

Configure simpledb as an ODBC datasource

Start->Settings/Control Panel->ODBC Data Sources

Select "User DSN" tab

<Add...>

Select "Microsoft Access Driver"

<Finish>

Data Source Name field = "simpledb" without the quotes.

<Select...>

Browse to the simpledb.mdb file you just create above and select it.

<OK>

<OK>

Run DODS to create the data objects for the project

 DODS doesn't work right if the data directory already exists
rm -rf /usr/prj/simpledb/simpledb/data
 Run DODS
dods <enter>
 Setup the packages correctly
Select the <root> package node in the lower left window.

Edit->Package

change name to "simpledb" no quotes

<OK>
Select the <simpledb> package node in the lower left window

Insert->Package

Change New Name field to "data" no quotes

<OK>
Select the <data> package node in the lower left window

Insert->Data Object

Change Name field to "Person" no quotes

Select Database Tab

Change db Table Name field to "person" no quotes

<OK>
Select <Person> Data Object Node in lower left window

Insert->Attribute

Change name field to "name" no quotes
Select Database tab and check "Can be queried"

<OK>
File->Save As

browse to /usr/prj/simpledb 

change the File name field to simpledb.doml

<Save>
File->Build All

browse to /usr/prj/simpledb/simpledb 

change the File name field to "data" no quotes

<Re/Create Directory>

You'll see a window pop up that shows the build progress of the DODS output.

<Close> when the last message is "DODS BUILD COMPLETE"
Quit DODS

Modify the Welcome.java file to get some data out of the database and replace a field in the HMTL file with it.

Edit the /usr/prj/simpledb/simpledb/presentation/Welcome.java file.

Add access to the DODS generated Data Object package by inserting the following code in red into the file Welcome.java .

package simpledb.presentation;

import java.util.Date;
import com.lutris.xml.xmlc.*;
import com.lutris.appserver.server.httpPresentation.*;

import simpledb.data.*;
import com.lutris.dods.builder.generator.query.*;

public class Welcome implements HttpPresentation {

    public void run(HttpPresentationComms comms) 
        throws HttpPresentationException,
        NonUniqueQueryException, DataObjectException  {

        String now = new Date().toString();
        WelcomeHTML welcome = 
                (WelcomeHTML)comms.xmlcFactory.create(WelcomeHTML.class);
        welcome.setTextTime(now);
    
        PersonDO person;
        PersonQuery pquery = new PersonQuery();
        person = pquery.getNextDO();
        welcome.setTextName( person.getName() );
                   
        comms.response.writeHTML(welcome);
    }
}

Save the file


Add the Database stuff to the simpledb.conf file

Append the following text between the BEGIN_APPEND and END_APPEND lines to the end of the /usr/prj/simpledb/simpledb/simpledb.conf file.
BEGIN_APPEND
#-----------------------------------------------------------------------------
#         Database Manager Configuration
#-----------------------------------------------------------------------------

#

# The databases that are used by CSAM. Each of these databases
# has configuration parameters set under DatabaseManager.DB."databaseName".
#

DatabaseManager.Databases[] = "simpledb"

#
# The default database used in this application.
#

DatabaseManager.DefaultDatabase = "simpledb"

#
# Turn on/off debugging for transactions or queries. Valid values
# are "true" or "false".
#

DatabaseManager.Debug = "false"

#
# The type of database. Normally this is "Standard".
#

DatabaseManager.DB.simpledb.ClassType = "Standard"

#
# The jdbc driver to use. 
#

DatabaseManager.DB.simpledb.JdbcDriver = "sun.jdbc.odbc.JdbcOdbcDriver"

#
# Database url.
#

DatabaseManager.DB.simpledb.Connection.Url = "jdbc:odbc:simpledb"

#
# Database user name.  All connection are allocated by this user.
#

DatabaseManager.DB.simpledb.Connection.User = "Admin"

#
# Database user password. Microsoft Access default is "Admin".
# The default password is blank.

DatabaseManager.DB.simpledb.Connection.Password = ""

#
# The maximum number of connections that a connection
# pool will hold.  If set to zero, then connections
# are allocated indefinitly or until the database
# refuses to allocate any new connections.
#

DatabaseManager.DB.simpledb.Connection.MaxPoolSize = 30

#
# Maximum amount of time that a thread will wait for
# a connection from the connection pool before an
# exception is thrown. This will prevent possible dead
# locks. The time out is in milliseconds. If the
# time out is zero, the allocation of connections
# will wait indefinitely.
#

DatabaseManager.DB.simpledb.Connection.AllocationTimeout = 10000

#
# Used to log database (SQL) activity.
#

DatabaseManager.DB.simpledb.Connection.Logging = false

#
# The number of object identifiers that are allocated
# as a group and held in memory.  These identifiers
# are assigned to new data objects that are inserted
# into the database.  
#

DatabaseManager.DB.simpledb.ObjectId.CacheSize = 20

DatabaseManager.DB.simpledb.ObjectId.MinValue = 1
END_APPEND

Build, run and test the application again

Build the application
cd /usr/prj/simpledb

make
Run the application
cd output

./start
Test the application
http://localhost:9000/Welcome.po
You should see the original text that mentioned it would be replaced when
this application works with a message that says it works!

If you did all of the above right, you now have a simple Enhydra application on your hands that works with a database and DODS output which is integrated in a newapp generated application.  Congrats!!!

G.W.

Last edited: Peter Darrah, peter@lutris.com, March 23, 2000