Package org.zeromq
Class ZProxy
- java.lang.Object
-
- org.zeromq.ZProxy
-
public class ZProxy extends java.lang.Object
Implementation of a remotely controlled proxy for 0MQ, usingZActor
.
The goals of this implementation are to delegate the creation of sockets in a background thread via a callback interface to ensure their correct use and to provide ultimately to end-users the following features.Basic features:
- Remote Control
- Start: if was paused, flushes the pending messages
- Pause: lets the socket queues accumulate messages according to their types
- Stop: Shutdowns the proxy, can be restarted
- Status: Retrieves the status of the proxy
- Cold Restart: Closes and recreates the connections
Hot Restart
: User-defined behavior with custom messagesConfigure
: User-defined behavior with custom messagescommand(String, boolean)
...: Custom commands of your own- Exit: Definitive shutdown of the proxy and its control
- Proxy mechanism ensured by pluggable pumps
- with built-in low-level
ZProxy.ZmqPump
(zmq.ZMQ): useful for performances - with built-in high-level
ZProxy.ZPump
(ZeroMQ): useful formessage transformation
, lower performances - with your own-custom proxy pump implementing a
1-method interface
- with built-in low-level
You can have all the above non-customizable features in about these lines of code:final ZProxy.Proxy provider = new ZProxy.SimpleProxy() { public Socket create(ZContext ctx, ZProxy.Plug place, Object ... args) { assert ("TEST".equals(args[0]); Socket socket = null; if (place == ZProxy.Plug.FRONT) { socket = ctx.createSocket(ZMQ.ROUTER); } if (place == ZProxy.Plug.BACK) { socket = ctx.createSocket(ZMQ.DEALER); } return socket; } public void configure(Socket socket, ZProxy.Plug place, Object ... args) { assert ("TEST".equals(args[0]); int port = -1; if (place == ZProxy.Plug.FRONT) { port = socket.bind("tcp://127.0.0.1:6660"); } if (place == ZProxy.Plug.BACK) { port = socket.bind("tcp://127.0.0.1:6661"); } if (place == ZProxy.Plug.CAPTURE && socket != null) { socket.bind("tcp://127.0.0.1:4263"); } } }; ZProxy proxy = ZProxy.newProxy("ProxyOne", provider, "ABRACADABRA", Arrays.asList("TEST"));
You can then use it like this:final boolean async = false, sync = true; String status = null; status = proxy.status(); status = proxy.pause(sync); status = proxy.start(async); status = proxy.restart(new ZMsg()); status = proxy.status(async); status = proxy.stop(sync); boolean here = proxy.sign(); ZMsg cfg = new ZMsg(); msg.add("CONFIG-1"); ZMsg rcvd = proxy.configure(cfg); proxy.exit(); status = proxy.status(sync); assert (!proxy.started());
programmatic interface
with enums is also available. - Remote Control
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
ZProxy.Command
static class
ZProxy.Plug
Possible places for sockets in the proxy.static interface
ZProxy.Proxy
private static class
ZProxy.ProxyActor
static interface
ZProxy.Pump
static class
ZProxy.State
private static class
ZProxy.ZmqPump
A specialized transport for better transmission purposes that will send each packets individually instead of the whole message.static class
ZProxy.ZPump
A pump that reads a message as a whole before transmitting it.
-
Field Summary
Fields Modifier and Type Field Description private ZAgent
agent
static java.lang.String
ALIVE
private static java.lang.String
CONFIG
private static java.util.concurrent.atomic.AtomicInteger
counter
private ZStar.Exit
exit
private static java.lang.String
EXIT
static java.lang.String
EXITED
private static java.lang.String
PAUSE
static java.lang.String
PAUSED
private static java.lang.String
RESTART
private static java.lang.String
START
static java.lang.String
STARTED
private static java.lang.String
STATUS
private static java.lang.String
STOP
static java.lang.String
STOPPED
-
Constructor Summary
Constructors Constructor Description ZProxy(java.lang.String name, ZAgent.SelectorCreator selector, ZProxy.Proxy creator, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.useZProxy(String, Proxy, String, Object...)
instead.ZProxy(java.lang.String name, ZProxy.Proxy creator, java.lang.String motdelafin, java.lang.Object... args)
Creates a new named proxy.ZProxy(java.lang.String name, ZProxy.Proxy sockets, ZProxy.Pump pump, java.lang.String motdelafin, java.lang.Object... args)
Creates a new named proxy.ZProxy(ZAgent.SelectorCreator selector, ZProxy.Proxy creator, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.useZProxy(Proxy, String, Object...)
instead.ZProxy(ZContext ctx, java.lang.String name, ZAgent.SelectorCreator selector, ZProxy.Proxy sockets, ZProxy.Pump pump, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.ZProxy(ZContext ctx, java.lang.String name, ZProxy.Proxy sockets, ZProxy.Pump pump, java.lang.String motdelafin, java.lang.Object... args)
Creates a new named proxy.ZProxy(ZProxy.Proxy creator, java.lang.String motdelafin, java.lang.Object... args)
Creates a new unnamed proxy.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description java.lang.String
command(java.lang.String command, boolean sync)
Sends a command message to the proxy actor.ZProxy.State
command(ZProxy.Command command, boolean sync)
Sends a command message to the proxy actor.ZMsg
command(ZProxy.Command command, ZMsg msg, boolean sync)
Sends a command message to the proxy actor.ZMsg
configure(ZMsg msg)
Configures the proxy.java.lang.String
exit()
Stops the proxy and exits.java.lang.String
exit(boolean sync)
Deprecated.The call is synchronous: the sync parameter is ignored, as it leads to many mistakes in case of a provided ZContext.boolean
isStarted()
Binary inquiry for the status of the proxy.static ZProxy
newProxy(ZContext ctx, java.lang.String name, ZAgent.SelectorCreator selector, ZProxy.Proxy sockets, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.usenewProxy(ZContext, String, Proxy, String, Object...)
instead.static ZProxy
newProxy(ZContext ctx, java.lang.String name, ZProxy.Proxy sockets, java.lang.String motdelafin, java.lang.Object... args)
Creates a new low-level proxy for better performances.static ZProxy
newZProxy(ZContext ctx, java.lang.String name, ZAgent.SelectorCreator selector, ZProxy.Proxy sockets, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.static ZProxy
newZProxy(ZContext ctx, java.lang.String name, ZProxy.Proxy sockets, java.lang.String motdelafin, java.lang.Object... args)
Creates a new proxy in a ZeroMQ way.java.lang.String
pause(boolean sync)
Pauses the proxy.private java.lang.String
recvStatus()
java.lang.String
restart(ZMsg hot)
Restarts the proxy.java.lang.String
start(boolean sync)
Starts the proxy.boolean
started()
Binary inquiry for the status of the proxy.java.lang.String
status()
Inquires for the status of the proxy.java.lang.String
status(boolean sync)
Inquires for the status of the proxy.java.lang.String
stop(boolean sync)
Stops the proxy.
-
-
-
Field Detail
-
START
private static final java.lang.String START
-
PAUSE
private static final java.lang.String PAUSE
-
STOP
private static final java.lang.String STOP
-
RESTART
private static final java.lang.String RESTART
-
EXIT
private static final java.lang.String EXIT
-
STATUS
private static final java.lang.String STATUS
-
CONFIG
private static final java.lang.String CONFIG
-
STARTED
public static final java.lang.String STARTED
-
PAUSED
public static final java.lang.String PAUSED
-
STOPPED
public static final java.lang.String STOPPED
-
EXITED
public static final java.lang.String EXITED
-
ALIVE
public static final java.lang.String ALIVE
-
counter
private static final java.util.concurrent.atomic.AtomicInteger counter
-
agent
private final ZAgent agent
-
exit
private final ZStar.Exit exit
-
-
Constructor Detail
-
ZProxy
@Deprecated public ZProxy(ZAgent.SelectorCreator selector, ZProxy.Proxy creator, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.useZProxy(Proxy, String, Object...)
instead.Creates a new unnamed proxy.- Parameters:
selector
- the creator of the selector used for the proxy.creator
- the creator of the sockets of the proxy.motdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.
-
ZProxy
public ZProxy(ZProxy.Proxy creator, java.lang.String motdelafin, java.lang.Object... args)
Creates a new unnamed proxy.- Parameters:
creator
- the creator of the sockets of the proxy.motdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.
-
ZProxy
@Deprecated public ZProxy(java.lang.String name, ZAgent.SelectorCreator selector, ZProxy.Proxy creator, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.useZProxy(String, Proxy, String, Object...)
instead.Creates a new named proxy.- Parameters:
name
- the name of the proxy (used in threads naming).selector
- the creator of the selector used for the proxy.creator
- the creator of the sockets of the proxy.motdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.
-
ZProxy
public ZProxy(java.lang.String name, ZProxy.Proxy creator, java.lang.String motdelafin, java.lang.Object... args)
Creates a new named proxy.- Parameters:
name
- the name of the proxy (used in threads naming).creator
- the creator of the sockets of the proxy.motdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.
-
ZProxy
@Deprecated public ZProxy(ZContext ctx, java.lang.String name, ZAgent.SelectorCreator selector, ZProxy.Proxy sockets, ZProxy.Pump pump, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.Creates a new named proxy.- Parameters:
ctx
- the main context used. If null, a new context will be created and closed at the stop of the operation. If not null, it is the responsibility of the call to close it.name
- the name of the proxy (used in threads naming).selector
- the creator of the selector used for the proxy.sockets
- the creator of the sockets of the proxy.pump
- the pump used for the proxymotdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.
-
ZProxy
public ZProxy(java.lang.String name, ZProxy.Proxy sockets, ZProxy.Pump pump, java.lang.String motdelafin, java.lang.Object... args)
Creates a new named proxy. A new context will be created and closed at the stop of the operation.- Parameters:
name
- the name of the proxy (used in threads naming).sockets
- the creator of the sockets of the proxy.pump
- the pump used for the proxymotdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.
-
ZProxy
public ZProxy(ZContext ctx, java.lang.String name, ZProxy.Proxy sockets, ZProxy.Pump pump, java.lang.String motdelafin, java.lang.Object... args)
Creates a new named proxy.- Parameters:
ctx
- the main context used. If null, a new context will be created and closed at the stop of the operation. If not null, it is the responsibility of the call to close it.name
- the name of the proxy (used in threads naming).sockets
- the creator of the sockets of the proxy.pump
- the pump used for the proxymotdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.
-
-
Method Detail
-
newZProxy
@Deprecated public static ZProxy newZProxy(ZContext ctx, java.lang.String name, ZAgent.SelectorCreator selector, ZProxy.Proxy sockets, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.Creates a new proxy in a ZeroMQ way. This proxy will be less efficient than thelow-level one
.- Parameters:
ctx
- the context used for the proxy. Possibly null, in this case a new context will be created and automatically destroyed afterwards.name
- the name of the proxy. Possibly null.selector
- the creator of the selector used for the internal polling. Not null.sockets
- the sockets creator of the proxy. Not null.motdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.- Returns:
- the created proxy.
-
newZProxy
public static ZProxy newZProxy(ZContext ctx, java.lang.String name, ZProxy.Proxy sockets, java.lang.String motdelafin, java.lang.Object... args)
Creates a new proxy in a ZeroMQ way. This proxy will be less efficient than thelow-level one
.- Parameters:
ctx
- the context used for the proxy. Possibly null, in this case a new context will be created and automatically destroyed afterwards.name
- the name of the proxy. Possibly null.sockets
- the sockets creator of the proxy. Not null.motdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.- Returns:
- the created proxy.
-
newProxy
@Deprecated public static ZProxy newProxy(ZContext ctx, java.lang.String name, ZAgent.SelectorCreator selector, ZProxy.Proxy sockets, java.lang.String motdelafin, java.lang.Object... args)
Deprecated.usenewProxy(ZContext, String, Proxy, String, Object...)
instead.Creates a new low-level proxy for better performances.- Parameters:
ctx
- the context used for the proxy. Possibly null, in this case a new context will be created and automatically destroyed afterwards.name
- the name of the proxy. Possibly null.selector
- the creator of the selector used for the internal polling. Not null.sockets
- the sockets creator of the proxy. Not null.motdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.- Returns:
- the created proxy.
-
newProxy
public static ZProxy newProxy(ZContext ctx, java.lang.String name, ZProxy.Proxy sockets, java.lang.String motdelafin, java.lang.Object... args)
Creates a new low-level proxy for better performances.- Parameters:
ctx
- the context used for the proxy. Possibly null, in this case a new context will be created and automatically destroyed afterwards.name
- the name of the proxy. Possibly null.sockets
- the sockets creator of the proxy. Not null.motdelafin
- the final word used to mark the end of the proxy. Null to disable this mechanism.args
- an optional array of arguments that will be passed at the creation.- Returns:
- the created proxy.
-
start
public java.lang.String start(boolean sync)
Starts the proxy.- Parameters:
sync
- true to read the status in synchronous way, false for asynchronous mode- Returns:
- the read status
-
pause
public java.lang.String pause(boolean sync)
Pauses the proxy. A paused proxy will cease processing messages, causing them to be queued up and potentially hit the high-water mark on the frontend or backend socket, causing messages to be dropped, or writing applications to block.- Parameters:
sync
- true to read the status in synchronous way, false for asynchronous mode- Returns:
- the read status
-
stop
public java.lang.String stop(boolean sync)
Stops the proxy.- Parameters:
sync
- true to read the status in synchronous way, false for asynchronous mode- Returns:
- the read status
-
command
public java.lang.String command(java.lang.String command, boolean sync)
Sends a command message to the proxy actor. Can be useful for programmatic interfaces. Does not works with commandsCONFIG
andRESTART
.- Parameters:
command
- the command to execute. Not null.sync
- true to read the status in synchronous way, false for asynchronous mode- Returns:
- the read status
-
command
public ZProxy.State command(ZProxy.Command command, boolean sync)
Sends a command message to the proxy actor. Can be useful for programmatic interfaces. Does not works with commandsCONFIG
andRESTART
.- Parameters:
command
- the command to execute.sync
- true to read the status in synchronous way, false for asynchronous mode- Returns:
- the read state
-
command
public ZMsg command(ZProxy.Command command, ZMsg msg, boolean sync)
Sends a command message to the proxy actor. Can be useful for programmatic interfaces. Works only with commandsCONFIG
andRESTART
.- Parameters:
command
- the command to execute.msg
- the custom message to transmit.sync
- true to read the status in synchronous way, false for asynchronous mode- Returns:
- the response message
-
configure
public ZMsg configure(ZMsg msg)
Configures the proxy. The distant side has to send back one (1) mandatory response message.- Parameters:
msg
- the custom message sent as configuration tip- Returns:
- the mandatory response message of the configuration.
-
restart
public java.lang.String restart(ZMsg hot)
Restarts the proxy. Stays alive.- Parameters:
hot
- null to make a cold restart (closing then re-creation of the sockets) or a configuration message to perform a configurable hot restart,
-
exit
@Deprecated public java.lang.String exit(boolean sync)
Deprecated.The call is synchronous: the sync parameter is ignored, as it leads to many mistakes in case of a provided ZContext.Stops the proxy and exits.- Parameters:
sync
- forced to true to read the status in synchronous way.- Returns:
- the read status.
-
exit
public java.lang.String exit()
Stops the proxy and exits. The call is synchronous.- Returns:
- the read status.
-
status
public java.lang.String status()
Inquires for the status of the proxy. This call is synchronous.
-
status
public java.lang.String status(boolean sync)
Inquires for the status of the proxy.- Parameters:
sync
- true to read the status in synchronous way, false for asynchronous mode. If false, you get the last cached status of the proxy
-
recvStatus
private java.lang.String recvStatus()
-
isStarted
public boolean isStarted()
Binary inquiry for the status of the proxy.
-
started
public boolean started()
Binary inquiry for the status of the proxy.
-
-