STARTS
Stanford Protocol Proposal for Internet Search and Retrieval

Reference Implementation

Installing and running version 2.0:  the CORBA implementation

This page describes how to install the components of the CORBA STARTS reference implementation on your UNIX and CORBA/java workstations and how to run them. Some of the components are the same as those used for the non-CORBA implementation -- if you are running STARTS version 1.0 or 1.1, we recommend that you reinstall all the STARTS code (start at step 3 below).  You might wish to refer to the CORBA implementation notes for more information about the organization of the software and how it interacts.  The entire set of components have been tested and run on Solaris 2.5 (for the wais server and dummy server) and Windows NT (Java pieces) and using CORBA ORB OrbixWeb 3.0. Note that even though the Java parts of the implementation will run on any Java virtual machine, the freeWAIS parts of the implementation will run only on UNIX.  Moreover, the Java code must be able to communicate properly with a CORBA server -- you may need to tweak the java code if you use an ORB other than OrbixWeb 3.0.  See the implementation notes for more information.

1. Install the freeWAIS search engine
   • Download the tar'ed freeWAIS binaries that have been compiled for Solaris 2.5 onto your UNIX workstation.
   • Create a new UNIX directory (which we'll call <freewais> here) and extract the tar'ed files into that directory.
2. Install the sample database
   • Install the index files
     • Download the tar'ed source index files onto your UNIX workstation.
     • Create a new UNIX directory (which we'll call <indexes> here) and extract the tar'ed files into that directory.
     • NOTE: the <indexes> directory will now contain the inverted index, catalog, dictionary, and ancillary files for each source (cstr and linux). The two files with the "fmt" suffix are the format files for each source, which allow the wais indexer to extract field information from the document source files (see the freeWAIS documentation for more information.)
   • Install the document files
     • Download the tar'ed cstr document sources onto your UNIX workstation.
     • Create a new UNIX directory (which we'll call <cstrdocs> here) and extract the tar'ed files into that directory.
     • Download the tar'ed linux document sources onto your UNIX workstation.
     • Create a new UNIX directory (which we'll call <linuxdocs> here) and extract the tar'ed files into that directory.
   • Modify the index files to point to the document files
     • Open the two files cstr.cat and linux.cat in the <indexes> directory using your favorite text editor.
     • Both files consist of headlines and DocID's for the set of documents in the source. Globally change the pathname for the documents to point to the respective file in either <cstrdoc> or <linuxdocs>. For example, Document #1 in the cstr collection has the pathname
       /home/lagoze/projects/starts/freewais/cstrdb/92-1260
       Change this to:
       <cstrdocs>/92-1260
     • NOTE: you could re-index the files to accomplish the same task, but this method is easier.
3. Get the CORBA STARTS source files.
   • Download the zipped STARTS Release 2.0 source files onto your CORBA/Java workstation.
   • Create a new folder (which we'll call <startsServer> here) and extract the zipped files into the <server> folder.
   • The <startsServer> folder should now have nine subfolders.  Subfolder "client" has the required source files and some other necessary files for the CORBA client.  Subfolder "IDLFiles" has the IDL file in it.  The other seven of subfolders, plus the three files in the top level folder are source code for the CORBA version of the STARTS server.
4. Compile the IDL file.
   • The IDL file was packaged with the server code in the zip file (see number 3 above).  If you extracted the files into your <startsServer> folder, then the IDL is <startsServer>/IDLFiles/idlstarts.idl.
   • Using the IDL compiler supplied with your CORBA ORB, generate java files from the IDL.
   • Make sure you know exactly where the generated java files were placed, as both the STARTS client and the STARTS server are dependent on this code.
5. Install the CORBA StartsServer code.
   • Modify CORBA StartsServer for your host.
     • Open the file <startsServer>/STARTSConfiguratin/ServerConfiguration.java in your favorite text editor.
     • Change the initial value of the variable "hostName" to correspond to the CORBA/Java that your server will run on.
   • Determine if you will be running the server on a UNIX or an NT environment.
     • Either way, you will need to make some further changes to the code.  Make the changes as described in the release 2.0 notes for platform specific code.  They will include specification of WAIS index locations and document locations, among other things.
   • Compile the server code. 
     • The main class for the server is <startsServer>/corbaServer.java.
     • The server code requires access your CORBA classes (provided with your CORBA ORB) and to the generated java code from the IDL (see step 4 above), in addition to access to a JDK.  We edited via SymantecVisualCafe PDE, so we compiled the server code from within that context and included the CORBA classes and the generated IDL files via directories in project options (rather than via our machine's classpath).
     • FYI: all code in the <startsServer> directory is relevant EXCEPT:
       • dummyServer.java
       • client subfolder
       • IDLFiles subfolder (unless you've placed your IDL generated java files here)
   • NOTE: the server code is written for the OrbixWeb 3.0 CORBA ORB.  You may need to make further modifications to the code if you are using a different ORB.
6. Register the CORBA STARTS server in the CORBA implementation repository
   • Follow the directions that came with your CORBA software to register the CORBA server.  For example, with OrbixWeb 3.0, the command is: "putit STARTS -java corbaServer"
   • File <startsServer>/corbaServer.java uses "STARTS" as the name of the server in the ORB. 
7. If you plan on running the StartsServer on NT, rather than UNIX, you will need to install the bridge server on UNIX.
   • Create a new directory (which we'll call <bridgeserver> here) on the same UNIX machine on which you installed freeWAIS.
   • Copy the <startsServer>/DummyServer.java file from your CORBA/Java workstation to the <bridgeserver> directory.
   • Copy the <startsServer>/wais and <startsServer>/resource subfolders (= java packages) from your CORBA/Java workstation to the <bridgeserver> directory.  These are needed for DummyServer to compile.
   • Modify DummyServer.java.
     • DEFAULT_PORT:  this is the port for the DummyServer, and as the comments indicate, it needs to match the port specific in the WAISSearchLink method in wais/WAISSourceDescription.java.
     • defaults for WAISServerHost and WAISServerPort:  towards the bottom of the file, in the DummyConnection class are two static variables which should be set to the hostname and port of your WAIS server running on unix.  These defaults can be overridden at runtime, but you will probably find it convenient if the defaults are set to a valid WAIS Server.
   • Compile "DummyServer.java" with your favorite JDK.
8. Install the CORBA StartsClient code.
   • The client code was packaged with the server code in the zip file (see number 3 above).  If you extracted the files into your <startsServer> folder, then the client code is in <startsServer>/client.
   • You may want to change the default hostname for the client.  You can edit this at runtime, but to change the default, you will need to go into file "STARTSClientStartApplet.java."  Look for the "init()" method (at the beginning of the file), and find a line that says "hostnameTextField.setText("moscow")"  Change "moscow" to the default hostname you want.
   • Compile the client code.
     • If you will be using the client as an application, the main class for the client is <startsServer>/client/STARTSClientGUI.java.   If you will be using the client as an applet, the applet is <startsServer>/client/STARTSClientApplet.java.
     • The client was developed in SymantecVisualCafe PDE, and it uses some Symantec classes.   These have been included with the client source code in file <startsServer>/client/symantecClasses.jar.   You may need to include this JAR file in your classpath to get the client to compile.
     • The client code requires access your CORBA classes (provided with your CORBA ORB) and to the generated java code from the IDL (see step 4 above), in addition to access to a JDK.  We edited via SymantecVisualCafe PDE, so we compiled the client code from within that context and included the CORBA classes and the generated IDL files via directories in project options (rather than via our machine's classpath).
   • NOTE: the client code is written for the OrbixWeb 3.0 CORBA ORB.  You may need to make further modifications to the code if you are using a different ORB.
   • NOTE:  We had difficulty launching the applet from a web page because our web browsers were unable to handle java 1.1. event modeling as used by our development environment.  Nevertheless, we did provide a simple html file,  <startsServer>/client/startspage.htm, to indicate how the applet might be launched.   The client requires access to:
     1. STARTS client class files
     2. symantec classes used by client and included in <startsServer>/client/symantecClasses.jar
     3. (some of) the classes generated from the starts IDL
     4. CORBA classes provided by your ORB.

     All of these can be placed in a single JAR file.  Our example jar file is here.

9. Run the components.
   • Run the freeWAIS server on your UNIX workstation.
     • in the <freewais> directory run the executable waisserver with the arguments "-p 5001" (specifying port 5001) and "-d <indexes>" (specifying that the indexes are in the directory <indexes>)
   • If you will be running the startsServer on NT, rather than UNIX, then run the bridge server on your UNIX workstation.
     • in the <bridgeserver> directory run the java code DummyServer.   You can either run it with the default port and the default hostname/port for the WAIS Server, or you can enter these as runtime arguments.   To specify all of these, the command is "java DummyServer <DummyServer port number> <WAIS Server hostname> <WAIS Server port number>".  To use the defaults for the WAIS server, the command is "java DummyServer <DummyServer port number>."  To take all defaults, the command is "java DummyServer."
   • Run the CORBA server.
     • Follow the instructions for your CORBA software to get it running.  For example, with OrbixWeb 3.0, you must start the Orbix Daemon.
     • NOTE:  STARTS must be registered with the CORBA Implementation Repository.   See 6. above.
   • Run the CORBA STARTS Server
     • in the <startsServer> directory, run the command "java corbaserver".
     • The CORBA STARTS Server will then start up, issue messages that it has pre-loaded document sources for both the cstr and linux source, and then listen on port 6790.
     • NOTE that for the server to run, the classpath needs to include 1) the STARTS server classes   2) the generated IDL classes 3) java classes and 4) CORBA classes.  If you have trouble, make sure you have configured your CORBA server correctly, and that you know which JDK you are accessing, etc.
     • NOTE that you may encounter runtime errors if you are using a different ORB than OrbixWeb 3.0.
   • Run the CORBA STARTS Client
     • To run the client as an application, in the <startsServer/client> directory, run the command "java STARTSClientGUI <hostname> STARTS" where <hostname> is the hostname of the box running the ORB.  NOTE that you will need a JDK that not only speaks java 1.1 but that does 1.1 event handling.
     • To run the client as an applet, you need an appletviewer or html browser that does java 1.1 event handling.  The front end file to run the client this way is "STARTSClientApplet."  Since we were unable to run our applet via a browser, we did not spend time trying to make a nice web page for our applet, nor did we put html links to help files on our applet.
     • NOTE that for the client to run, the classpath needs to include 1) the STARTS client classes   2) the generated IDL classes 3) startsServer/client/symantecClasses.jar   4) java classes  and 5) CORBA classes.  If you have trouble, make sure you have configured your CORBA server correctly, and that you know which JDK you are accessing, etc.
     • NOTE that you may encounter runtime errors if you are using a different ORB than OrbixWeb 3.0.

   You can now use the client to submit STARTS requests and get results.  There is documentation for valid filter and ranking expressions.

Send questions to help@ncstrl.org