Class ZMQ
- java.lang.Object
-
- org.zeromq.ZMQ
-
public class ZMQ extends java.lang.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
usingcontext(int)
. When you exit your application you must destroy the context usingZMQ.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 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 socketsstatic 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 Description static java.nio.charset.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 byROUTER
static int
XREQ
Deprecated.As of release 3.0 of zeromq, replaced byDEALER
static int
XSUB
Deprecated.
-
Constructor Summary
Constructors Modifier Constructor Description private
ZMQ()
-
Method Summary
All Methods Static Methods Concrete Methods Deprecated Methods Modifier and Type Method 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 java.lang.String
getVersionString()
static int
makeVersion(int major, int minor, int patch)
static void
msleep(long millis)
static int
poll(java.nio.channels.Selector selector, ZMQ.PollItem[] items, int count, long timeout)
static int
poll(java.nio.channels.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, java.util.concurrent.TimeUnit unit)
-
-
-
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 byDEALER
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 byROUTER
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 java.nio.charset.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.Socketbackend
- ZMQ.Socketcapture
- 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(java.nio.channels.Selector selector, ZMQ.PollItem[] items, long timeout)
-
poll
public static int poll(java.nio.channels.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 java.lang.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, java.util.concurrent.TimeUnit unit)
-
-