X-Git-Url: http://git.indexdata.com/?p=yaz4j-moved-to-github.git;a=blobdiff_plain;f=README.md;h=286ce4bc09ff6d0b0c22559c01159e93da849b7c;hp=d69343c12bf71ff76f9bb0d0b93390b8b454e6b3;hb=HEAD;hpb=2884f869e0648de01377eaeff2f9647511626837 diff --git a/README.md b/README.md index d69343c..286ce4b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,12 @@ +% Developing with yaz4j +% Index Data +% 2015-05-26 + + + INTRODUCTION ============ @@ -13,7 +22,7 @@ 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. @@ -33,14 +42,16 @@ contents: 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 @@ -48,16 +59,25 @@ executes a search against a public Index Data Z39.50 test server: 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 ======================= @@ -82,12 +102,12 @@ Compilation requires [JDK][1], [Maven][2], [Swig][3] and [YAZ][4] development 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 @@ -98,7 +118,7 @@ installed with: 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: @@ -108,26 +128,27 @@ 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 @@ -144,51 +165,57 @@ source directory and run: 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. @@ -198,7 +225,7 @@ it becomes available to all deployed webapps and is loaded only once. 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 @@ -220,27 +247,29 @@ Windows 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 @@ -252,6 +281,8 @@ If successful you can run the application with a URL as follows: [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 =================================== @@ -259,8 +290,17 @@ Maven ----- 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 `` in pom.xml): + + id-maven-repo + Indexdata Maven Repository + http://maven.indexdata.com/ + + +Yaz4j API dependency (put under `` in pom.xml): org.yaz4j @@ -271,7 +311,7 @@ Maven repo location and include yaz4j dependency in your project: 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 @@ -279,11 +319,6 @@ best how to use yaz4j in a servlet. There's also a blog entry on building the 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" @@ -297,3 +332,9 @@ The following is most probably already outdated, consult Google. [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"