2517ac783d6723bd243623a24921ff20d8cf60f8
[yaz4j-moved-to-github.git] / 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 Z39.50, SRU/W and Solr. Yaz4j includes a native
7 component and supports Windows, Linux and OSX.
8
9 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).
10
11 INSTALLATION
12 ============
13
14 Index Data provides ready to use yaz4j RPMs for CentOS 5 and 6, available from
15 our public YUM repository. On Windows yaz4j can be installed with the YAZ
16 [installer][4]. Those methods are the simplest ways to get yaz4j up and running
17 on the particular platforms and are highly recommended.
18
19
20 Index Data YUM repository (CentOS)
21 ----------------------------------
22
23 Yaz4j with it's runtime and compilation dependencies are provided through
24 Index Data's YUM repository, the repository is enabled by placing the following
25 contents:
26
27     [indexdata-main]
28     name=Index Data Main Repository
29     baseurl=http://ftp.indexdata.com/pub/yum/centos/6/main/$basearch
30     failovermethod=priority
31     gpgcheck=1
32     gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-indexdata
33     enabled=1
34     priority=1
35
36 at `/etc/yum.repos.d/indexdata.repo`.
37
38 With the above repository enabled, yaz4j can be simply installed with:
39
40     yum install yaz4j
41
42 And the installation can be verified by running a provided test program which
43 executes a search against a public Index Data Z39.50 test server:
44
45     java -jar /usr/share/java/yaz4j.jar
46
47
48 YAZ Installer (Windows)
49 -----------------------
50
51 YAZ Windows installer can be downloaded from [here][4]. Yaz4j is bundled with
52 the installer: just make sure during the installation yaz4j box is checked. 
53 It is also recommended to check the box for updating updating PATH environment
54 variable with a path to yaz binaries. After installation yaz4j can be tested
55 with (Java runtime environment required):
56
57     java -jar C:\Program Files\YAZ\java\yaz4j.jar
58
59 All native libraries and binaries are located in `C:\Program Files\YAZ\bin\`
60 after installation.
61
62 COMPILATION FROM SOURCE
63 =======================
64
65 Checking out the source code
66 ----------------------------
67
68 Yaz4j can be checked out from Index Data's Git repository:
69
70     git clone git://git.indexdata.com/yaz4j
71
72 It's recommended to build the latest tagged version (see tags with `git tag`),
73 e.g:
74
75     git checkout v1.5 -b v1.5
76
77
78 Compilation on CentOS/RHEL
79 --------------------------
80
81 Compilation requires [JDK][1], [Maven][2], [Swig][3] and [YAZ][4] development 
82 packages installed.
83
84 Installing build dependencies can be done through the package manager specific 
85 for the distribution (subject to availability), for CentOS 5/6 (YUM) JDK and Swig RPMs can be installed  with:
86
87     yum install java-1.7.0-openjdk-devel swig
88
89 While YAZ development package needs to be installed from Index Data's YUM 
90 repository (see INSTALLATION on how to enable the YUM repo):
91
92     yum install libyaz5-devel
93
94 Maven is not part of CentOS so a binary distribution needs to be downloaded
95 from Maven [website][2] and installed manually. Refer to Maven's website for
96 details. In case Index Data's YUM repo is enabled, Maven 3 can also be 
97 installed with:
98
99     yum install maven3-indexdata
100
101 in which case Maven program is called `mvn-id` rather than `mvn`.
102
103 With all dependencies in place you can continue the yaz4j compilation with:
104
105     cd yaz4j
106     mvn install
107
108 Which will also run tests that open a connection to Index Data's public Z39.50
109 server.
110
111 Notice that `yaz-config` binary must be on the PATH (this is assured when 
112 `libyaz5-devel` package is installed), if it isn't e.g if a local YAZ (source) 
113 installation is used, the binary location can be specified with:
114
115     mvn -Dyaz.config=/path/to/yaz-config install
116
117 The compiled jar file ends up in any/target/yaz4j.jar while the native library
118 in unix/target/libyaz4j.so.
119
120 Compilation on generic Unix
121 ---------------------------
122
123 You will need the JDK, Maven, Swig and YAZ development packages.
124 Consult your package manager on how to install those.
125
126 If yaz-config is in your PATH, the following command should suffice:
127
128     mvn install
129
130 If yaz-config is not in your PATH, you'll have to tell where YAZ is located:
131
132     mvn -Dyaz.config=/path/to/yaz-config install
133
134 Windows
135 -------
136
137 Besides the exact same requirements as in the Unix case (JDK, Maven, Swig,
138 YAZ), you will need the Windows [SDK][5] installed (which in turn requires
139 .NET Framework 4) to compile yaz4j. Again it's much easier to use the
140 YAZ Installer. Git must be installed to checkout yaz4j source code.
141
142 Use the command prompt provided with the Windows SDK, navigate to the yaz4j
143 source directory and run:
144
145     mvn install
146
147 Default 64-bit YAZ installer location is assumed for the 'yaz.path' property.
148 Nothing is assumed for 'swig', so you either need to specify an absolute path
149 or update the PATH environment to include the directory containing swig.exe.
150 Both can be specified with:
151
152     mvn -Dyaz.path=/path/to/yaz/installdir -Dswig=/path/to/swig/binary install
153
154 YAZ4J AND A SERVLET CONTAINER
155 =============================
156
157 If you are coding a web application that uses yaz4j there's a couple of things
158 to keep in mind. First, you are not invoking the JVM directly, but the servlet
159 container (e.g Tomcat) run/init script is doing that for you and that's the place
160 to configure any environment settings (e.g the PATH). Second, yaz4j includes
161 static initializers to load the native part and can't be packaged along with the
162 webapp as that would break on consecutive redeployments. It must be deployed to
163 the servlet container common classloader similar to JDBC drivers.
164
165 For convenience, `yaz4j-tomcat6` RPM is provided in the ID's YUM repo which will
166 set up the default RPM-provided Tomcat 6 with yaz4j automatically:
167
168     sudo yum install yaz4j-tomcat6
169
170 Linux (CentOS)
171 --------------
172
173 In case when yaz4j is installed through the RPM (Index Data's YUM repo) the
174 native libraries are placed in the standard system locations (/usr/lib/.. etc)
175 and are readily available to all applications, including Tomcat. The only other
176 thing to configure is to add yaz4j.jar (the pure Java component) to Tomcat's
177 common class loader (further down).
178
179 In case when yaz4j is built from source or for some other reason the native
180 pars are not present in the standard system library locations, they need to be
181 placed on the servlet  container's shared libraries load path. One way
182 to do this in Tomcat (assuming Tomcat is run from a tarball rather than RPM) is
183 by editing  (create it if it does not exist) the CATALINA_HOME/bin/setenv.sh`
184 script and putting the following lines in there:
185
186     LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/libyaz4j.so
187     export LD_LIBRARY_PATH
188
189 Notice, that this has to be done for all native libraries that `yaz4j.so`
190 dependson, e.g `libyaz5.so` and so on, unless they are already on the default s
191 ystem library paths (e.g when installed from RPMs).
192
193 If Tomcat is started by a custom init scripts similar operation needs to be
194 performed there.
195
196 The pure Java yaz4j.jar must be added to Tomcat's common classloader so that
197 it becomes available to all deployed webapps and is loaded only once. There
198 are a couple ways to do that.
199
200 One (employed by `yaz4j-tomcat6` RPM) is to place (or symlink) `yaz4j.jar` to
201 to `$CATALINA_BASE/lib` (CATALINA_BASE is `/usr/share/tomcat6` when Tomcat was
202 installed from RPMs on CentOS):
203
204     ln -s /path/to/yaz4j.jar /usr/share/tomcat6/lib
205
206 and restart Tomcat.
207
208 Another option is to edit the file `catalina.properties` shipped with Tomcat
209 (and located in `CATALINA_BASE/conf/` e.g `/etc/tomcat6/`on RPM-packaged Tomcat)
210 and extend the `common.loader=` property with the following:
211
212     common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,/path/to/yaz4j.jar
213
214 again restarting Tomcat afterwards.
215
216 Please consult Tomcat documentation for more information on [classloading][6].
217
218 Windows
219 -------
220
221 On Windows Tomcat will most likely be run from the binary distribution which
222 includes `CATALINA_BASE/bin/setenv.bat` for the purpose of setting up the 
223 environment. Unless, you have installed yaz4j.dll with the YAZ Installer and 
224 checked the option to update the global PATH and include all native YAZ and
225 yaz4j components, edit setenv.bat with the following:
226
227     set PATH=%PATH;X:\path\to\yaz\bin;X:\path\to\yaz4j.dll
228
229 The `X:\path\to\yaz\bin` is `C:\Program Files\YAZ\bin` when the installer was
230 used and includes also yaz4j.dll.
231
232 In case Tomcat is start up does not execute `setenv.sh`, e.g when custom startup
233 script is used, please include similar steps there.
234
235 To deploy `yaz4j.jar` you must follow steps identical to those from the Linux 
236 section. Again, when installer is used `yaz4j.jar` is located at `C:\Program Files\YAZ\java\yaz4j.jar`.
237
238
239 Deploy a test app
240 -----------------
241
242 Under yaz4j/examples you'll find a small zgate app. This can be deployed
243 to Tomcat to test the yaz4j installation. To do so:
244
245     cd yaz4j/examples/zgate
246     mvn install
247     cp target/zgate.war CATALINA_BASE/webapps
248
249 (substitute / with \\ and copy as necessary under Windows!)
250
251 If successful you can run the application with a URL as follows:
252
253 [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)
254
255 PREPARING A DEVELOPMENT ENVIRONMENT
256 ===================================
257
258 Maven
259 -----
260
261 If you are using maven to build your application you can include Index Data's
262 maven repository and include yaz4j as a dependency in your jar or war project:
263
264 Index Data's Maven repository (put under `<repositories/>` in pom.xml):
265
266     <repository>
267       <id>id-maven-repo</id>
268       <name>Indexdata Maven Repository</name>
269       <url>http://maven.indexdata.com/</url>
270     </repository>
271
272 Yaz4j API dependency (put under `<dependencies/>` in pom.xml):
273
274     <dependency>
275       <groupId>org.yaz4j</groupId>
276       <artifactId>yaz4j-any</artifactId>
277       <version>VERSION</version>
278       <scope>provided</scope>
279     </dependency>
280
281
282 It's crucial that the scope of this dependency is set to `provided` for web
283 application type projecets, otherwise the library would end up packaged in 
284 the .war archive and we wouldn't want that.
285
286 Yaz4j includes a trivial HTTP to z3590 gateway under `examples/zgate` that shows
287 best how to use yaz4j in a servlet. There's also a blog entry on building the
288 gateway [here][7]
289
290
291 LINKS
292 =====
293
294 The following is most probably already outdated, consult Google.
295
296 [1]: http://www.oracle.com/technetwork/java/javase/downloads/index.html "JDK"
297
298 [2]: http://maven.apache.org/download.cgi "Maven"
299
300 [3]: http://www.swig.org/download.html "Swig"
301
302 [4]: http://www.indexdata.com/yaz "YAZ"
303
304 [5]: http://www.microsoft.com/en-us/download/details.aspx?id=8279 "Windows SDK"
305
306 [6]: https://tomcat.apache.org/tomcat-6.0-doc/class-loader-howto.html "Tomcat 6 class loading"
307
308 [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"