OCLC Research SRW Server 2.0 Installation Instructions

Get and unpack the file SRW.zip.  It contains everything you need to build the base SRW server, but does not include the libraries necessary to build the DSpace or Pears interfaces.  The normal DSpace installation will have all the jars necessary and all you’ll have to do is edit build.properties to point to the directory that contains the DSpace jars.  If you want a Pears interface built, you’ll need to edit build.properties to point to the directory that contains the Pears jar.  That directory may also contain the Gwen and Dbutils jars or you can edit build.properties to point at their directories if you are maintaining them separately.

The code distributed in the zip file may be out of date.  You can run “ant checkout” to get the latest versions of the code.

Run “ant war” to compile the code and build a war file.  ant deploy” will do that also, plus copy the war file to your <tomcat>/webapps directory, if you’ve specified the serverPath in the build.properties file.  After you’ve run “ant war”, you’ll find a directory named “dist” and in it you will find the war file and the SRW jar files.  If you have an existing SRW deployment with its own configuration files, you may want to just copy the SRW jar files to your <tomcat>/webapps/<SRW>/WEB-INF/lib directory.

Configuration Files

The two primary configuration files, web.xml and SRWServer.props, are in the <SRW>/WEB-INF and <SRW>/WEB-INF/classes directories respectively. web.xml controls the interaction between Tomcat and the SRW servlet. SRWServer.props controls the behavior of the servlet.

web.xml

Every web service, of which SRW is one, has a web.xml configuration file. This file contains configuration information for the servlet engine (Tomcat) and optional parameters for the servlets. It resides in the WEB-INF subdirectory of the web service. There should be little reason to edit this file.

There is a single optional parameter for the SRW server: PropertiesFile.  This parameter is commented out in the distribution.  Normally, the server expects to see a file named SRWServer.props in the <tomcat>/webapps/<SRW>/WEB-INF/classes directory.  If you have a need to either rename or move that file, then you’ll want to uncomment the parameter and specify the full path to the properties file.

SRWServer.props

By default, the SRW server expects to find any files it needs in the WEB-INF/classes directory.  If you need to put things like the SRWServer.props file or XSLT files for record transformation anywhere else, then you should edit the SRW.Home path to point at that directory.

You can change the name of your default.database, if you want.

You can change the resultSetIdleTime, if you want. This is a time in seconds and determines how long query results are kept after they have last been referenced.

DSpace

If you are running DSpace, then you need to change db.DSpace.home to point at your DSpace directory. This will be the directory that contains the DSpace conf directory. (Don't forget the trailing slash on the path.) The SRWServer.props file is set to point at an SRW configuration file for the DSpace database. It expects to find that configuration file in the conf subdirectory of the DSpace directory. You will need to copy the file DSpace.SRWDatabase.props to your /conf directory. (See DSpaceSRWConfiguration.html for information about that file.)

If you are not running DSpace, this section can be left in the configuration file with no ill effects.

Pears/ Newton

There are three pieces of information necessary to configure a Pears or Newton database. First, you specify that the database is a Pears/Newton database with the db.<dbname>.class parameter, setting it to ORG.oclc.os.SRW.SRWPearsDatabase. Replace <dbname> with the name of your database. (Sorry, no embedded blanks in the dbname.) Next, you specify the location of the files needed by the database via the db.<dbname>.home parameter. You point this at the path to the directory that contains, at least, the SRW configuration properties file for the database. (Don't forget the trailing slash on the path.) Finally, you specify the name of the properties file via the db.<dbname>.configuration parameter. Typically, this file is named SRWDatabase.props. (See PearsSRWConfiguration.html for information about that file.)

Build

Go to the <SRW> directory and run ant. (See The Apache Ant Project for more information about ant.) By default, it compiles the source code and builds the srw.jar file in the <SRW>/build/ directory. If you have previously deployed the SRW.war file, then this is probably all you need to build and you should copy <SRW>/build/srw.jar to your existing <Tomcat>/webapps/SRW/WEB-INF/lib directory.

If you need to build the SRW.war file to deploy the SRW service, then enter "ant war" at the command line. Copy the SRW.war file from the <SRW>/build/ directory to the <Tomcat>/webapps directory. When you restart Tomcat, it will create a new webapp named SRW. If you would like to name the service something else (e.g. dspace-srw) then simply rename the SRW.war file (e.g. dspace-srw.war.) Restart your Tomcat server.

You can get the latest version of the SRW Server code by entering "ant checkout" at the command line. This will get the latest copy of the code from our CVS repository. (See Concurrent Versions System for more information about CVS.) After getting the new code, you will want to run ant to build the .jar and .war files.

Testing

The URL http://localhost:8080/SRW/search/test?query=dog&maximumRecords=1 will cause a query to be sent to the SRW test database. (You may have to change the host and port to get to your copy of Tomcat.) Any searches against the test database will report the creation of a result set with one record in it. The URL above also requests the return of one record.

If the installation is correct, then you will see something like this in the response:

 

A Project of OCLC Research

OCLC Online Computer Library Center

Result of search: dog

 

Search Results

Result Set Identifier: 7h5pcj
Records found: 1

Records

 

Position: 1 Schema: Dublin Core

srw_dc:dc.dc:identifier:

test001

srw_dc:dc.dc:creator:

Ralph LeVan

srw_dc:dc.date:

2003-08-25

srw_dc:dc.dc:title:

SRW Test Record

 

Home

Powered by OCLC SRW/U

 

Test Failure Modes

"Cannot find server or DNS Error"
You've specified the wrong host or port or Tomcat isn't running.

"The download of the specified resource has failed"
The SRW Servlet failed during initialization. The Tomcat log should contain information explaining the failure. If the servlet was unable to find the SRWServer.props file, you will see in the log several attempts to open the file and finally a FileNotFoundException.

I am sure there are other failure modes during testing. I'll document them as they are reported.

URL Construction

A typical SRW URL looks like this: http://localhost:8080/SRW/search/test?query=dog&maximumRecords=1.

The first part points at your host and port. After the slash is the name of the Tomcat webapp that should process the request; SRW in this case. If you changed the name of the SRW.war file before Tomcat deployed it, then the webapp will have a different name. (If you changed the name to dspace-srw.war, then the webapp is named dspace-srw and the URL becomes http://localhost:8080/dspace-srw/search/test?query=dog&maximumRecords=1.

Everything after the webapp part is compared with the patterns specified in the web.xml file. We have told Tomcat that the pattern "search/*" indicates a URL that should be given to the SRW Servlet. You can edit the web.xml file and change the url-pattern in the servlet-mapping for the SRWServlet, if you want to use a different pattern.

After the pattern comes the name of the database to be searched. If this is omitted, then the default database, as specified in your SRWServer.props file, will be searched. As originally deployed, the DSpace database is the default and can be omitted from the URL.

Finally, comes a question-mark and the SRW parameters. Information about SRW can be found at http://lcweb.loc.gov/z3950/agency/zing/srw

CVS Repository

The source code for the SRW Server is available from OCLC Research's CVS server. You can access it using the cvsroot: :pserver:anonymous@pubserv.oclc.org:/home/CVS/srw/cvsroot.

The <SRW>/src directory already has the control files necessary to access our CVS server. You should be able to point your favorite CVS tool at that directory.

Finally, there is an ant task that will update the <SRW/src directory. "ant checkout" on the command line will run this task and update your source files with the latest version.

License

The OCLC Research SRW Server is released under the Apache 2.0 license.

Contact Information

Any questions, comments, suggestions or opinions should be sent to Ralph LeVan (Ralph's Home Page.)
OCLC Research
OCLC