==================================================================
=                                                                =
=  Columbia Faceted Query Engine (ArchFacet) README File         =
=                                                                =
=  Author: Julia Stoyanovich (jds1@cs.columbia.edu)              =
=  Date:   May 18th, 2006                                        =
=                                                                =
==================================================================

List of files
=============

+ README (this file)
+ ArchFacet.war
+ ArchFacetUtils.jar
+ thulamela_data.zip
+ thulamela_images.zip


I. Installing the Software
==========================

1) Install Apache Tomcat 
  + we are running Tomcat v5.5.17 for Windows, available from 
    http://apache.tradebit.com/pub/tomcat/tomcat-5/v5.5.17/bin/apache-tomcat-5.5.17.exe
  + we are running Tomcat as a service

2) Install mySQL 
  + we are running MySQL v.4.1.11-nt, but a later version will certainly work, 
    see www.mysql.org for downloads
  + we are running mySql as a service

3) Deploy ArchFacet in Tomcat
  
  $CATALINA_HOME refers to the directory where you installed Tomcat

  + Add the following to server.xml in the $CATALINA_HOME/conf directory:

        <Context path="/ArchFacet" docBase="ArchFacet" debug="0"
         reloadable="true">
          <Logger className="org.apache.catalina.logger.FileLogger"
           prefix="localhost_archfacet_log." suffix=".txt"
           timestamp="true"/>
         </Context>

     Place the above context descriptor at the end of the file, but before 
     </Host>.

 + Place the file ArchFacet.war into $CATALINA_HOME/webapps and restart Tomcat.
   The directory $CATALINA_HOME/webapps/ArchFacet directory will be created by tomcat 
   upon restart.

 + Edit the file UI.properties in $CATALINA_HOME/webapps/ArchFacet/WEB-INF/classes
   and specify an absoulte path to the file script1.js on your system.  This file
   is at the top level of the $CATALINA_HOME/webapps/ArchFacet/ directory.
   On Windows, the path separator "\" needs to be escaped with another "\":
     C:\\foo\\bar\\baz\\script1.js

II. Configuring the Default Dataset (Thulamela)
===============================================

1) Create a new database and add a new database user as follows:

   cmd> mysql --user=<your mySQL admin user> --password=<your password> mysql

   mysql> CREATE DATABASE thulamela_source;
   mysql> CREATE DATABASE thulamela_query;

   mysql> GRANT ALL PRIVILEGES on thulamela_source.* to 'facet_usr'@'localhost' IDENTIFIED  by 'facet_pass';
   mysql> GRANT ALL PRIVILEGES on thulamela_query.* to 'facet_usr'@'localhost';

   + Feel free to substitute a username and password of your choice for <facet_usr> and <facet_pass>.
   
2) Allow ArchFacet to access the databases created in step (1):
   + Edit the files QueryDatabase.properties and SourceDatabase.properties in
     $CATALINA_HOME/webapps/ArchFacet/WEB-INF/classes/thulamela_resources and substitute the username
     and password for the user you create in step (1) on the first line of both files.

3) Unpack the thulamela_data.zip archive; this will create the directory thulamela_data.

4) Edit the file thulamela_data/query/users.txt and specify usernames and passwords for
   application users who will be allowed to access the Thulamela dataset through ArchFacet. 
   The format of each line in the users.txt file is:
   <userid>,<username>,<password>

   The userid and username fields must be unique.

5) Use the ArchFacet import utilities to load the Thulamela dataset. 

   !! Make sure that the file ArchFacetUtil.jar is in your CLASSPATH !!
   !! Order of operations is important !!

  + add the following to your classpath:

     <path to ArchFacetInstall>/ArchFacetUtil.jar
     $CATALINA_HOME/webapps/ArchFacet/WEB-INF/classes/
     $CATALINA_HOME/webapps/ArchFacet/WEB-INF/lib/mysql-connector-java-3.1.6-bin.jar
     $CATALINA_HOME/webapps/ArchFacet/WEB-INF/lib/ArchFacet.jar

  + create the relational representation of the data in the thulamela_source database.

  cmd> java ArchFacetUtil.Create thulamela <path to thulamela_data>

  + create the faceted thulamela_query schema.

  cmd> java ArchFacetUtil.CreateQuery thulamela <path to thulamela_data>

  + transform the data into faceted representation.

  cmd> java ArchFacetUtil.Transfer thulamela

 + There are also two Erase utilities in ArchFacetUtils:
 
  cmd> java ArchFacetUtil.Erase thulamela <path to thulamela_data>
  cmd> java ArchFacetUtil.EraseQuery thulamela <path to thulamela_data> 

 + Extract thulamela_images.zip into the $CATALINA_HOME\webapps\ArchFacet\images\
   directory

III. Using ArchFacet
====================

You can access ArchFacet at http://localhost:8080/ArchFacet/.  Use the login credentials
from step II(4).