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 z3950, SRU/W and SOLR. Yaz4j includes a native
7 component and supports Windows, Linux and OSX.
13 Index Data provides ready to use yaz4j RPMs for CentOS 5 and 6, available from
14 our public YUM repository. On Windows yaz4j can be installed with the YAZ
15 [installer][4]. Those methods are the simplest ways to get yaz4j up and running
16 on the particular platforms and are highly recommended.
19 Index Data YUM repository (CentOS)
20 ----------------------------------
22 Yaz4j with it's runtime and compilation dependencies are provided through
23 Index Data's YUM repository, the repository is enabled by placing the following
27 name=Index Data Main Repository
28 baseurl=http://ftp.indexdata.com/pub/yum/centos/6/main/$basearch
29 failovermethod=priority
31 gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-indexdata
35 at `/etc/yum.repos.d/indexdata.repo`.
37 With the above repository enabled, yaz4j can be simply installed with:
41 And the installation can be verified by running a provided test program which
42 executes a search against a public Index Data z3950 test server:
44 java -jar /usr/share/java/yaz4j.jar
47 YAZ Installer (Windows)
48 -----------------------
50 YAZ Windows installer can be downloaded from [here][4]. Yaz4j is bundled with
51 the installer: just make sure during the installation yaz4j box is checked.
52 It is also recommended to check the box for updating updating PATH environment
53 variable with a path to yaz binaries. After installation yaz4j can be tested
54 with (Java runtime environment required):
56 java -jar C:\Program Files\YAZ\java\yaz4j.jar
58 All native libraries and binaries are located in `C:\Program Files\YAZ\bin\`
61 COMPILATION FROM SOURCE
62 =======================
64 Checking out the source code
65 ----------------------------
67 Yaz4j can be checked out from Index Data's Git repository:
69 git clone git://git.indexdata.com/yaz4j
71 It's recommended to build the latest tagged version (see tags with `git tag`),
74 git checkout v1.5 -b v1.5
80 Compilation requires [JDK][1], [Maven][2], [Swig][3] and [YAZ][4] development
83 Installing build dependencies can be done through the package manager specific
84 for the distribution (subject to availability), for CentOS 5/6 (YUM) JDK and Swig RPMs can be installed with:
86 yum install java-1.7.0-openjdk-devel swig
88 While YAZ development package needs to be installed from Index Data's YUM
89 repository (see INSTALLATION on how to enable the YUM repo):
91 yum install libyaz5-devel
93 Maven is not part of CentOS so a binary distribution needs to be downloaded
94 from Maven [website][2] and installed manually. Refer to Maven's website for
95 details. In case Index Data's YUM repo is enabled, Maven 3 can also be
98 yum install maven3-indexdata
100 in which case Maven program is called `mvn-id` rather than `mvn`.
102 With all dependencies in place you can continue the yaz4j compilation with:
107 Which will also run tests that open a connection to Index Data's public z3950
110 Notice that `yaz-config` binary must be on the PATH (this is assured when
111 `libyaz5-devel` package is installed), if it isn't e.g if a local YAZ (source)
112 installation is used, the binary location can be specified with:
114 mvn -Dyaz.config=/path/to/yaz-config install
116 The compiled jar file ends up in any/target/yaz4j.jar while the native library
117 in unix/target/libyaz4j.so.
122 Besides the exact same requirements as in the Unix case (JDK, Maven, Swig, YAZ), you will need the Windows [SDK][5] installed (which in turn requires .NET
123 Framework 4) to compile yaz4j. Again it's much easier to use the
124 YAZ Installer. Git must be installed to checkout yaz4j source code.
126 Use the command prompt provided with the Windows SDK, navigate to the yaz4j
127 source directory and run:
131 Default 64-bit YAZ installer location is assumed for the 'yaz.path' property.
132 Nothing is assumed for 'swig', so you either need to specify an absolute path
133 or update the PATH environment to include the directory containing swig.exe.
134 Both can be specified with:
136 mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install
138 YAZ4J AND A SERVLET CONTAINER
139 =============================
141 If you are coding a web application that uses yaz4j there's a couple of things
142 to keep in mind. First, you are not invoking the JVM directly, but the servlet
143 container (e.g Tomcat) run/init script is doing that for you and that's the place
144 to configure any environment settings (e.g the PATH). Second, yaz4j includes
145 static initializers to load the native part and can't be packaged along with the
146 webapp as that would break on consecutive redeployments. It must be deployed to
147 the servlet container common classloader similar to JDBC drivers.
149 For convenience, `yaz4j-tomcat6` RPM is provided in the ID's YUM repo which will
150 set up the default RPM-provided Tomcat 6 with yaz4j automatically:
152 sudo yum install yaz4j-tomcat6
157 In case when yaz4j is installed through the RPM (Index Data's YUM repo) the
158 native libraries are placed in the standard system locations (/usr/lib/.. etc)
159 and are readily available to all applications, including Tomcat. The only other
160 thing to configure is to add yaz4j.jar (the pure Java component) to Tomcat's
161 common class loader (further down).
163 In case when yaz4j is built from source or for some other reason the native
164 pars are not present in the standard system library locations, they need to be
165 placed on the servlet container's shared libraries load path. One way
166 to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is
167 by editing (create it if it does not exist) the CATALINA_HOME/bin/setenv.sh`
168 script and putting the following lines in there:
170 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so
171 export LD_LIBRARY_PATH
173 Notice, that this has to be done for all native libraries that `yaz4j.so`
174 dependson, e.g `libyaz5.so` and so on, unless they are already on the default s
175 ystem library paths (e.g when installed from RPMs).
177 If Tomcat is started by a custom init scripts similar operation needs to be
180 The pure Java yaz4j.jar must be added to Tomcat's common classloader so that
181 it becomes available to all deployed webapps and is loaded only once. There
182 are a couple ways to do that.
184 One (employed by `yaz4j-tomcat6` RPM) is to place (or symlink) `yaz4j.jar` to
185 to `$CATALINA_BASE/lib` (CATALINA_BASE is `/usr/share/tomcat6` when Tomcat was
186 installed from RPMs on CentOS):
188 ln -s /path/to/yaz4j.jar /usr/share/tomcat6/lib
192 Another option is to edit the file `catalina.properties` shipped with Tomcat
193 (and located in `CATALINA_BASE/conf/` e.g `/etc/tomcat6/`on RPM-packaged Tomcat)
194 and extend the `common.loader=` property with the following:
196 common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,/path/to/yaz4j.jar
198 again restarting Tomcat afterwards.
200 Please consult Tomcat documentation for more information on [classloading][6].
205 On Windows Tomcat will most likely be run from the binary distribution which
206 includes `CATALINA_BASE/bin/setenv.sh` for the purpose of setting up the
207 environment. Unless, you have installed yaz4j.dll with the YAZ Installer and
208 checked the option to update the global PATH and include all native YAZ and y
209 az4j components, edit setenv.sh with the following:
211 set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll
213 The `X:\path\to\yaz\bin` is `C:\Program Files\YAZ\bin` when the installer was
214 used and includes also yaz4j.dll.
216 In case Tomcat is start up does not execute `setenv.sh`, e.g when custom startup
217 script is used, please include similar steps there.
219 To deploy `yaz4j.jar` you must follow steps identical to those from the Linux
220 section. Again, when installer is used `yaz4j.jar` is located at `C:\Program Files\YAZ\java\yaz4j.jar`.
223 PREPARING A DEVELOPMENT ENVIRONMENT
224 ===================================
229 If you are using maven to build your application you can include Index Data's
230 Maven repo location and include yaz4j dependency in your project:
234 <groupId>org.yaz4j</groupId>
235 <artifactId>yaz4j-any</artifactId>
236 <version>VERSION</version>
237 <scope>provided</scope>
241 It's crucial that the scope of this dependency is set to `provided` for web
242 application type projecets, otherwise the library would end up packaged in
243 the .war archive and we wouldn't want that.
245 Yaz4j includes a trivial HTTP to z3590 gateway under `examples/zgate` that shows
246 best how to use yaz4j in a servlet. There's also a blog entry on building the
253 The following is most probably already outdated, consult Google.
255 [1]: http://www.oracle.com/technetwork/java/javase/downloads/index.html "JDK"
257 [2]: http://maven.apache.org/download.cgi "Maven"
259 [3]: http://www.swig.org/download.html "Swig"
261 [4]: http://www.indexdata.com/yaz "YAZ"
263 [5]: http://www.microsoft.com/en-us/download/details.aspx?id=8279 "Windows SDK"
265 [6]: https://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html "Tomcat 6 class loading"
267 [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"