Java binding

Source Code

The Java binding requires a recent release of 0MQ, which you can download from the download area, or the latest development version, which you can download and build from the the github repository.

Build and installation

UNIX-like platforms

Get the jzmq source code by cloning the jzmq git or using github's download function, then do the following:

$ ./autogen.sh
$ ./configure
$ make
$ make install

On Linux you must run the ldconfig command as root after running make install to ensure that the system library cache is updated.

Make sure that you have set the Java classpath to the directory where ØMQ classes reside.

Finally, for Java to find the libzmq and libjzmq shared libraries you must ensure that java.library.path is set to the directory where these are installed (normally /usr/local/lib on UNIX-like systems).

Example command line for running a Java test program on Linux:

$ java -Djava.library.path=/usr/local/lib -classpath /home/user/zeromq/libjzmq local_lat tcp://127.0.0.1:5555 1 100

Fedora

Specific Fedora instructions from Steven McCoy on the mailing list:

Required packages:

    autoconf
    automake
    libtool
    gcc
    gcc-g++
    make
    libuuid-dev
    git
    java-1.6.0-openjdk-devel

1) Download and unpack ZeroMQ 2.1.10.

$ wget http://download.zeromq.org/zeromq-2.1.10.tar.gz
$ tar zxf zeromq-2.1.10.tar.gz

2) Build

$ cd zeromq-2.1.10
$ ./configure --with-pgm
$ make
$ sudo make install

Now libzmq.so should reside in /usr/local/lib

3) Clone JZMQ from GitHub.

$ git clone https://github.com/zeromq/jzmq.git

4) Build

$ cd jzmq
$ ./autogen.sh
$ ./configure
$ make
$ sudo make install

5) Setup environment

$ sudo bash

optional step #1 (not required on Debian platforms)

    # echo /usr/local/lib > /etc/ld.so.conf.d/local.conf
    # ldconfig

optional step #2

    # echo CLASSPATH=/usr/local/share/java/zmq.jar:. >> /etc/environment
    Incredibly limiting as you will still need to override to include any other directory or JAR file.

optional step #3

    # echo export LD_LIBRARY_PATH=/usr/local/lib > /etc/profile.d/ldlibrarypath.sh
    This is pretty much a workaround to a JRE defect:
    http://lists.fedoraproject.org/pipermail/java-devel/2011-March/004153.html
# exit

Then log out and log back in again.

6) Verify new environment

$ echo $CLASSPATH
/usr/local/share/java/zmq.jar:.
$ echo $LD_LIBRARY_PATH
/usr/local/lib

7) Test with Java ØMQ performance examples

$ cd jzmq/perf
$ java local_lat tcp://127.0.0.1:5000 1 100

This will fail if zmq.jar cannot be found in the class path.
This will fail if libjzmq.so or libzmq.so cannot be found in java.library.path or LD_LIBRARY_PATH.

If you skip optional step #1 you will need to specify the library path:

$ LD_LIBRARY_PATH=/usr/local/lib java local_lat tcp://127.0.0.1:5000 1 100

If you skip optional step #2 you will need to specify the class path:

$ java -cp /usr/local/share/java/zmq.jar:. local_lat tcp://127.0.0.1:5000 1 100

Note that setting -Djava.library.path is insufficient for libjzmq.so to find libzmq.so but it is sufficient if you take optional step #1 and skip optional step #3, i.e. LD_LIBRARY_PATH is not overridden but ld.so.conf is updated.

$ java -Djava.library.path=/usr/local/lib local_lat tcp://127.0.0.1:5000 1 100

Windows

Get the source code, then use MSVC (2008 or later) to open the solution file builds\msvc\msvc.sln and build the projects.

Ensure that the javac binary is in the Path variable.

Note that ØMQ and JDK header file has to be on "include path" (Tools|Options|Projects and Solutions|VC++ Directories|Include files) and ØMQ libraries have to be on "library path" (Tools|Options|Projects and Solutions|VC++ Directories|Library files):

Include files:
    <jdk>\include\win32
    <jdk>\include
    <zeromq>\include

Library files:
    <zeromq>\lib

To run it, firstly check whether libzmq.dll is on the system PATH. Secondly, make sure that you add zmq.jar and the jzmq perf directory to the Java classpath. Thirdly, for Java to find the jzmq.dll shared library you must ensure that java.library.path is set to the directory where it is installed.

Example command to run Java test program on Windows:

C:\zmq\java\perf> set PATH=%PATH%;C:\zmq\lib
C:\zmq\java\perf> java -Djava.library.path=C:\zmq\java\lib -classpath C:\zmq\java\lib\zmq.jar;. local_lat tcp://127.0.0.1:5555 1 100

Windows 64bit Build Instructions

Alternative Windows instructions from Steven McCoy on the mailing list:

1) Build ZeroMQ or install a prepared package. I built with SDK 7.1 but I also have MSVC 2010 Express and Pro installed.

2) Clone JZMQ from GitHub, might be easier with Cygwin.

$ git clone https://github.com/zeromq/jzmq.git

3) Insert attached CMakeLists.txt, you probably want to install CMake for Windows too.

4) With a suitable JDK installed prepare the build:

c:\zeromq\jzmq\jzmq> mkdir build64

c:\zeromq\jzmq\jzmq> cd build64

c:\zeromq\jzmq\jzmq> cmake .. -G "NMake Makefiles"
-- The C compiler identification is MSVC
-- The CXX compiler identification is MSVC
-- Check for CL compiler version
-- Check for CL compiler version - 1600
-- Check if this is a free VC compiler
-- Check if this is a free VC compiler - no
-- Check for working C compiler: c:/Program Files (x86)/Microsoft Visual Studio10.0/VC/bin/amd64/cl.exe
-- Check for working C compiler: c:/Program Files (x86)/Microsoft Visual Studio10.0/VC/bin/amd64/cl.exe -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working CXX compiler: c:/Program Files (x86)/Microsoft Visual Studio 10.0/VC/bin/amd64/cl.exe
-- Check for working CXX compiler: c:/Program Files (x86)/Microsoft Visual Studio 10.0/VC/bin/amd64/cl.exe -- works
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Java version 1.6.0.27 configured successfully!
-- Found Java: C:/Program Files/Java/jdk1.6.0_27/bin/java.exe (found version "1.6.0.27")
-- Found JNI: C:/Program Files/Java/jdk1.6.0_27/lib/jawt.lib
-- Configuring done
-- Generating done
-- Build files have been written to: C:/zeromq/jzmq/jzmq/build64

c:\zeromq\jzmq\jzmq> cmake-gui .

Change "Debug" to "Release", hit "Configure" and "Generate".

Java version 1.6.0.27 configured successfully!

Configuring done

Generating done

5) With NSIS installed you can jump to build the package or just build the libraries.

c:\zeromq\jzmq\jzmq> nmake package

or

c:\zeromq\jzmq\jzmq> nmake

Then output similar to as follows:

Microsoft (R) Program Maintenance Utility Version 10.00.30319.01
Copyright (C) Microsoft Corporation.  All rights reserved.

[ 11%] Generating config.hpp
[ 22%] Generating org/zeromq/ZMQ.class, org/zeromq/ZMQ$$Context.class, org/zeromq/ZMQ$$Socket.class, org/zeromq/ZMQ$$Poller.class, org/zeromq/ZMQ$$Error.class, org/zeromq/ZMQException.class, org/zeromq/ZMQQueue.class, org/zeromq/ZMQForwarder.class, org/zeromq/ZMQStreamer.class, org/zeromq/EmbeddedLibraryTools.class, org/zeromq/App.class
[ 33%] Generating org_zeromq_ZMQ.h, org_zeromq_ZMQ_Error.h, org_zeromq_ZMQ_Context.h, org_zeromq_ZMQ_Socket.h, org_zeromq_ZMQ_Poller.h
[ 44%] Generating lib/zmq.jar
Scanning dependencies of target jzmq
[ 44%] Generating org/zeromq/ZMQ.class, org/zeromq/ZMQ$$Context.class, org/zeromq/ZMQ$$Socket.class, org/zeromq/ZMQ$$Poller.class, org/zeromq/ZMQ$$Error.class, org/zeromq/ZMQException.class, org/zeromq/ZMQQueue.class, org/zeromq/ZMQForwarder.class, org/zeromq/ZMQStreamer.class, org/zeromq/EmbeddedLibraryTools.class, org/zeromq/App.class
[ 44%] Generating org_zeromq_ZMQ.h, org_zeromq_ZMQ_Error.h, org_zeromq_ZMQ_Context.h, org_zeromq_ZMQ_Socket.h, org_zeromq_ZMQ_Poller.h
[ 55%] Building CXX object CMakeFiles/jzmq.dir/src/Context.cpp.obj
Context.cpp
[ 66%] Building CXX object CMakeFiles/jzmq.dir/src/Poller.cpp.obj
Poller.cpp
[ 77%] Building CXX object CMakeFiles/jzmq.dir/src/Socket.cpp.obj
Socket.cpp
C:\zeromq\jzmq\jzmq\src\Socket.cpp(176) : warning C4267: 'argument' : conversion from 'size_t' to 'jsize', possible loss of data
C:\zeromq\jzmq\jzmq\src\Socket.cpp(182) : warning C4267: 'argument' : conversion from 'size_t' to 'jsize', possible loss of data
C:\zeromq\jzmq\jzmq\src\Socket.cpp(476) : warning C4267: 'initializing' : conversion from 'size_t' to 'int', possible loss of data
C:\zeromq\jzmq\jzmq\src\Socket.cpp(500) : warning C4267: 'initializing' : conversion from 'size_t' to 'int', possible loss of data
[ 88%] Building CXX object CMakeFiles/jzmq.dir/src/util.cpp.obj
util.cpp
[100%] Building CXX object CMakeFiles/jzmq.dir/src/ZMQ.cpp.obj
ZMQ.cpp
Linking CXX shared library lib\jzmq.dll
   Creating library lib\jzmq.lib and object lib\jzmq.exp
[100%] Built target jzmq
Run CPack packaging tool...
CPack: Create package using NSIS
CPack: Install projects
CPack: - Run preinstall target for: JZMQ
CPack: - Install project: JZMQ
CPack: Create package
CPack: - package: C:/zeromq/jzmq/jzmq/build64/JZMQ-2.1.10-win64.exe generated.

Then to test copy all the libraries into the perf directory from the jzmq package and build some examples.

C:\zeromq\jzmq\jzmq\perf>"\Program Files\Java\jdk1.6.0_27"\bin\javac -cp zmq.jar;. local_lat.java

C:\zeromq\jzmq\jzmq\perf>"\Program Files\Java\jdk1.6.0_27"\bin\javac -cp zmq.jar;. remote_lat.java

Then test:

C:\zeromq\jzmq\jzmq\perf>"\Program Files\Java\jdk1.6.0_27\bin"\java -Xcheck:jni -verbose:jni,class -classpath .;zmq.jar local_lat tcp://127.0.0.1:5000 1 100

C:\zeromq\jzmq\jzmq\perf>"\Program Files\Java\jdk1.6.0_27"\bin\java -classpath .;zmq.jar remote_lat tcp://127.0.0.1:5000 1 100
message size: 1 [B]
roundtrip count: 100
mean latency: 85.0 [us]

The perf directory looks like this:

10/26/2011  01:18 PM    <DIR>          .
10/26/2011  01:18 PM    <DIR>          ..
10/26/2011  01:09 PM            16,384 jzmq.dll
10/03/2011  12:47 PM           445,952 libzmq.dll
10/26/2011  12:53 PM             1,492 local_lat.class
10/05/2011  05:07 PM             1,723 local_lat.java
10/05/2011  05:07 PM                68 local_lat.sh
10/05/2011  05:07 PM             2,278 local_thr.java
10/05/2011  05:07 PM                68 local_thr.sh
10/05/2011  05:07 PM               512 Makefile.am
10/05/2011  05:07 PM             9,988 Makefile.in
10/26/2011  01:18 PM             1,853 remote_lat.class
10/05/2011  05:07 PM             2,049 remote_lat.java
10/05/2011  05:07 PM                69 remote_lat.sh
10/05/2011  05:07 PM             1,722 remote_thr.java
10/05/2011  05:07 PM                69 remote_thr.sh
10/26/2011  01:09 PM            15,350 zmq.jar
              15 File(s)        499,577 bytes

Bug Reporting

http://github.com/zeromq/jzmq/issues

Mailing list

gro.qmorez.stsil|ved-qmorez#gro.qmorez.stsil|ved-qmorez