1 % Developing with yaz4j
6 Generate standalone HTML with:
7 pandoc -s -o dev-with-yaz4j.html README.md
13 Yaz4j is a Java binding for the high-level, client-side portion of the YAZ
14 toolkit known as the ZOOM API. With Yaz4j you can program clients for YAZ-
15 supported protocols like Z39.50, SRU/W and Solr. Yaz4j includes a native
16 component and supports Windows, Linux and OSX.
18 Yaz4j is covered by the [Revised BSD](http://www.indexdata.com/licences/revised-bsd) license. That should be same as the the [BSD 3 Clause License](http://opensource.org/licenses/BSD-3-Clause).
23 Index Data provides ready to use yaz4j RPMs for CentOS 5 and 6, available from
24 our public YUM repository. On Windows yaz4j can be installed with the YAZ
25 installer. Those methods are the simplest ways to get yaz4j up and running
26 on the particular platforms and are highly recommended.
29 Index Data YUM repository (CentOS)
30 ----------------------------------
32 Yaz4j with it's runtime and compilation dependencies are provided through
33 Index Data's YUM repository, the repository is enabled by placing the following
37 name=Index Data Main Repository
38 baseurl=http://ftp.indexdata.com/pub/yum/centos/6/main/$basearch
39 failovermethod=priority
41 gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-indexdata
45 under `/etc/yum.repos.d/indexdata.repo` and import the package signing key with:
47 rpm --import http://ftp.indexdata.com/pub/yum/centos/6/RPM-GPG-KEY-indexdata
49 With the above repository enabled, yaz4j can be simply installed with:
53 The installation can be verified by running a provided command-line test
54 program, which executes a search against a public Index Data Z39.50 test server:
56 java -jar /usr/share/java/yaz4j.jar
59 YAZ Installer (Windows)
60 -----------------------
62 YAZ Windows installer can be downloaded for [64-bit][9] and [32-bit][10]
63 Windows systems. Make sure you choose your architecture correctly and install
64 the latest available version for your system.
66 Yaz4j is bundled with the installer: just make sure that during the
67 installation yaz4j box is checked.
69 It is also recommended to check the box for updating the `PATH` environment
70 variable with a path to yaz binaries and DLLs.
72 After installation yaz4j can be tested with (Java runtime environment be [installed][1] separately):
74 java -jar C:\Program Files\YAZ\java\yaz4j.jar
76 All native libraries and binaries are installed to `C:\Program Files\YAZ\bin\`
77 while the `yaz4j.jar` is installed to `C:\Program Files\YAZ\java`.
79 `C:\Program Files\YAZ\` is the default YAZ location on a 64-bit Windows and
80 it is assumed for `yaz-path` in the yaz4j build process.
82 COMPILATION FROM SOURCE
83 =======================
85 Checking out the source code
86 ----------------------------
88 Yaz4j can be checked out from Index Data's Git repository:
90 git clone git://git.indexdata.com/yaz4j
92 It's recommended to build the latest tagged version (see tags with `git tag`),
95 git checkout v1.5 -b v1.5
98 Compilation on CentOS/RHEL
99 --------------------------
101 Compilation requires [JDK][1], [Maven][2], [Swig][3] and [YAZ][4] development
104 Installing build dependencies can be done through the package manager specific
105 for the distribution (subject to availability). For CentOS 5/6 (YUM) JDK and Swig RPMs can be installed with:
107 yum install java-1.7.0-openjdk-devel swig
109 YAZ development package needs to be installed from Index Data's YUM
110 repository (see the INSTALLATION section on how to enable the YUM repo):
112 yum install libyaz5-devel
114 Maven is not part of CentOS so a binary distribution needs to be downloaded
115 from Maven [website][2] and installed manually. Refer to Maven's website for
116 details. In case Index Data's YUM repo is enabled, Maven 3 can also be
119 yum install maven3-indexdata
121 in which case the Maven program is called `mvn-id` rather than `mvn`.
123 With all dependencies in place you can continue the yaz4j compilation with:
128 Which will also run tests that open a connection to Index Data's public Z39.50
131 Notice that `yaz-config` binary must be on the `PATH` (this is assured when
132 `libyaz5-devel` package is installed), if it isn't e.g if a local YAZ (source)
133 installation is used, the binary location can be specified with:
135 mvn -Dyaz.config=/path/to/yaz-config install
137 The compiled jar file ends up in `any/target/yaz4j.jar` while the native library
138 in `unix/target/libyaz4j.so`.
140 Compilation on generic Unix
141 ---------------------------
143 You will need the JDK, Maven, Swig and YAZ development packages.
144 Consult your package manager on how to install those. For compilation
145 of YAZ please consult YAZ [manual][8].
147 If yaz-config is in your `PATH`, the following command should suffice:
151 If yaz-config is not in your `PATH`, you'll have to tell where YAZ is located:
153 mvn -Dyaz.config=/path/to/yaz-config install
158 Besides the exact same requirements as in the Unix case (JDK, Maven, Swig,
159 YAZ), you will need the Windows [SDK][5] installed (which in turn requires
160 .NET Framework 4) to compile yaz4j. Again it's much easier to use the
161 YAZ Installer. Git must be installed to checkout yaz4j source code.
163 Use the command prompt provided with the Windows SDK, navigate to the yaz4j
164 source directory and run:
168 Default 64-bit YAZ installer location, that is`C:\Program Files\YAZ\`,
169 is assumed for the `yaz.path` property. Nothing is assumed for `swig`,
170 so you either need to specify an absolute path or update the `PATH`
171 environment variable to include the directory containing
172 `swig.exe`. Both can be specified with:
174 mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install
176 The compiled jar file ends up in `any/target/yaz4j.jar` while the native library
177 in `win32/target/libyaz4j.dll`.
180 YAZ4J AND A SERVLET CONTAINER
181 =============================
183 If you are coding a web application that uses yaz4j there's a couple of things
184 to keep in mind. First, you are not invoking the JVM directly, but the servlet
185 container (e.g Tomcat) run/init script is doing that for you and that's the
186 place to configure any environment settings (e.g the `PATH`). Second, yaz4j
187 includes static initializers to load the native part and can't be packaged
188 along with the webapp as that would break on consecutive redeployments. It must
189 be deployed to the servlet container common classloader, similarly to JDBC
192 For convenience, `yaz4j-tomcat6` RPM is provided in the ID's YUM repo which will
193 set up the default CentOS-provided Tomcat 6 with yaz4j automatically:
195 sudo yum install yaz4j-tomcat6
200 In the case when yaz4j is installed through the RPM (Index Data's YUM repo) the
201 native libraries are placed in the standard system locations (/usr/lib/.. etc)
202 and are readily available to all applications, including Tomcat. The only other
203 thing to configure is to add yaz4j.jar (the pure Java component) to Tomcat's
204 common class loader (further down).
206 In the case when yaz4j is built from source or for some other reason the native
207 parts are not present in the standard system library locations, they need to be
208 placed on the servlet container's shared libraries load path. One way
209 to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is
210 by editing (create it if it does not exist) the `CATALINA_HOME/bin/setenv.sh`
211 script and putting the following lines in there:
213 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so
214 export LD_LIBRARY_PATH
216 Notice, that this has to be done for all native libraries that `yaz4j.so`
217 depends on, e.g `libyaz5.so` and so on, unless they are already on the default
218 system library paths (e.g when installed from RPMs).
220 If Tomcat is started by a custom init scripts similar operation needs to be
223 The pure Java yaz4j.jar must be added to Tomcat's common classloader so that
224 it becomes available to all deployed webapps and is loaded only once. There
225 are a couple ways to do that.
227 One (employed by `yaz4j-tomcat6` RPM) is to place (or symlink) `yaz4j.jar` to
228 to `CATALINA_BASE/lib` (`CATALINA_BASE` is `/usr/share/tomcat6` when Tomcat is
229 installed from RPMs on CentOS):
231 ln -s /path/to/yaz4j.jar /usr/share/tomcat6/lib
235 Another option is to edit the file `catalina.properties` shipped with Tomcat
236 (and located in `CATALINA_BASE/conf/` e.g `/etc/tomcat6/`on RPM-packaged Tomcat)
237 and extend the `common.loader=` property with the following:
239 common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,/path/to/yaz4j.jar
241 again restarting Tomcat afterwards.
243 Please consult Tomcat documentation for more information on [classloading][6].
248 On Windows Tomcat will most likely be run from the binary distribution which
249 includes `CATALINA_BASE/bin/setenv.bat` for the purpose of setting up the
250 environment. Unless, you have installed yaz4j.dll through the YAZ Installer and
251 checked the option to update the global `PATH` and include all native YAZ and
252 yaz4j components or you have set up the global `PATH` on your own, edit
253 `setenv.bat` with the following:
255 set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll
257 The `X:\path\to\yaz\bin` is `C:\Program Files\YAZ\bin` when the installer was
258 used and includes also yaz4j.dll.
260 In case Tomcat start up does not execute `setenv.sh`, e.g when custom startup
261 script is used, please include similar steps there.
263 To deploy `yaz4j.jar` you must edit `catalina.properties` files, see the Linux
264 section for details. Again, when the YAZ installer is used `yaz4j.jar` is
265 located at `C:\Program Files\YAZ\java\yaz4j.jar` by default.
271 Under `yaz4j/examples` you'll find a small webapp called `zgate`. This can be
272 deployed to Tomcat to test the yaz4j installation. To do so:
274 cd yaz4j/examples/zgate
276 cp target/zgate.war CATALINA_BASE/webapps
278 (substitute / with \\ and copy as necessary under Windows!)
280 If successful you can run the application with a URL as follows:
282 [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)
284 You should see results from the Index Data's test z3950 server.
286 PREPARING A DEVELOPMENT ENVIRONMENT
287 ===================================
292 If you are using maven to build your application you can include Index Data's
293 maven repository and include yaz4j as a dependency in your jar or war project:
295 Index Data's Maven repository (put under `<repositories/>` in pom.xml):
298 <id>id-maven-repo</id>
299 <name>Indexdata Maven Repository</name>
300 <url>http://maven.indexdata.com/</url>
303 Yaz4j API dependency (put under `<dependencies/>` in pom.xml):
306 <groupId>org.yaz4j</groupId>
307 <artifactId>yaz4j-any</artifactId>
308 <version>VERSION</version>
309 <scope>provided</scope>
313 It's crucial that the scope of this dependency is set to `provided` for web
314 application type projects, otherwise the library would end up packaged in
315 the .war archive and we wouldn't want that.
317 Yaz4j includes a trivial HTTP to z3590 gateway under `examples/zgate` that shows
318 best how to use yaz4j in a servlet. There's also a blog entry on building the
322 [1]: http://www.oracle.com/technetwork/java/javase/downloads/index.html "JDK"
324 [2]: http://maven.apache.org/download.cgi "Maven"
326 [3]: http://www.swig.org/download.html "Swig"
328 [4]: http://www.indexdata.com/yaz "YAZ"
330 [5]: http://www.microsoft.com/en-us/download/details.aspx?id=8279 "Windows SDK"
332 [6]: https://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html "Tomcat 6 class loading"
334 [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"
336 [8]: http://www.indexdata.com/yaz/doc/installation.html "YAZ Compilation"
338 [9]: http://ftp.indexdata.dk/pub/yaz/win64/ "YAZ Installer 64-bit"
340 [10]: http://ftp.indexdata.dk/pub/yaz/win32/ "YAZ Installer 32-bit"