+% Developing with yaz4j
+% Index Data
+% 2015-05-26
+
+<!---
+ Generate standalone HTML with:
+ pandoc -s -o dev-with-yaz4j.html README.md
+-->
+
INTRODUCTION
============
supported protocols like Z39.50, SRU/W and Solr. Yaz4j includes a native
component and supports Windows, Linux and OSX.
+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).
+
INSTALLATION
============
Index Data provides ready to use yaz4j RPMs for CentOS 5 and 6, available from
our public YUM repository. On Windows yaz4j can be installed with the YAZ
-[installer][4]. Those methods are the simplest ways to get yaz4j up and running
+installer. Those methods are the simplest ways to get yaz4j up and running
on the particular platforms and are highly recommended.
enabled=1
priority=1
-at `/etc/yum.repos.d/indexdata.repo`.
+under `/etc/yum.repos.d/indexdata.repo` and import the package signing key with:
+
+ rpm --import http://ftp.indexdata.com/pub/yum/centos/6/RPM-GPG-KEY-indexdata
With the above repository enabled, yaz4j can be simply installed with:
yum install yaz4j
-And the installation can be verified by running a provided test program which
-executes a search against a public Index Data Z39.50 test server:
+The installation can be verified by running a provided command-line test
+program, which executes a search against a public Index Data Z39.50 test server:
java -jar /usr/share/java/yaz4j.jar
YAZ Installer (Windows)
-----------------------
-YAZ Windows installer can be downloaded from [here][4]. Yaz4j is bundled with
-the installer: just make sure during the installation yaz4j box is checked.
-It is also recommended to check the box for updating updating PATH environment
-variable with a path to yaz binaries. After installation yaz4j can be tested
-with (Java runtime environment required):
+YAZ Windows installer can be downloaded for [64-bit][9] and [32-bit][10]
+Windows systems. Make sure you choose your architecture correctly and install
+the latest available version for your system.
+
+Yaz4j is bundled with the installer: just make sure that during the
+installation yaz4j box is checked.
+
+It is also recommended to check the box for updating the `PATH` environment
+variable with a path to yaz binaries and DLLs.
+
+After installation yaz4j can be tested with (Java runtime environment be [installed][1] separately):
java -jar C:\Program Files\YAZ\java\yaz4j.jar
-All native libraries and binaries are located in `C:\Program Files\YAZ\bin\`
-after installation.
+All native libraries and binaries are installed to `C:\Program Files\YAZ\bin\`
+while the `yaz4j.jar` is installed to `C:\Program Files\YAZ\java`.
+
+`C:\Program Files\YAZ\` is the default YAZ location on a 64-bit Windows and
+it is assumed for `yaz-path` in the yaz4j build process.
COMPILATION FROM SOURCE
=======================
packages installed.
Installing build dependencies can be done through the package manager specific
-for the distribution (subject to availability), for CentOS 5/6 (YUM) JDK and Swig RPMs can be installed with:
+for the distribution (subject to availability). For CentOS 5/6 (YUM) JDK and Swig RPMs can be installed with:
yum install java-1.7.0-openjdk-devel swig
-While YAZ development package needs to be installed from Index Data's YUM
-repository (see INSTALLATION on how to enable the YUM repo):
+YAZ development package needs to be installed from Index Data's YUM
+repository (see the INSTALLATION section on how to enable the YUM repo):
yum install libyaz5-devel
yum install maven3-indexdata
-in which case Maven program is called `mvn-id` rather than `mvn`.
+in which case the Maven program is called `mvn-id` rather than `mvn`.
With all dependencies in place you can continue the yaz4j compilation with:
Which will also run tests that open a connection to Index Data's public Z39.50
server.
-Notice that `yaz-config` binary must be on the PATH (this is assured when
+Notice that `yaz-config` binary must be on the `PATH` (this is assured when
`libyaz5-devel` package is installed), if it isn't e.g if a local YAZ (source)
installation is used, the binary location can be specified with:
mvn -Dyaz.config=/path/to/yaz-config install
-The compiled jar file ends up in any/target/yaz4j.jar while the native library
-in unix/target/libyaz4j.so.
+The compiled jar file ends up in `any/target/yaz4j.jar` while the native library
+in `unix/target/libyaz4j.so`.
Compilation on generic Unix
---------------------------
You will need the JDK, Maven, Swig and YAZ development packages.
-Consult your package manager on how to install those.
+Consult your package manager on how to install those. For compilation
+of YAZ please consult YAZ [manual][8].
-If yaz-config is in your PATH, the following command should suffice:
+If yaz-config is in your `PATH`, the following command should suffice:
mvn install
-If yaz-config is not in your PATH, you'll have to tell where YAZ is located:
+If yaz-config is not in your `PATH`, you'll have to tell where YAZ is located:
mvn -Dyaz.config=/path/to/yaz-config install
mvn install
-Default 64-bit YAZ installer location is assumed for the 'yaz.path' property.
-Nothing is assumed for 'swig', so you either need to specify an absolute path
-or update the PATH environment to include the directory containing swig.exe.
-Both can be specified with:
+Default 64-bit YAZ installer location, that is`C:\Program Files\YAZ\`,
+is assumed for the `yaz.path` property. Nothing is assumed for `swig`,
+so you either need to specify an absolute path or update the `PATH`
+environment variable to include the directory containing
+`swig.exe`. Both can be specified with:
mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install
+The compiled jar file ends up in `any/target/yaz4j.jar` while the native library
+in `win32/target/libyaz4j.dll`.
+
+
YAZ4J AND A SERVLET CONTAINER
=============================
If you are coding a web application that uses yaz4j there's a couple of things
to keep in mind. First, you are not invoking the JVM directly, but the servlet
-container (e.g Tomcat) run/init script is doing that for you and that's the place
-to configure any environment settings (e.g the PATH). Second, yaz4j includes
-static initializers to load the native part and can't be packaged along with the
-webapp as that would break on consecutive redeployments. It must be deployed to
-the servlet container common classloader similar to JDBC drivers.
+container (e.g Tomcat) run/init script is doing that for you and that's the
+place to configure any environment settings (e.g the `PATH`). Second, yaz4j
+includes static initializers to load the native part and can't be packaged
+along with the webapp as that would break on consecutive redeployments. It must
+be deployed to the servlet container common classloader, similarly to JDBC
+drivers.
For convenience, `yaz4j-tomcat6` RPM is provided in the ID's YUM repo which will
-set up the default RPM-provided Tomcat 6 with yaz4j automatically:
+set up the default CentOS-provided Tomcat 6 with yaz4j automatically:
sudo yum install yaz4j-tomcat6
Linux (CentOS)
--------------
-In case when yaz4j is installed through the RPM (Index Data's YUM repo) the
+In the case when yaz4j is installed through the RPM (Index Data's YUM repo) the
native libraries are placed in the standard system locations (/usr/lib/.. etc)
and are readily available to all applications, including Tomcat. The only other
thing to configure is to add yaz4j.jar (the pure Java component) to Tomcat's
common class loader (further down).
-In case when yaz4j is built from source or for some other reason the native
-pars are not present in the standard system library locations, they need to be
-placed on the servlet container's shared libraries load path. One way
+In the case when yaz4j is built from source or for some other reason the native
+parts are not present in the standard system library locations, they need to be
+placed on the servlet container's shared libraries load path. One way
to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is
-by editing (create it if it does not exist) the CATALINA_HOME/bin/setenv.sh`
+by editing (create it if it does not exist) the `CATALINA_HOME/bin/setenv.sh`
script and putting the following lines in there:
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so
export LD_LIBRARY_PATH
Notice, that this has to be done for all native libraries that `yaz4j.so`
-dependson, e.g `libyaz5.so` and so on, unless they are already on the default s
-ystem library paths (e.g when installed from RPMs).
+depends on, e.g `libyaz5.so` and so on, unless they are already on the default
+system library paths (e.g when installed from RPMs).
If Tomcat is started by a custom init scripts similar operation needs to be
performed there.
are a couple ways to do that.
One (employed by `yaz4j-tomcat6` RPM) is to place (or symlink) `yaz4j.jar` to
-to `$CATALINA_BASE/lib` (CATALINA_BASE is `/usr/share/tomcat6` when Tomcat was
+to `CATALINA_BASE/lib` (`CATALINA_BASE` is `/usr/share/tomcat6` when Tomcat is
installed from RPMs on CentOS):
ln -s /path/to/yaz4j.jar /usr/share/tomcat6/lib
On Windows Tomcat will most likely be run from the binary distribution which
includes `CATALINA_BASE/bin/setenv.bat` for the purpose of setting up the
-environment. Unless, you have installed yaz4j.dll with the YAZ Installer and
-checked the option to update the global PATH and include all native YAZ and
-yaz4j components, edit setenv.bat with the following:
+environment. Unless, you have installed yaz4j.dll through the YAZ Installer and
+checked the option to update the global `PATH` and include all native YAZ and
+yaz4j components or you have set up the global `PATH` on your own, edit
+`setenv.bat` with the following:
set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll
The `X:\path\to\yaz\bin` is `C:\Program Files\YAZ\bin` when the installer was
used and includes also yaz4j.dll.
-In case Tomcat is start up does not execute `setenv.sh`, e.g when custom startup
+In case Tomcat start up does not execute `setenv.sh`, e.g when custom startup
script is used, please include similar steps there.
-To deploy `yaz4j.jar` you must follow steps identical to those from the Linux
-section. Again, when installer is used `yaz4j.jar` is located at `C:\Program Files\YAZ\java\yaz4j.jar`.
+To deploy `yaz4j.jar` you must edit `catalina.properties` files, see the Linux
+section for details. Again, when the YAZ installer is used `yaz4j.jar` is
+located at `C:\Program Files\YAZ\java\yaz4j.jar` by default.
Deploy a test app
-----------------
-Under yaz4j/examples you'll find a small zgate app. This can be deployed
-to Tomcat to test the yaz4j installation. To do so:
+Under `yaz4j/examples` you'll find a small webapp called `zgate`. This can be
+deployed to Tomcat to test the yaz4j installation. To do so:
cd yaz4j/examples/zgate
mvn install
[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)
+You should see results from the Index Data's test z3950 server.
+
PREPARING A DEVELOPMENT ENVIRONMENT
===================================
-----
If you are using maven to build your application you can include Index Data's
-Maven repo location and include yaz4j dependency in your project:
+maven repository and include yaz4j as a dependency in your jar or war project:
+
+Index Data's Maven repository (put under `<repositories/>` in pom.xml):
+ <repository>
+ <id>id-maven-repo</id>
+ <name>Indexdata Maven Repository</name>
+ <url>http://maven.indexdata.com/</url>
+ </repository>
+
+Yaz4j API dependency (put under `<dependencies/>` in pom.xml):
<dependency>
<groupId>org.yaz4j</groupId>
It's crucial that the scope of this dependency is set to `provided` for web
-application type projecets, otherwise the library would end up packaged in
+application type projects, otherwise the library would end up packaged in
the .war archive and we wouldn't want that.
Yaz4j includes a trivial HTTP to z3590 gateway under `examples/zgate` that shows
gateway [here][7]
-LINKS
-=====
-
-The following is most probably already outdated, consult Google.
-
[1]: http://www.oracle.com/technetwork/java/javase/downloads/index.html "JDK"
[2]: http://maven.apache.org/download.cgi "Maven"
[6]: https://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html "Tomcat 6 class loading"
[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"
+
+[8]: http://www.indexdata.com/yaz/doc/installation.html "YAZ Compilation"
+
+[9]: http://ftp.indexdata.dk/pub/yaz/win64/ "YAZ Installer 64-bit"
+
+[10]: http://ftp.indexdata.dk/pub/yaz/win32/ "YAZ Installer 32-bit"
projects / yaz4j-moved-to-github.git / blobdiff