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.
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.
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.
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
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.
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
If you are not running DSpace, this section can be left in the configuration file with no ill effects.
There are three pieces of
information necessary to configure a Pears or
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
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.
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:
Result Set Identifier: 7h5pcj
Position: 1 Schema:
"Cannot find server or DNS
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.
A typical SRW URL looks like
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
The source code for the SRW
Server is available from OCLC Research's CVS server. You can access it using
the cvsroot: :pserver:firstname.lastname@example.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.
The OCLC Research SRW Server is released under the Apache 2.0 license.