org.zeromq

Class ZMQ

java.lang.Object

org.zeromq.ZMQ

public class ZMQ
extends Object

The ØMQ lightweight messaging kernel is a library which extends the standard socket interfaces with features traditionally provided by specialised messaging middleware products. ØMQ sockets provide an abstraction of asynchronous message queues, multiple messaging patterns, message filtering (subscriptions), seamless access to multiple transport protocols and more.

Following is an overview of ØMQ concepts, describes how ØMQ abstracts standard sockets and provides a reference manual for the functions provided by the ØMQ library.

Contexts

Before using any ØMQ library functions you must create a ØMQ context using context(int). When you exit your application you must destroy the context using ZMQ.Context.close().

Thread safety

A ØMQ context is thread safe and may be shared among as many application threads as necessary, without any additional locking required on the part of the caller.
Individual ØMQ sockets are not thread safe except in the case where full memory barriers are issued when migrating a socket from one thread to another.
In practice this means applications can create a socket in one thread with * ZMQ.Context.socket(SocketType) and then pass it to a newly created thread as part of thread initialization.

Multiple contexts

Multiple contexts may coexist within a single application.
Thus, an application can use ØMQ directly and at the same time make use of any number of additional libraries or components which themselves make use of ØMQ as long as the above guidelines regarding thread safety are adhered to.

Messages

A ØMQ message is a discrete unit of data passed between applications or components of the same application. ØMQ messages have no internal structure and from the point of view of ØMQ itself they are considered to be opaque binary data.

Sockets

ØMQ sockets present an abstraction of a asynchronous message queue, with the exact queueing semantics depending on the socket type in use.

Transports

A ØMQ socket can use multiple different underlying transport mechanisms. Each transport mechanism is suited to a particular purpose and has its own advantages and drawbacks.

The following transport mechanisms are provided:

• Unicast transport using TCP
• Local inter-process communication transport
• Local in-process (inter-thread) communication transport

Proxies

ØMQ provides proxies to create fanout and fan-in topologies. A proxy connects a frontend socket to a backend socket and switches all messages between the two sockets, opaquely. A proxy may optionally capture all traffic to a third socket.

Security

A ØMQ socket can select a security mechanism. Both peers must use the same security mechanism.

The following security mechanisms are provided for IPC and TCP connections:

• Null security
• Plain-text authentication using username and password
• Elliptic curve authentication and encryption

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ZMQ.Context Container for all sockets in a single process, acting as the transport for inproc sockets, which are the fastest way to connect threads in one process.
static class	ZMQ.Curve Class that interfaces the generation of CURVE key pairs.
static class	ZMQ.Error
static class	ZMQ.Event Inner class: Event.
static class	ZMQ.Poller Provides a mechanism for applications to multiplex input/output events in a level-triggered fashion over a set of sockets
static class	ZMQ.PollItem
static class	ZMQ.Socket Abstracts an asynchronous message queue, with the exact queuing semantics depending on the socket type in use.

Field Summary

Fields

Modifier and Type	Field and Description
static Charset	CHARSET
static int	DEALER Deprecated.
static int	DONTWAIT Socket flag to indicate a nonblocking send or recv mode.
static int	DOWNSTREAM Deprecated.
static int	EVENT_ACCEPT_FAILED EVENT_ACCEPT_FAILED: could not accept client connection.
static int	EVENT_ACCEPTED EVENT_ACCEPTED: connection accepted to bound interface.
static int	EVENT_ALL EVENT_ALL: all events known.
static int	EVENT_BIND_FAILED EVENT_BIND_FAILED: socket could not bind to an address.
static int	EVENT_CLOSE_FAILED EVENT_CLOSE_FAILED: connection couldn't be closed.
static int	EVENT_CLOSED EVENT_CLOSED: connection closed.
static int	EVENT_CONNECT_DELAYED EVENT_CONNECT_DELAYED: synchronous connect failed, it's being polled.
static int	EVENT_CONNECT_RETRIED EVENT_CONNECT_RETRIED: asynchronous connect / reconnection attempt.
static int	EVENT_CONNECTED EVENT_CONNECTED: connection established.
static int	EVENT_DELAYED Deprecated.
static int	EVENT_DISCONNECTED EVENT_DISCONNECTED: broken session.
static int	EVENT_HANDSHAKE_PROTOCOL EVENT_HANDSHAKE_PROTOCOL: protocol has been successfully negotiated.
static int	EVENT_LISTENING EVENT_LISTENING: socket bound to an address, ready to accept connections.
static int	EVENT_MONITOR_STOPPED EVENT_MONITOR_STOPPED: monitor has been stopped.
static int	EVENT_RETRIED Deprecated.
static int	FORWARDER Deprecated.
static byte[]	MESSAGE_SEPARATOR
static int	NOBLOCK
static int	PAIR Deprecated.
static byte[]	PROXY_PAUSE
static byte[]	PROXY_RESUME
static byte[]	PROXY_TERMINATE
static int	PUB Deprecated.
static int	PULL Deprecated.
static int	PUSH Deprecated.
static int	QUEUE Deprecated.
static int	REP Deprecated.
static int	REQ Deprecated.
static int	ROUTER Deprecated.
static int	SNDMORE Socket flag to indicate that more message parts are coming.
static int	STREAM Deprecated.
static int	STREAMER Deprecated.
static int	SUB Deprecated.
static byte[]	SUBSCRIPTION_ALL
static int	UPSTREAM Deprecated.
static int	XPUB Deprecated.
static int	XREP Deprecated. As of release 3.0 of zeromq, replaced by ROUTER
static int	XREQ Deprecated. As of release 3.0 of zeromq, replaced by DEALER
static int	XSUB Deprecated.

Method Summary

Modifier and Type	Method and Description
static ZMQ.Context	context(int ioThreads) Create a new Context.
static boolean	device(int type, ZMQ.Socket frontend, ZMQ.Socket backend) Deprecated.
static int	getFullVersion()
static int	getMajorVersion()
static int	getMinorVersion()
static int	getPatchVersion()
static String	getVersionString()
static int	makeVersion(int major, int minor, int patch)
static void	msleep(long millis)
static int	poll(Selector selector, ZMQ.PollItem[] items, int count, long timeout)
static int	poll(Selector selector, ZMQ.PollItem[] items, long timeout)
static boolean	proxy(ZMQ.Socket frontend, ZMQ.Socket backend, ZMQ.Socket capture) Starts the built-in 0MQ proxy in the current application thread.
static boolean	proxy(ZMQ.Socket frontend, ZMQ.Socket backend, ZMQ.Socket capture, ZMQ.Socket control)
static void	sleep(long seconds)
static void	sleep(long amount, TimeUnit unit)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SNDMORE

public static final int SNDMORE

Socket flag to indicate that more message parts are coming.

See Also:

Constant Field Values

DONTWAIT

public static final int DONTWAIT

Socket flag to indicate a nonblocking send or recv mode.

See Also:

Constant Field Values

NOBLOCK

public static final int NOBLOCK

See Also:

Constant Field Values

PAIR

@Deprecated
public static final int PAIR

Deprecated.

See Also:

Constant Field Values

PUB

@Deprecated
public static final int PUB

Deprecated.

See Also:

Constant Field Values

SUB

@Deprecated
public static final int SUB

Deprecated.

See Also:

Constant Field Values

REQ

@Deprecated
public static final int REQ

Deprecated.

See Also:

Constant Field Values

REP

@Deprecated
public static final int REP

Deprecated.

See Also:

Constant Field Values

DEALER

@Deprecated
public static final int DEALER

Deprecated.

See Also:

Constant Field Values

XREQ

@Deprecated
public static final int XREQ

Deprecated. As of release 3.0 of zeromq, replaced by DEALER

Old alias for DEALER flag. Flag to specify a XREQ socket, receiving side must be a XREP.

See Also:

Constant Field Values

ROUTER

@Deprecated
public static final int ROUTER

Deprecated.

See Also:

Constant Field Values

XREP

@Deprecated
public static final int XREP

Deprecated. As of release 3.0 of zeromq, replaced by ROUTER

Old alias for ROUTER flag. Flag to specify the receiving part of a XREQ socket.

See Also:

Constant Field Values

PULL

@Deprecated
public static final int PULL

Deprecated.

See Also:

Constant Field Values

PUSH

@Deprecated
public static final int PUSH

Deprecated.

See Also:

Constant Field Values

XPUB

@Deprecated
public static final int XPUB

Deprecated.

See Also:

Constant Field Values

XSUB

@Deprecated
public static final int XSUB

Deprecated.

See Also:

Constant Field Values

STREAM

@Deprecated
public static final int STREAM

Deprecated.

See Also:

Constant Field Values

STREAMER

@Deprecated
public static final int STREAMER

Deprecated.

Flag to specify a STREAMER device.

See Also:

Constant Field Values

FORWARDER

@Deprecated
public static final int FORWARDER

Deprecated.

Flag to specify a FORWARDER device.

See Also:

Constant Field Values

QUEUE

@Deprecated
public static final int QUEUE

Deprecated.

Flag to specify a QUEUE device.

See Also:

Constant Field Values

UPSTREAM

@Deprecated
public static final int UPSTREAM

Deprecated.

See Also:

PULL, Constant Field Values

DOWNSTREAM

@Deprecated
public static final int DOWNSTREAM

Deprecated.

See Also:

PUSH, Constant Field Values

EVENT_CONNECTED

public static final int EVENT_CONNECTED

EVENT_CONNECTED: connection established. The EVENT_CONNECTED event triggers when a connection has been established to a remote peer. This can happen either synchronous or asynchronous. Value is the FD of the newly connected socket.

See Also:

Constant Field Values

EVENT_CONNECT_DELAYED

public static final int EVENT_CONNECT_DELAYED

EVENT_CONNECT_DELAYED: synchronous connect failed, it's being polled. The EVENT_CONNECT_DELAYED event triggers when an immediate connection attempt is delayed and its completion is being polled for. Value has no meaning.

See Also:

Constant Field Values

EVENT_DELAYED

@Deprecated
public static final int EVENT_DELAYED

Deprecated.

See Also:

EVENT_CONNECT_DELAYED, Constant Field Values

EVENT_CONNECT_RETRIED

public static final int EVENT_CONNECT_RETRIED

EVENT_CONNECT_RETRIED: asynchronous connect / reconnection attempt. The EVENT_CONNECT_RETRIED event triggers when a connection attempt is being handled by reconnect timer. The reconnect interval's recomputed for each attempt. Value is the reconnect interval.

See Also:

Constant Field Values

EVENT_RETRIED

@Deprecated
public static final int EVENT_RETRIED

Deprecated.

See Also:

EVENT_CONNECT_RETRIED, Constant Field Values

EVENT_LISTENING

public static final int EVENT_LISTENING

EVENT_LISTENING: socket bound to an address, ready to accept connections. The EVENT_LISTENING event triggers when a socket's successfully bound to a an interface. Value is the FD of the newly bound socket.

See Also:

Constant Field Values

EVENT_BIND_FAILED

public static final int EVENT_BIND_FAILED

EVENT_BIND_FAILED: socket could not bind to an address. The EVENT_BIND_FAILED event triggers when a socket could not bind to a given interface. Value is the errno generated by the bind call.

See Also:

Constant Field Values

EVENT_ACCEPTED

public static final int EVENT_ACCEPTED

EVENT_ACCEPTED: connection accepted to bound interface. The EVENT_ACCEPTED event triggers when a connection from a remote peer has been established with a socket's listen address. Value is the FD of the accepted socket.

See Also:

Constant Field Values

EVENT_ACCEPT_FAILED

public static final int EVENT_ACCEPT_FAILED

EVENT_ACCEPT_FAILED: could not accept client connection. The EVENT_ACCEPT_FAILED event triggers when a connection attempt to a socket's bound address fails. Value is the errno generated by accept.

See Also:

Constant Field Values

EVENT_CLOSED

public static final int EVENT_CLOSED

EVENT_CLOSED: connection closed. The EVENT_CLOSED event triggers when a connection's underlying descriptor has been closed. Value is the former FD of the for the closed socket. FD has been closed already!

See Also:

Constant Field Values

EVENT_CLOSE_FAILED

public static final int EVENT_CLOSE_FAILED

EVENT_CLOSE_FAILED: connection couldn't be closed. The EVENT_CLOSE_FAILED event triggers when a descriptor could not be released back to the OS. Implementation note: ONLY FOR IPC SOCKETS. Value is the errno generated by unlink.

See Also:

Constant Field Values

EVENT_DISCONNECTED

public static final int EVENT_DISCONNECTED

EVENT_DISCONNECTED: broken session. The EVENT_DISCONNECTED event triggers when the stream engine (tcp and ipc specific) detects a corrupted / broken session. Value is the FD of the socket.

See Also:

Constant Field Values

EVENT_MONITOR_STOPPED

public static final int EVENT_MONITOR_STOPPED

EVENT_MONITOR_STOPPED: monitor has been stopped. The EVENT_MONITOR_STOPPED event triggers when the monitor for a socket is stopped.

See Also:

Constant Field Values

EVENT_HANDSHAKE_PROTOCOL

public static final int EVENT_HANDSHAKE_PROTOCOL

EVENT_HANDSHAKE_PROTOCOL: protocol has been successfully negotiated. The EVENT_HANDSHAKE_PROTOCOL event triggers when the stream engine (tcp and ipc) successfully negotiated a protocol version with the peer. Value is the version number (0 for unversioned, 3 for V3).

See Also:

Constant Field Values

EVENT_ALL

public static final int EVENT_ALL

EVENT_ALL: all events known. The EVENT_ALL constant can be used to set up a monitor for all known events.

See Also:

Constant Field Values

MESSAGE_SEPARATOR

public static final byte[] MESSAGE_SEPARATOR

SUBSCRIPTION_ALL

public static final byte[] SUBSCRIPTION_ALL

PROXY_PAUSE

public static final byte[] PROXY_PAUSE

PROXY_RESUME

public static final byte[] PROXY_RESUME

PROXY_TERMINATE

public static final byte[] PROXY_TERMINATE

CHARSET

public static final Charset CHARSET

Method Detail

context

public static ZMQ.Context context(int ioThreads)

Create a new Context.

Parameters:

ioThreads - Number of threads to use, usually 1 is sufficient for most use cases.

Returns:

the Context

device

@Deprecated
public static boolean device(int type,
                                         ZMQ.Socket frontend,
                                         ZMQ.Socket backend)

Deprecated.

proxy

public static boolean proxy(ZMQ.Socket frontend,
                            ZMQ.Socket backend,
                            ZMQ.Socket capture)

Starts the built-in 0MQ proxy in the current application thread. The proxy connects a frontend socket to a backend socket. Conceptually, data flows from frontend to backend. Depending on the socket types, replies may flow in the opposite direction. The direction is conceptual only; the proxy is fully symmetric and there is no technical difference between frontend and backend.

Before calling ZMQ.proxy() you must set any socket options, and connect or bind both frontend and backend sockets. The two conventional proxy models are:

ZMQ.proxy() runs in the current thread and returns only if/when the current context is closed.

Parameters:

frontend - ZMQ.Socket

backend - ZMQ.Socket

capture - If the capture socket is not NULL, the proxy shall send all messages, received on both frontend and backend, to the capture socket. The capture socket should be a ZMQ_PUB, ZMQ_DEALER, ZMQ_PUSH, or ZMQ_PAIR socket.

proxy

public static boolean proxy(ZMQ.Socket frontend,
                            ZMQ.Socket backend,
                            ZMQ.Socket capture,
                            ZMQ.Socket control)

poll

public static int poll(Selector selector,
                       ZMQ.PollItem[] items,
                       long timeout)

poll

public static int poll(Selector selector,
                       ZMQ.PollItem[] items,
                       int count,
                       long timeout)

getMajorVersion

public static int getMajorVersion()

Returns:

Major version number of the ZMQ library.

getMinorVersion

public static int getMinorVersion()

Returns:

Major version number of the ZMQ library.

getPatchVersion

public static int getPatchVersion()

Returns:

Major version number of the ZMQ library.

getFullVersion

public static int getFullVersion()

Returns:

Full version number of the ZMQ library used for comparing versions.

makeVersion

public static int makeVersion(int major,
                              int minor,
                              int patch)

Parameters:

major - Version major component.

minor - Version minor component.

patch - Version patch component.

Returns:

Comparible single int version number.

getVersionString

public static String getVersionString()

Returns:

String version number in the form major.minor.patch.

msleep

public static void msleep(long millis)

sleep

public static void sleep(long seconds)

sleep

public static void sleep(long amount,
                         TimeUnit unit)