4 Yaz4j is a Java binding for the high-level, client-side portion of the YAZ
5 toolkit known as the ZOOM API. With Yaz4j you can program clients for YAZ-
6 supported protocols like Z39.50, SRU/W and Solr. Yaz4j includes a native
7 component and supports Windows, Linux and OSX.
12 Index Data provides ready to use yaz4j RPMs for CentOS 5 and 6, available from
13 our public YUM repository. On Windows yaz4j can be installed with the YAZ
14 [installer][4]. Those methods are the simplest ways to get yaz4j up and running
15 on the particular platforms and are highly recommended.
18 Index Data YUM repository (CentOS)
19 ----------------------------------
21 Yaz4j with it's runtime and compilation dependencies are provided through
22 Index Data's YUM repository, the repository is enabled by placing the following
26 name=Index Data Main Repository
27 baseurl=http://ftp.indexdata.com/pub/yum/centos/6/main/$basearch
28 failovermethod=priority
30 gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-indexdata
34 at `/etc/yum.repos.d/indexdata.repo`.
36 With the above repository enabled, yaz4j can be simply installed with:
40 And the installation can be verified by running a provided test program which
41 executes a search against a public Index Data Z39.50 test server:
43 java -jar /usr/share/java/yaz4j.jar
46 YAZ Installer (Windows)
47 -----------------------
49 YAZ Windows installer can be downloaded from [here][4]. Yaz4j is bundled with
50 the installer: just make sure during the installation yaz4j box is checked.
51 It is also recommended to check the box for updating updating PATH environment
52 variable with a path to yaz binaries. After installation yaz4j can be tested
53 with (Java runtime environment required):
55 java -jar C:\Program Files\YAZ\java\yaz4j.jar
57 All native libraries and binaries are located in `C:\Program Files\YAZ\bin\`
60 COMPILATION FROM SOURCE
61 =======================
63 Checking out the source code
64 ----------------------------
66 Yaz4j can be checked out from Index Data's Git repository:
68 git clone git://git.indexdata.com/yaz4j
70 It's recommended to build the latest tagged version (see tags with `git tag`),
73 git checkout v1.5 -b v1.5
76 Compilation on CentOS/RHEL
77 --------------------------
79 Compilation requires [JDK][1], [Maven][2], [Swig][3] and [YAZ][4] development
82 Installing build dependencies can be done through the package manager specific
83 for the distribution (subject to availability), for CentOS 5/6 (YUM) JDK and Swig RPMs can be installed with:
85 yum install java-1.7.0-openjdk-devel swig
87 While YAZ development package needs to be installed from Index Data's YUM
88 repository (see INSTALLATION on how to enable the YUM repo):
90 yum install libyaz5-devel
92 Maven is not part of CentOS so a binary distribution needs to be downloaded
93 from Maven [website][2] and installed manually. Refer to Maven's website for
94 details. In case Index Data's YUM repo is enabled, Maven 3 can also be
97 yum install maven3-indexdata
99 in which case Maven program is called `mvn-id` rather than `mvn`.
101 With all dependencies in place you can continue the yaz4j compilation with:
106 Which will also run tests that open a connection to Index Data's public Z39.50
109 Notice that `yaz-config` binary must be on the PATH (this is assured when
110 `libyaz5-devel` package is installed), if it isn't e.g if a local YAZ (source)
111 installation is used, the binary location can be specified with:
113 mvn -Dyaz.config=/path/to/yaz-config install
115 The compiled jar file ends up in any/target/yaz4j.jar while the native library
116 in unix/target/libyaz4j.so.
118 Compilation on generic Unix
119 ---------------------------
121 You will need the JDK, Maven, Swig and YAZ development packages.
122 Consult your package manager on how to install those.
124 If yaz-config is in your PATH, the following command should suffice:
128 If yaz-config is not in your PATH, you'll have to tell where YAZ is located:
130 mvn -Dyaz.config=/path/to/yaz-config install
135 Besides the exact same requirements as in the Unix case (JDK, Maven, Swig,
136 YAZ), you will need the Windows [SDK][5] installed (which in turn requires
137 .NET Framework 4) to compile yaz4j. Again it's much easier to use the
138 YAZ Installer. Git must be installed to checkout yaz4j source code.
140 Use the command prompt provided with the Windows SDK, navigate to the yaz4j
141 source directory and run:
145 Default 64-bit YAZ installer location is assumed for the 'yaz.path' property.
146 Nothing is assumed for 'swig', so you either need to specify an absolute path
147 or update the PATH environment to include the directory containing swig.exe.
148 Both can be specified with:
150 mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install
152 YAZ4J AND A SERVLET CONTAINER
153 =============================
155 If you are coding a web application that uses yaz4j there's a couple of things
156 to keep in mind. First, you are not invoking the JVM directly, but the servlet
157 container (e.g Tomcat) run/init script is doing that for you and that's the place
158 to configure any environment settings (e.g the PATH). Second, yaz4j includes
159 static initializers to load the native part and can't be packaged along with the
160 webapp as that would break on consecutive redeployments. It must be deployed to
161 the servlet container common classloader similar to JDBC drivers.
163 For convenience, `yaz4j-tomcat6` RPM is provided in the ID's YUM repo which will
164 set up the default RPM-provided Tomcat 6 with yaz4j automatically:
166 sudo yum install yaz4j-tomcat6
171 In case when yaz4j is installed through the RPM (Index Data's YUM repo) the
172 native libraries are placed in the standard system locations (/usr/lib/.. etc)
173 and are readily available to all applications, including Tomcat. The only other
174 thing to configure is to add yaz4j.jar (the pure Java component) to Tomcat's
175 common class loader (further down).
177 In case when yaz4j is built from source or for some other reason the native
178 pars are not present in the standard system library locations, they need to be
179 placed on the servlet container's shared libraries load path. One way
180 to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is
181 by editing (create it if it does not exist) the CATALINA_HOME/bin/setenv.sh`
182 script and putting the following lines in there:
184 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so
185 export LD_LIBRARY_PATH
187 Notice, that this has to be done for all native libraries that `yaz4j.so`
188 dependson, e.g `libyaz5.so` and so on, unless they are already on the default s
189 ystem library paths (e.g when installed from RPMs).
191 If Tomcat is started by a custom init scripts similar operation needs to be
194 The pure Java yaz4j.jar must be added to Tomcat's common classloader so that
195 it becomes available to all deployed webapps and is loaded only once. There
196 are a couple ways to do that.
198 One (employed by `yaz4j-tomcat6` RPM) is to place (or symlink) `yaz4j.jar` to
199 to `$CATALINA_BASE/lib` (CATALINA_BASE is `/usr/share/tomcat6` when Tomcat was
200 installed from RPMs on CentOS):
202 ln -s /path/to/yaz4j.jar /usr/share/tomcat6/lib
206 Another option is to edit the file `catalina.properties` shipped with Tomcat
207 (and located in `CATALINA_BASE/conf/` e.g `/etc/tomcat6/`on RPM-packaged Tomcat)
208 and extend the `common.loader=` property with the following:
210 common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,/path/to/yaz4j.jar
212 again restarting Tomcat afterwards.
214 Please consult Tomcat documentation for more information on [classloading][6].
219 On Windows Tomcat will most likely be run from the binary distribution which
220 includes `CATALINA_BASE/bin/setenv.bat` for the purpose of setting up the
221 environment. Unless, you have installed yaz4j.dll with the YAZ Installer and
222 checked the option to update the global PATH and include all native YAZ and
223 yaz4j components, edit setenv.bat with the following:
225 set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll
227 The `X:\path\to\yaz\bin` is `C:\Program Files\YAZ\bin` when the installer was
228 used and includes also yaz4j.dll.
230 In case Tomcat is start up does not execute `setenv.sh`, e.g when custom startup
231 script is used, please include similar steps there.
233 To deploy `yaz4j.jar` you must follow steps identical to those from the Linux
234 section. Again, when installer is used `yaz4j.jar` is located at `C:\Program Files\YAZ\java\yaz4j.jar`.
240 Under yaz4j/examples you'll find a small zgate app. This can be deployed
241 to Tomcat to test the yaz4j installation. To do so:
243 cd yaz4j/examples/zgate
245 cp target/zgate.war CATALINA_BASE/webapps
247 (substitute / with \\ and copy as necessary under Windows!)
249 If successful you can run the application with a URL as follows:
251 [http://localhost:8080/zgate/?zurl=z3950.indexdata.com/marc&query=computer&syntax=usmarc](http://localhost:8080/zgate/?zurl=z3950.indexdata.com/marc&query=computer&syntax=usmarc)
253 PREPARING A DEVELOPMENT ENVIRONMENT
254 ===================================
259 If you are using maven to build your application you can include Index Data's
260 Maven repo location and include yaz4j dependency in your project:
264 <groupId>org.yaz4j</groupId>
265 <artifactId>yaz4j-any</artifactId>
266 <version>VERSION</version>
267 <scope>provided</scope>
271 It's crucial that the scope of this dependency is set to `provided` for web
272 application type projecets, otherwise the library would end up packaged in
273 the .war archive and we wouldn't want that.
275 Yaz4j includes a trivial HTTP to z3590 gateway under `examples/zgate` that shows
276 best how to use yaz4j in a servlet. There's also a blog entry on building the
283 The following is most probably already outdated, consult Google.
285 [1]: http://www.oracle.com/technetwork/java/javase/downloads/index.html "JDK"
287 [2]: http://maven.apache.org/download.cgi "Maven"
289 [3]: http://www.swig.org/download.html "Swig"
291 [4]: http://www.indexdata.com/yaz "YAZ"
293 [5]: http://www.microsoft.com/en-us/download/details.aspx?id=8279 "Windows SDK"
295 [6]: https://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html "Tomcat 6 class loading"
297 [7]: http://www.indexdata.com/blog/2010/02/building-simple-http-z3950-gateway-using-yaz4j-and-tomcat "Building a simple HTTP-to-Z39.50 gateway using Yaz4j and Tomcat"