Package org.zeromq

Class ZProxy

  • public class ZProxy
extends java.lang.Object
    Implementation of a remotely controlled proxy for 0MQ, using ZActor.
    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 messages
      • Configure: User-defined behavior with custom messages
      • command(String, boolean) ...: Custom commands of your own
      • Exit: Definitive shutdown of the proxy and its control
      All the non-custom commands can be performed in asynchronous or synchronous mode.
    • Proxy mechanism ensured by pluggable pumps


    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"));
    Once created, the proxy is not started. You have to perform first a start command on it. This choice was made because it is easier for a user to start it with one line of code than for the code to internally handle different possible starting states (after all, someone may want the proxy started but paused at first or configured in a specific way?) and because the a/sync stuff was funnier. Life is unfair ... Or maybe an idea is floating in the air?
    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());
    A programmatic interface with enums is also available.

    • 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

    • Constructor Detail

      • ZProxy

        @Deprecated
public ZProxy​(ZAgent.SelectorCreator selector,
              ZProxy.Proxy creator,
              java.lang.String motdelafin,
              java.lang.Object... args)
        Deprecated.
        use ZProxy(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.
        use ZProxy(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.
        use ZProxy(ZContext, String, Proxy, Pump, String, Object...) instead.
        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 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 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 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​(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 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.

    • 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.
        use newZProxy(ZContext, String, Proxy, String, Object...) instead.
        Creates a new proxy in a ZeroMQ way. This proxy will be less efficient than the low-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 the low-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.
        use newProxy(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 commands CONFIG and RESTART.
        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 commands CONFIG and RESTART.
        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 commands CONFIG and RESTART.
        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.