doc/README.md

   1 INTRODUCTION
   2 ============
   3
   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.
   8
   9
  10 INSTALLATION
  11 ============
  12
  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.
  17
  18
  19 Index Data YUM repository (CentOS)
  20 ----------------------------------
  21
  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
  24 contents:
  25
  26     [indexdata-main]
  27     name=Index Data Main Repository
  28     baseurl=http://ftp.indexdata.com/pub/yum/centos/6/main/$basearch
  29     failovermethod=priority
  30     gpgcheck=1
  31     gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-indexdata
  32     enabled=1
  33     priority=1
  34
  35 at `/etc/yum.repos.d/indexdata.repo`.
  36
  37 With the above repository enabled, yaz4j can be simply installed with:
  38
  39     yum install yaz4j
  40
  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:
  43
  44     java -jar /usr/share/java/yaz4j.jar
  45
  46
  47 YAZ Installer (Windows)
  48 -----------------------
  49
  50 YAZ Windows installer can be downloaded from [here][2]. 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):
  55
  56   java -jar C:\Program Files\YAZ\java\yaz4j.jar
  57
  58
  59 COMPILATION FROM SOURCE
  60 =======================
  61
  62 Checking out the source code
  63 ----------------------------
  64
  65 Yaz4j can be checked out from Index Data's Git repository:
  66
  67     git clone git://git.indexdata.com/yaz4j
  68
  69 It's recommended to build the latest tagged version (see tags with `git tag`),
  70 e.g:
  71
  72     git checkout v1.5 -b v1.5
  73
  74
  75 Linux (e.g CentOS)
  76 ------------------
  77
  78 Compilation requires [JDK][1], [Maven][2], [Swig][3] and [YAZ][4] development
  79 packages installed.
  80
  81 Installing build dependencies can be done through the package manager specific
  82 for the distribution (subject to availability), for CentOS 5/6 (YUM) JDK and Swig RPMs can be installed  with:
  83
  84     yum install java-1.7.0-openjdk-devel swig
  85
  86 While YAZ development package needs to be installed from Index Data's YUM
  87 repository (see INSTALLATION on how to enable the YUM repo):
  88
  89     yum install libyaz5-devel
  90
  91 Maven is not part of CentOS so a binary distribution needs to be downloaded
  92 from Maven [website][2] and installed manually. Refer to Maven's website for
  93 details. In case Index Data's YUM repo is enabled, Maven 3 can also be
  94 installed with:
  95
  96     yum install maven3-indexdata
  97
  98 in which case Maven program is called `mvn-id` rather than `mvn`.
  99
 100 With all dependencies in place you can continue the yaz4j compilation with:
 101
 102     cd yaz4j
 103     mvn install
 104
 105 Which will also run tests that open a connection to Index Data's public z3950
 106 server.
 107
 108 Notice that `yaz-config` binary must be on the PATH (this is assured when
 109 `libyaz5-devel` package is installed), if it isn't e.g if a local YAZ (source)
 110 installation is used, the binary location can be specified with:
 111
 112     mvn -Dyaz.config=/path/to/yaz-config install
 113
 114 The compiled jar file ends up in any/target/yaz4j.jar while the native library
 115 in unix/target/libyaz4j.so.
 116
 117 Windows
 118 -------
 119
 120 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
 121 Framework 4) to compile yaz4j. Again it's much easier to use the
 122 YAZ Installer. Git must be installed to checkout yaz4j source code.
 123
 124 Use the command prompt provided with the Windows SDK, navigate to the yaz4j
 125 source directory and run:
 126
 127     mvn install
 128
 129 Default 64-bit YAZ installer location is assumed for the 'yaz.path' property.
 130 Nothing is assumed for 'swig', so you either need to specify an absolute path
 131 or update the PATH environment to include the directory containing swig.exe.
 132 Both can be specified with:
 133
 134     mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install
 135
 136 YAZ4J AND A SERVLET CONTAINER
 137 =============================
 138
 139
 140 PREPARING A DEVELOPMENT ENVIRONMENT
 141 ===================================
 142
 143 LINKS
 144 =====
 145
 146 The following is most probably already outdated, consult Google.
 147
 148 [1]: http://www.oracle.com/technetwork/java/javase/downloads/index.html "JDK"
 149
 150 [2]: http://maven.apache.org/download.cgi "Maven"
 151
 152 [3]: http://www.swig.org/download.html "Swig"
 153
 154 [4]: http://www.indexdata.com/yaz "YAZ"
 155
 156 [5]: http://www.microsoft.com/en-us/download/details.aspx?id=8279 "Windows SDK"