How to run the XDirectoryService

NOTE: This assumes you have already built the XDirectoryService.

There are currently three database systems that the XDirectoryService can use: MySQL, PostgreSQL, and HSQLDB. The simplest of these is HSQLDB, because it does not require any external database system. HSQLDB is a lightweight 100% SQL database engine, which primarily runs in memory with a persistent option for storing the database contents.

The XDirectoryService should be started through the provided run scripts, currently only run.sh, or directly from Java, otherwise.

The run scripts, and the main Java class, take a few different arguments. The most important of which are "--port" and "--impl". "--port" is used to tell the XDirectoryService which port it should listen for requests on, and the "--impl" argument is used to specify the type of database system that will be used for storing the data in the XDirectoryService.

By default the HSQLDB is used to store the XDirectoryService's data. The other options are a MySQL database or PostgreSQL database. To use a MySQL database specify "mysql" after "--impl" and to use PostgreSQL specify "postgres".

In addition to the arguments passed to the run scripts, or main Java class, you can configure the different database systems using Java environment variables. Java environment variables are those that are passed to the "java" command using the "-D" option, i.e. java -Dname=value. If you are using the run scripts, and not java directly, you can specify these variables using a JAVA_OPTS shell environment variable, i.e. performing a "setenv JAVA_OPTS -Dname=value" before invoking the run scripts. Otherwise, you can just add them directly to the Java command-line. Below are instructions on what the different database systems understand in the way of Java environment variables.

There is also an option that all database systems understand: clean_database. It should only be used when you want to delete all the existing data in the database before the XDirectoryService starts up. It basically just performs an SQL DROP on all the tables that are being using in the database, and therefore cannot be undone. "clean_database" can be used by giving it a value of "true", i.e. setenv JAVA_OPTS -Dclean_database=true.

There are also some examples of how to run the XDirectoryService below.

HSQLDB Instructions

The HSQLDB implementation supports two modes of operation, either in memory, which is not persistent across runs, or in memory with persistence, which is persistent across runs. By default the non-persistent in memory version is used. If you want to use the persistent mode you need to set the Java environment variable called "xdrs_hsqldb_dbname" to some value other than ".". The value will be the name of the file used to hold the database information between runs. Note, the value of "." means the non-persistent in memory version will be used.

MySQL Instructions

The MySQL implementation requires a MySQL database be running, specifically one that supports the InnoDB table type (for transactions), and a user and database exists that the XDirectoryService can use to CREATE/DROP tables in. Once such a setup exists the MySQL database can be used by specifying "--impl mysql" on startup and defining a "xdrs_mysql_url" to be a MySQL connection URL such as: jdbc:mysql://mysql_server/database_name?user=username,password=user_password

PostgreSQL Instructions

The PostgreSQL implementation requires a PostgreSQL database be running, and a user and database must exists that the XDirectoryService can use to CREATE/DROP tables in. Once the PostgreSQL system is setup it can be used by specifying "--impl postgres" on startup and defining a "xdrs_postgresql_url" to be a PostgreSQL connection URL such as: jdbc:postgresql://postgresql_server/database_name?user=username

Examples

Examples of how to run the XDirectoryService (assuming [t]csh):

The in memory HSQLDB XDirectoryService:

./run.sh server

The persistent in memory HSQLDB XDirectoryService:

setenv JAVA_OPTS "-Dxdrs_hsqldb_dbname=hsql_test_db"
./run.sh server

The persistent in memory HSQLDB XDirectoryService that is emptied at the beginning of the run:

setenv JAVA_OPTS "-Dxdrs_hsqldb_dbname=hsql_test_db -Dclean_database=true"
./run.sh server

Examples of how to run the XDirectoryService (assuming windows):

NOTE: Before anything else, run classpath.bat to set your classpath.

The in memory HSQLDB XDirectoryService:

java xdrs_impl.Run

The persistent in memory HSQLDB XDirectoryService:

java -Dxdrs_hsqldb_dbname=hsql_test_db xdrs_impl.Run

The persistent in memory HSQLDB XDirectoryService that is empties at the beginning of the run:

java -Dxdrs_hsqldb_dbname=hsql_test_db -Dclean_database=true xdrs_impl.Run


Last modified: Tue Jul 29 15:43:52 EST 2003