up
Up: The DRE Project - The Tool

Configuring DRE v2.05 - DRE Server

Configuration

The DRE Server is increasingly simple to run - a one line command is all that is necessary to kick-start the Server, and it runs by itself. The necessary configuration is inversely proportional. While every attempt has been made to minimize the amount of work that a standard user must do in order to get CDRE running, some hefty configuration is required to enable maximum flexibility of the system.

The DRE Server must be configured properly and started before any CDRE client can connect to it. Therefore, these detailed directions may be overkill, but the attempt to fully explain each step in the configuration in order to get the system working. Begin configuring the system by reading the Standard DRE Configuration Document; it might actually help to have run standard DRE on a workstation in order to understand what the goal of setting up CDRE is.

Without further ado, then, here are the configuration topics for setting up the DRE Server.


Installing the Code Base

From the DRE Website, it is necessary to download the latest .jar file containing the DRE Server code. This should be clearly marked. It can be put into any directory on the server, but a word of caution is important here. The DRE Server will allow access to source files on the server; therefore it should only be run as a process by a user that has as restricted an access to the system as any of the users of DRE. For example, if you run DRE Server from a root ID, you may give CDRE Clients view access to more than they should be able to see. While CDRE will not allow any users to manipulate the contents on the server, they may be able to get the directory structure of directories that are supposedly off-limits. A good idea would be to create a new operating system user ID that only runs DRE Server, and has access only to directories where source code is stored on the machine.

The various .jar files that complement DRE are also needed on the server end. The full description of how and where to install these .jar files can be found in the Standard DRE Configuration Document.


Specify the IP Address and Port

The DREServer runs on some IP Address on a particular port. The IP Address is the address of the machine on which the DREServer is running. The Port may be any valid not-in-use port on the machine. To specify these values, a configuration file must be updated. The file "options.txt" in the "config" subdirectory (inside the installation directory) needs to be altered to include the IP address and port values. This information also needs to be communicated to each DRE Client that wishes to communicate with the DRE Server.

The following steps should be sufficient to set up the proper IP Address and port number for the DRE Server.

  1. Locate the configuration file "options.txt". It should appear in a subdirectory "config" inside the directory in which the DRE has been installed. If you cannot find it, create a subdirectory "config" and put a new text file "options.txt" into it.
  2. Open "options.txt" for editing. It should contain lines similar to the following (if you had to create "options.txt" in the previous step, copy and paste these lines into it):
    DREServerIP:INSERT_DRE_SERVER_IP_ADDRESS_HERE:
    DREServerPort:INSERT_DRE_SERVER_PORT_NUMBER_HERE:
    RemoteDirectory:INSERT_DRE_SERVER_REMOTE_STARTING_DIRECTORY_HERE:
  3. Replace "INSERT_DRE_SERVER_IP_ADDRESS_HERE" with the IP address of the machine. The line should now read something like:
    DREServerIP:12.123.210.1:
  4. Replace "INSERT_DRE_SERVER_PORT_NUMBER_HERE" with the port number you have assigned to the DRE Server.
  5. Delete the line beginning with "RemoteDirectory". It is unnecessary for the DRE Server.
  6. Save and close "options.txt".

Choosing a Database Strategy

One of the responsibilities of the DRE Server is to coordinate the storage of user IDs, Project contents, and Class markings. To do this, DRE works with various databases. These databases may be contained locally on the same machine, or may exist on other hardware. The databases may be vertically partitioned. They may be encoded in the default XML-format, or may be translated into relational tables defined by the development team. The database choices are plentiful, and constitute the most difficult part of DRE.

For first time users of CDRE, we recommend the following configuration: Locally-accessible databases; No partitioning strategy; Using the default-XML storage technique. As users mature in their understanding of the DRE, it is understandable that they may wish to customize this data layout, and so instructions for all of these configurations are presented here.

Choosing Between Data Storage Formats

The default storage mechanism for the data is in a homegrown, XML-based database. This works well, handling all of the requirements of the CDRE application, and it is fully distributable, without having to sell users a full-blown database in order to run DRE. However, we recognize that users may wish to use their own proprietary systems to store the application data, especially if there is some other benefit to the stored information for business processes. Therefore, we provide a method for allowing customizers to write code to interoperate the DRE with their own proprietary storage techniques. For the majority of users, however, this is overkill, and the default XML-based implementation will be sufficient.

Choosing Between Localized Databases and Remote Databases

The first and simplest strategy decision is to determine where you want to keep the application data, on the same machine as the DRE Server, or on a different one. The data stored by the server should be relatively small, compared to the source code that likely appears on the server. Consequently, we recommend that you keep the databases locally on the same machine. If you do have the need to store the data elsewhere, be aware that access times will now be dependent on RMI and will therefore increase.

Changing the location of the databases requires alteration of a configuration file. If the databases are locally defined, no other work is necessary. If the databases are to be located on remote machines, they will need to be started on those machines, and their IP addresses/ports coordinated with the DRE Server. More detail will occur in the actual configuration instructions.

Choosing Between Partitioned and Non-partitioned Data

By default, all user information goes into one database, all project information goes into another database, and all class information goes into a third. If, for some reason, the development team wishes to partition the data (for example, the user data), this is also supported by CDRE. The steps are slightly more complicated, and involve manipulating a configuration file as well as the source code for one class. Vertical data partitioning is supported, by splitting up the data according to some key among the various data sources. Although this function is fully supported and tested, it is VERY complicated, and should only be decided upon as a course of action with good reason after a LOT of consideration.


After the database strategies have been selected, you can visit the individual configuration sections to learn how to do each configuration.


Creating XML Databases

Using DRE with the standard XML database is simple. All that is required is that a directory be created for each database (i.e., one for Users, one for Projects, one for Classes). This is all. Advanced users who wish to partition the data will need to create one directory for each partition. If you have decided to use local databases (the standard installation), create the directories on the machine housing the DRE Server. If you wish to use remote databases, create the directories on whichever machines are to house the data.


Creating Other Databases

If you have chosen this option, be sure, be very, very sure. It is not too difficult, but it will require some Java coding to complete. The task is not likely to be finished in under a week. Ensure that you have good need to do this before attempting it.

First an overview of the communication of CDRE. DRE Server communicates with the databases by querying a database repository, the DatabaseFinder class. This repository provides the DRE Server with access to objects through various database interfaces, coded as Java classes UserAccess, ProjectAccess, and ClassAccess for the three databases. All calls to the databases must be made through the methods listed in these interfaces.

In order to code a different database backend to CDRE, you will need to provide an implementation to each of these three XXXAccess classes, and rewrite DatabaseFinder. Each and every method of the three database access classes must be implemented in your new database. When these classes have been written and tested, DatabaseFinder must be rewritten to create new instances of your implementation of the database access interfaces. The whole process sounds simple, but will involve a lot of time in discovering the necessary schemas and code work in order to interact with the database. Feel free to do it if you are up to the challenge; users using the default XML-based databases will be able to start working right away.

Further, if you do intend to create your own databases, the section on setting up local or remote databases will be meaningless. You must code your own way for the DatabaseFinder to locate your databases.


Setting Local Databases

Setting up the local databases is a snap. Follow the directions in order, and the databases should work without issue. (These directions assume you are working with the default XML-based databases; advanced users will need to work with their own configuration files, as specified previously).

  1. Locate the database configuration file. It should be in the "config" subdirectory of the installation directory as the file "xmldb.txt". If it is not found, go to the DRE Website and download it.
  2. Open the file in an editor.
  3. In the section "Creating XML Databases", you were instructed to create three directories. Ensure that you know the full paths to these directories.
  4. We will specify the class database first. There should appear a line in the configuration file like:
    ClassDBPath
    Add a line immediately after this in the following structure:
    ::/home/dre/xmldb/cdb/
    where "/home/dre/xmldb/cdb/" is replaced by whichever path stores the directory for the class database.
  5. If you have decided to partition the data in the class database (not recommended!), and you have other paths that the data is stored, enter them on separate lines after the current line.
  6. For any other pre-existing paths that exist in the configuration file, delete them or comment them out by prepending a semi-colon at the start of the line.
  7. Repeat the last three steps with the directory(ies) for the Project database with keyword "ProjectDBPath".
  8. Repeat the previous three steps with the directory(ies) for the User database with keyword "UserDBPath".

Your local databases are now configured.


Setting Remote Database

Setting up remote databases is not much harder than doing it for local databases. However, the underlying implementation is different. Wherease local databases are activated by Java method calls, remote databases require RMI communication to running database threads. Therfore to enable Remote Databases, not only does proper configuration of the configuration file need to occur, but also the database threads and RMIservers on the remote hosts must be enabled.

First, the configuration file should be manipulated in the same way as in the Setting Local Databases section. But whereas each database in the case of local databases is created in the form:

::/home/dre/xmldb/cdb/
remote databases must include IP address and RMI ID information in their configuration entries:
123.231.12.210:ca1:/home/dre/xmldb/cdb
Each entry in the configuration file must have a similar form. Technically, the path is no longer necessary (it is only necessary to be known on the remote database host), but it is often convenient to use the same configuration files on all database servers as well as on the DRE Server. If any of the databases are located physically on the same server as the DRE Server as well (but still wish to be run as remote databases), you can alter the line to:
localhost:ca1:/home/dre/xmldb/cdb

Secondly, an RMI Name Server must be running on each database host. The rmiregistry program ships with Java installations. Run it with the command:

rmiregistry
on each database server. Because all communications occur through RMI, this server is used as the RMI process finder.

Next, begin the thread on each of the database servers. To do this, run the associated Java applications:

java DRE.cs.server.db.xml.ClassAccessXML THIS_IP_ADDRESS THIS_RMI_ID
java DRE.cs.server.db.xml.XMLProjectAccess THIS_IP_ADDRESS THIS_RMI_ID
java DRE.cs.server.db.xml.UserAccessXML THIS_IP_ADDRESS THIS_RMI_ID
Each application begins a specific instance of that database. It is essential that the configuration file ("config/xmldb.txt") contain an entry for the Database thread being begun. For example if you start your User database with
java DRE.cs.server.db.xml.UserAccessXML 137.99.10.239 uadb
it is essential that not only are you running your database at IP address 137.99.10.239, but also that you have a line in the configuration file on the database server that reads:
137.99.10.239:uadb:/home/dre/xmldb/udb
that specifies the IP address, an RMI ID for this instance of the database thread, and the path containing the database files. In this step, the specified RMI ID is bound to this thread (it will error out if something is already bound at that address... either restart the rmiregistry or run "java DRE.cs.server.db.XML_DB_Parameters" to clear out the registry).

Now your remote databases are ready to rock!


Partitioning the Databases

By default, the data in the databases is not partitioned, because it has no need to be. If you really want to partition the data, think again. If you still want to, follow these directions, but you have been warned. Standard installation operators may skip this step.

The DRE Server access the data through a database repository called the DatabaseFinder. This simple Java class is used to organize the databases, and make their locations and types transparent from the rest of the DRE application. Consequently, vertical partitioning can occur in systems by recoding this class.

If you are not using the default XML-based database implementation, you have already seen DatabaseFinder in action, and can likely figure out how to partition it according to your needs. Otherwise, this will be a primer. The XML databases are stored inside the configuration file "xmldb.txt", and has already been set up. A perusal of DatabaseFinder.java shows that it reads in the local paths or RMI IDs of all databases. To specify more than one database in the configuration file, just alter the read method to read that many databases from the configuration files and store that many database instances in the class. This is how to connect to more than one database for each type of data.

Next, each database is retrieved by the application by methods like getUserAccessDatabase(). The name of the request user or project or class is passed to the method. You can, therefore, code a partitioning strategy by analyzing this key and directing it to one of the databases. For intance, in our trials, we split users whose IDs began in letters A-I into one database, and those in J or later to a second database.

Using these techniques, you can partition your data until your heart is content!

Creating Users

CDRE does not yet have an online facility to create users. This will occur as work progresses. For now, user information must be coded by hand. If you are not using the default XML-databases, you must enter your data in your own defined way. If you ARE using the XML-based databases, follow these directions to enter users for your system.

Each XML user database directory should contain one file: DREUsers.xml. Download this file and alter it so that it contains the user information for all users of the DRE (and consequently should be protected to being viewed only by the administrator of the DRE Server. The file should look similar to the following:

<DREUsers>
  <developers>
    <user>
      <userID>jre95001</userID>
      <name>Jeff Ellis</name>
      <password>jeff</password>
      <description>graduate student - DRE manager</description>
      <group>cse350</group>
    </user>
	...
  </developers>
</DREUsers>
Other users can be added to the file where the three periods occur. The file information should be pretty self-explanatory, identifying the name, user ID, password, optional description, (which all must occur exactly one time per user) and optional groups (groups are not yet active in DRE, but a user entry may contain zero or more groups). Note that alSpacing does not matter; it is preserved only for convenience to human eyes. Until the online user facility is created, all users must be added via text-entry here.

Starting and Stopping the DRE Server

Finally, we are ready to run the DRE Server. A simple command line entry is all that is needed:

java DRE.cs.server.DREServer
Assuming all configuration files exist in the right places, and assuming that all remote databases that have been created (if they have been created... this is not necessary) are running, then the DRE Server should be open for business. Woohoo!!

DRE Server allows the administrator to sneak peek at all network communications that are occurring. Simply add the flag "-d3" to see debug information including encoded requests and signals that state when threads are created and/or terminated.

Stopping the server is as simple as killing the process. If it is running in the foreground, try CONTROL-C or CONTROL-D. If it is running in the background, locate it and kill it.


Should you have any other questions regarding configuration of the DRE Server, please feel free to send a note to the DRE Development Team.


Last Modified: 17 July 2002