Contract
Parameter key	Default value	Type
a_uri	opt
contract	opt
type	opt
a_response	null
http_message	opt
base_protocol	false	boolean
name	opt
protocol_name	"file"	string
of	of	instances
a_connection	opt
database_name	opt
username	""	string
password	""	string

Water Contract
<class resource.db a_connection =opt database_name =opt username ="" password ="" />

resource.db contains the classes and methods for Water Database. Water Database is the standard Water library for connecting Water programs to relational databases.

<set my_db = <resource "jdbc:mysql://localhost/book" protocol_handler="java.com.mysql.jdbc.Driver"/> />
my_db.<execute> SELECT * FROM book </execute>

<vector <thing "283223" "Water" "Plusch" "Wiley"/> <thing "458328" "Water Programming" "Fry" "Clear Methods"/>/>

Installation

Water Database uses standard JDBC drivers. Below are instructions for how to configure different databases. To setup databases with specific drivers: (Example: MySQL) 0. Make sure you have a database installed on your machine. If you'd like to run MySql, you can get it free at: http://dev.mysql.com/downloads/ 1. Download a JDBC driver. It should be packaged as a .jar file. For the MySql driver go to: http://www.mysql.com/products/connector-j/index.html 2. Put the JDBC .jar file into the 'jre/lib/ext' folder of your Java Runtime Environment. You can see the directory to install this file by looking at the top of the Java Console window after you have launched Steam. (Example: Folder for Java Extensions: C:/jdk1.4/jre/lib/ext or C:/Program Files/Java/j2re1.4.1_02/lib/ext) For MySql the file will be named something like: mysql-connector-java-3.1.7-bin.jar If you don't see a Java console window, on Windows you can configure this to show upon launching Water using the Java Control Panel. 3. Configure the database for local and/or remote access (Example: for MySQL, use the MySQL Control Center (mysqlcc) program) Enter usernames and passwords (or leave empty) 4. Start the database (Example: D:/mysql/bin/mysqld ) 5. Execute Water Database commands (see examples below) To setup a local Access 97 database under Windows: 1. Under the Control Panel, setup the ODBC settings and 2. Add a System DSN 3. Choose a type of "Microsoft Access Driver" 4. Enter a Data Source name (Example: my_db) 5. Click "Select..." button to select an mdb file (Example: my_db.mdb) 6. Choose "Advanced..." and setup the Default Dir (Example: C:\my documents) 7. Enter user and password fields (or leave blank) 8. Start the database 9. Execute Water Database commands (see examples below) -------- Create a new database data_source. A single data_source can hold one or more databases. Note: data_source is a subclass of db_resource, but it is promoted.

<resource "jdbc:mysql://localhost/" protocol="com.mysql.jdbc.Driver"/>

resource.of."jdbc:mysql://localhost/"

Any SQL query can be executed on a data_source resource using execute. execute takes an SQL statement in the hypertext content area. An ending semi-colon is not required.

resource.of."jdbc:mysql://localhost".<execute> SHOW DATABASES </execute>

<vector <thing Database="test"/> <thing Database="mysql"/>/>

The database connection can be found in field named "a_connection", although you typically do not need to access it. The connection gets created on the first database request and is maintained in the resource until the resource is removed.

resource.of."jdbc:mysql://localhost/"._object.a_connection

CREATING A NEW DATABASE database Creates a new database within the data_source. If no connection is given, it will reuse the connection from the data_source. The database can be accessed as a field in the data_source. The following example shows creating a new database named "test_db":

<resource "jdbc:mysql://localhost/test_db"/>.<create/>

resource.of."jdbc:mysql://localhost/test_db"

Alternatively, you can create a database connection that is separate from the database connection for the data_source. Set the database resource to the local variable "my_db"

<set my_db=resource.of."jdbc:mysql://localhost/test_db" />

Create a new database table named 'book' using SQL:

my_db.<execute> CREATE TABLE book(isbn VARCHAR(255),
                                       title VARCHAR(255),
                                       author VARCHAR(255),
                                       publisher VARCHAR(255))  
 </execute>

Use SQL to look at the newly created table:

my_db.<execute> SHOW TABLES </execute>

<vector <thing Tables_in_test_db="book"/>/>

Use 'execute' to insert two rows into the table:

my_db.<execute> INSERT INTO book VALUES 
                      ("283223","Water","Plusch","Wiley") 
  </execute>
my_db.<execute> INSERT INTO book VALUES 
                      ("458328","Water Programming","Fry","Clear Methods") 
  </execute>

Perform a SQL SELECT query on the new table to retrieve the data. Notice that the instances are generic things, and are not of type 'book'.

my_db.<execute> SELECT * FROM book </execute>

<vector <thing "283223" "Water" "Plusch" "Wiley"/> <thing "458328" "Water Programming" "Fry" "Clear Methods"/>/>

If you have a Water Contract (class) for the corresponding database table, you can specify that the returned instances should be of that class. execute takes an argument named 'class'.

<class book isbn=req title=req author=req publisher=req/>

my_db.<execute maker=book> SELECT * FROM book </execute>

<thing <book "283223" "Water" "Plusch" "Wiley"/> <book "458328" "Water Programming" "Fry" "Clear Methods"/>/>

The following example shows how the first instance can be retrieved using a simple Water Path:

my_db.<execute maker=book> SELECT * FROM book WHERE isbn="283223" </execute>.0

<thing.book  isbn=283223 title="Water" author="Plusch" publisher="Wiley"/>

a_connection can be explicitly created and passed into a database in the a_connection field.

<set a_db=
  <database "test_db" 
    a_connection=db_resource.<connection "jdbc:mysql://localhost/"
                                         "com.mysql.jdbc.Driver"
                                         username="" password=""
                 />
  />
 />

a_db.<execute> SHOW TABLES </execute>.<length/>

CONNECTING TO EXISTING DATABASE A very common scenario is that data already exists in a database, and Water is used to access and manipulate that data. If you have an existing database named "test_db" and an existing table named "book", then the following will create a Water Database object that represents the relational database, and assign it to the my_store local variable. If the database already exists, use the path to the database instead.

<resource "jdbc:mysql://localhost/"
            protocol_handler="java.com.mysql.jdbc.Driver"
            username=""
            password=""
  />
<set my_store=
       data_source.of."jdbc:mysql://localhost/primary_db"
  />

Any SQL command can be called using execute:

my_store.<execute> SELECT * FROM book </execute>

<vector <thing "283223" "Water" "Plusch" "Wiley"/> <thing "458328" "Water Programming" "Fry" "Clear Methods"/>/>

A Water Contract 'class' can be created automatically from the database table definitions using derive_classes.

my_store.<make_classes/>

It is possible to create custom mappings of SQL datatypes to Water types. db_resource.map_sql_type_to_water and db_resource.map_water_type_to_sql are the mapping tables. The use of these maps has yet to be documented. The class for book is now defined in thing.book and can be used as a class in execute to return objects of the appropriate class.

my_store.<execute class=book> SELECT * FROM book </execute>

<vector <book "283223" "Water" "Plusch" "Wiley"/> <book "458328" "Water Programming" "Fry" "Clear Methods"/>/>