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
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
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:
|
Result
of search: dog |
|
Search Results
|
||||||||
|
Result Set Identifier: 7h5pcj |
||||||||
Records
|
||||||||
|
|
||||||||
|
Position: 1 Schema:
|
||||||||
|
|
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