                              HIPPO 0.9
                              ---------
                             README FILE


This directory contains the distribution of Hippo system ver 0.9. 
Hippo system computes Consistent Answers to projection-free SQL 
queries. The system works as a front-end to a relational database
through a JDBC interface. The system is implemented in Java 2. The
primary database system used with Hippo is PostgreSQL (ver. 7.3.3);
Hippo was also used with a post-relational database system Cache. The 
theoretical foundations for Hippo system can be found in [CMS04].
This README file contains a short description of the distribution,
installation notes, and contact information. 

DISTRIBUTION CONTENTS:
This distribution contains the following elements:
*) source files:
        src/java/ (Java source files)
        src/jj/   (JavaCC complier definition)
        src/xsd/  (XMLSchema configuration file parser definition)
        
*) a binary archive 
        hippo.jar

*) a template configuration file 
        config.xml

*) library of external resources needed to run the system
        lib/ (collection of JAR files to put in CLASSPATH)

REQUIRED PACKAGES:
*) Commons Collections ver 2.1 (www.apache.org)
*) Log4J ver 1.2.8             (www.apache.org)
*) PostrgreSQL JDBC drivers    (www.postgresql.org)
*) JAXB API ver 1.0            (www.java.sun.com)

HIPPO CONFIGURATION:
The config.xml is a template of the configuration file. 
The following parameters control the connection with the database:

/xml-configuration/db-description/connection-params/@db-name
- database name
/xml-configuration/db-description/connection-params/@user
- user name
/xml-configuration/db-description/connection-params/@password
- user's password

The configuration file also has to contain the schema description of
the database. For each relation R with attributes A,B,...,Z (of types
TYPE_A, TYPE_B,..., TYPE_Z resp.) in the element
/xml-configuration/db-description/schema the following element  
need to be added:
<relation name="R">
    <field name="A" type="TYPE_A"/>
    <field name="B" type="TYPE_B"/>
    ...
    <field name="Z" type="TYPE_Z"/>
</relation>
The supported types are: INT, TEXT, FLOAT, DATE, TIME, and TIMESTAMP. 

For each denial constraint of the form
FORALL X1 IN R1, FORALL X2 IN R2,..., FORALL Xn in Rn. NOT (DEFINITON)
the following element needs to added in 
/xml-configuration/db-description/integrity-constraints
<integrity-constraint>
   <binding-variable variable-name="X1" relation-name="R1"/>
   <binding-variable variable-name="X2" relation-name="R2"/>
   ...
   <binding-variable variable-name="Xn" relation-name="Rn"/>
   <definition>DEFINITION</definition>
</integrity-constraint>
The condition DEFINITON describes a situation that is prohibited
(defines a conflict between tuples from R1, R2,..., Rn) and it's
expressed as a WHERE conditions statement of SQL'99. (The template
contains definitions of two functional dependencies P:X->Z and Q:X->Z) 

RUNNING THE SYSTEM:
After configuration of the system, execute the following class:
edu.buffalo.nsf.hippo.util.StdinClient

This will run a command-line type of an interface which accepts
projection-free SQL queries. 

CONTACTING THE AUTHOR:

Slawomir Staworko,
SUNY at Buffalo,
staworko(at)cse(dot)buffalo(dot)edu

REFERENCES:

[CMS04] J. Chomicki, J. Marcinkowski, and S. Staworko, "Computing
Consistent Query Answers using Conflict Hypergraphs", Proc. 13th
Conference on Information and Knowledge Management (CIKM), November
2004, Washington, D.C., pp. 417--426 Short version in Proc. Workshop
on Information Integration on the Web,  August 2004, Toronto, Canada,
pp. 103--108 

