README
------

UnityJDBC is distributed with no implied warranty or obligation.  The trial version is for 30 days.

If you have any suggestions or bug reports, please send e-mail to support@unityjdbc.com
or post messages via the forum at www.unityjdbc.com.


PACKAGE CONTENTS
----------------

UnityJDBC.jar 			- main UnityJDBC jar file
register.bat			- registration batch file for Windows systems
register.sh			- registration script file for Linux/UNIX systems
jar.exe				- JAR executable (Windows use only)
UnityJDBCLicense.txt		- license information
UnityJDBCDistribution.txt	- distribution information
padUnityJDBC.xml		- PAD file describing application

doc/				- JavaDoc for Unity system (most users only concerned about unity.jdbc package)
code/
   Tests/
     ExampleEngine.java		- an advanced query that shows how users can use the UnityJDBC database engine directly
     ExampleGUI.java		- graphical query interface for building UnityJDBC queries 
     MyDataModel.java		- helper class for ExampleGUI.java
     ExampleMerge.java		- query example showing MERGE functionality
     ExampleMetaData.java	- query example showing how to extract metadata information
     ExampleQuery.java		- query example of UnityJDBC driver
     xspec/
       UnityDemo.xml		- sources file for example database
       UnityDemoOrder.xml	- XSpec description file for TPC-H Order database schema
       UnityDemoPart.xml	- XSpec description file for TPC-H Part database schema
   unity/
     extractor/
       SourceBuilder.java	- graphical program for building you source description files
       ExtractorXSpec.java	- program for building XML description files for each one of your sources
       AnnotatedExtractor.java	- helper program
       

REGISTRATION
------------
The UnityJDBC driver must be registered before it can be used.  The driver must be registered on the machine where it will
be used. 

To register run either register.bat (Windows) or register.sh (Linux).  Enter your key.  If registration is successful, you can
then copy and install the UnityJDBC.jar to an appropriate place in your CLASSPATH.  The 30-day trial key is "TRIALKEY".

You can also register by running:  java -jar UnityJDBC.jar   in a command/shell window.


INSTALLATION
------------
Copy the UnityJDBC.jar into a directory that is in your CLASSPATH.
An easy method to do this is to put the file in your ext directory of your JDK and JRE instllation.
e.g. C:\Program Files\Java\jdk1.5\jre\lib\ext


RUNNING TESTS
-------------

The tests provided access a database at our site.  This database is a TPC-H 100 MB database running on SQL Server.
You should be able to compile and run the test programs as is.  Make sure to also copy the Microsoft SQL Server
JDBC drivers into your classpath from the OtherJDBCDrivers directory.

Please discontinue using the sample databases once you have setup your own environment.


SETTING UP YOUR OWN ENVIRONMENT
-------------------------------

You need to do two things.  First, create a sources XML file that lists the connection information for all the sources
you want to query.  The example UnityDemo.xml is a sources file and looks like this:

<SOURCES>
	<DATABASE>
		<URL>jdbc:microsoft:sqlserver://IDEALAB5.cs.uiowa.edu:1433;DatabaseName=TPCH100;User=unitydemo;Password=test</URL>
		<DRIVER>com.microsoft.jdbc.sqlserver.SQLServerDriver</DRIVER>
		<XSPEC>Tests/xspec/UnityDemoPart.xml</XSPEC>
	</DATABASE>
	<DATABASE>
		<URL>jdbc:microsoft:sqlserver://IDEALAB5.cs.uiowa.edu:1433;DatabaseName=TPCH100;User=unitydemo;Password=test</URL>
		<DRIVER>com.microsoft.jdbc.sqlserver.SQLServerDriver</DRIVER>
		<XSPEC>Tests/xspec/UnityDemoOrder.xml</XSPEC>
	</DATABASE>
</SOURCES>

This is showing two "virtual" databases as we have split the TPC-H schema into an Part database and an Order database.
They both refer to the same physical Microsoft SQL Server database.
Each database entry contains the regular JDBC connection information including the JDBC URL, driver class, and the location
of the XSpec XML file describing the database schema and contents.

The XSpec XML file is used so that the driver does not have to extract schema information every query and can perform better
optimization.  It also allows users to provide a view of the database by only including tables and fields in the XSpec file
that the UnityJDBC driver can access.  The XSpec file must be locally accessible but can be retrieved over the Internet.
There is an encryption feature for XSpecs if you put them in Internet-accessible locations.

As an example, open up the UnityDemoOrder.xml XSpec.  It contains an XML encoding of the schema.  A few important tags:

<databaseName>OrderDB</databaseName> 		- OrderDB will be the name of the database in queries (very important)
<semanticTableName></semanticTableName> 	- You can rename any database table to have your own alias.
<tableName>CUSTOMER</tableName>			- The database table name in the schema.
<numTuples>15000</numTuples>			- The size of the table in tuples.  Used by optimizer.
...
<semanticFieldName></semanticFieldName>		- You can provide an alias for any field as well.
<fieldName>C_ADDRESS</fieldName>		- Field name assigned in the schema.
...
<numDistinctValues>15000</numDistinctValues>	- Used by optimizer.


There are two ways to produce a sources.xml file describing your sources and the associated XSpec files:

1) The easiest way is to use the SourceBuilder.java program.  This is a GUI that will guide you through creating the files.  It will
automatically extract source information and build the necessary files.

2) You can manually build the sources.xml file using a text editor.  
To produce an XSpec for a source, open up the program called ExtractorXSpec.java in the code/unity/extractor directory.
Modify the JDBC URL, driver path, and output directory accordingly and run the program.  The account that you connect with
must have read access to the database and associated tables that you want to access.  After the XML file has been produced, move
it to the directory where you want it and update the sources XML file to reference the correct location.

Then, we suggest copying and modifying the ExampleQuery.java program to use your sources XML file and write an appropriate
query for your schema.


SUPPORT
-------

If you have any problems, consult the documentation and user support forums at www.unityjdbc.com.  We would also appreciate any
bug fixes or suggested new features.  You may also send your support related questions to support@unityjdbc.com.


--
The UnityJDBC.com Team
July 5th, 2006
     