Package org.zeromq

Class ZMsg

  • All Implemented Interfaces:
    java.lang.Iterable<ZFrame>, java.util.Collection<ZFrame>, java.util.Deque<ZFrame>, java.util.Queue<ZFrame>

    public class ZMsg
    extends java.lang.Object
    implements java.lang.Iterable<ZFrame>, java.util.Deque<ZFrame>
    The ZMsg class provides methods to send and receive multipart messages across 0MQ sockets. This class provides a list-like container interface, with methods to work with the overall container. ZMsg messages are composed of zero or more ZFrame objects.
     // Send a simple single-frame string message on a ZMQSocket "output" socket object
     ZMsg.newStringMsg("Hello").send(output);
    
     // Add several frames into one message
     ZMsg msg = new ZMsg();
     for (int i = 0 ; i < 10 ; i++) {
         msg.addString("Frame" + i);
     }
     msg.send(output);
    
     // Receive message from ZMQSocket "input" socket object and iterate over frames
     ZMsg receivedMessage = ZMsg.recvMsg(input);
     for (ZFrame f : receivedMessage) {
         // Do something with frame f (of type ZFrame)
     }
     
    Based on zmsg.c in czmq
    • Field Detail

      • frames

        private final java.util.ArrayDeque<ZFrame> frames
        Hold internal list of ZFrame objects
    • Constructor Detail

      • ZMsg

        public ZMsg()
        Class Constructor
    • Method Detail

      • destroy

        public void destroy()
        Destructor. Explicitly destroys all ZFrames contains in the ZMsg
      • contentSize

        public long contentSize()
        Returns:
        total number of bytes contained in all ZFrames in this ZMsg
      • addString

        public ZMsg addString​(java.lang.String str)
        Add a String as a new ZFrame to the end of list
        Parameters:
        str - String to add to list
      • duplicate

        public ZMsg duplicate()
        Creates copy of this ZMsg. Also duplicates all frame content.
        Returns:
        The duplicated ZMsg object, else null if this ZMsg contains an empty frame set
      • wrap

        public ZMsg wrap​(ZFrame frame)
        Push frame plus empty frame to front of message, before 1st frame. Message takes ownership of frame, will destroy it when message is sent.
        Parameters:
        frame -
      • unwrap

        public ZFrame unwrap()
        Pop frame off front of message, caller now owns frame. If next frame is empty, pops and destroys that empty frame (e.g. useful when unwrapping ROUTER socket envelopes)
        Returns:
        Unwrapped frame
      • send

        public boolean send​(ZMQ.Socket socket)
        Send message to 0MQ socket.
        Parameters:
        socket - 0MQ socket to send ZMsg on.
        Returns:
        true if send is success, false otherwise
      • send

        public boolean send​(ZMQ.Socket socket,
                            boolean destroy)
        Send message to 0MQ socket, destroys contents after sending if destroy param is set to true. If the message has no frames, sends nothing but still destroy()s the ZMsg object
        Parameters:
        socket - 0MQ socket to send ZMsg on.
        Returns:
        true if send is success, false otherwise
      • recvMsg

        public static ZMsg recvMsg​(ZMQ.Socket socket)
        Receives message from socket, returns ZMsg object or null if the recv was interrupted. Does a blocking recv, if you want not to block then use the ZLoop class or ZMQ.Poller to check for socket input before receiving or recvMsg with flag ZMQ.DONTWAIT.
        Parameters:
        socket -
        Returns:
        ZMsg object, null if interrupted
      • recvMsg

        public static ZMsg recvMsg​(ZMQ.Socket socket,
                                   boolean wait)
        Receives message from socket, returns ZMsg object or null if the recv was interrupted.
        Parameters:
        socket -
        wait - true to wait for next message, false to do a non-blocking recv.
        Returns:
        ZMsg object, null if interrupted
      • recvMsg

        public static ZMsg recvMsg​(ZMQ.Socket socket,
                                   int flag)
        Receives message from socket, returns ZMsg object or null if the recv was interrupted. Setting the flag to ZMQ.DONTWAIT does a non-blocking recv.
        Parameters:
        socket -
        flag - see ZMQ constants
        Returns:
        ZMsg object, null if interrupted
      • recvMsg

        public static void recvMsg​(ZMQ.Socket socket,
                                   int flags,
                                   Consumer<ZMsg> handler,
                                   Consumer<ZMQException> exceptionHandler)
        This API is in DRAFT state and is subject to change at ANY time until declared stable handle incoming message with a handler
        Parameters:
        socket -
        flags - see ZMQ constants
        handler - handler to handle incoming message
        exceptionHandler - handler to handle exceptions
      • recvMsg

        public static void recvMsg​(ZMQ.Socket socket,
                                   int flags,
                                   Consumer<ZMsg> handler)
        This API is in DRAFT state and is subject to change at ANY time until declared stable handle incoming message with a handler
        Parameters:
        socket -
        flags - see ZMQ constants
        handler - handler to handle incoming message
      • save

        public static boolean save​(ZMsg msg,
                                   java.io.DataOutputStream file)
        Save message to an open data output stream. Data saved as: 4 bytes: number of frames For every frame: 4 bytes: byte size of frame data + n bytes: frame byte data
        Parameters:
        msg - ZMsg to save
        file - DataOutputStream
        Returns:
        True if saved OK, else false
      • load

        public static ZMsg load​(java.io.DataInputStream file)
        Load / append a ZMsg from an open DataInputStream
        Parameters:
        file - DataInputStream connected to file
        Returns:
        ZMsg object
      • newStringMsg

        public static ZMsg newStringMsg​(java.lang.String... strings)
        Create a new ZMsg from one or more Strings
        Parameters:
        strings - Strings to add as frames.
        Returns:
        ZMsg object
      • equals

        public boolean equals​(java.lang.Object o)
        Specified by:
        equals in interface java.util.Collection<ZFrame>
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Specified by:
        hashCode in interface java.util.Collection<ZFrame>
        Overrides:
        hashCode in class java.lang.Object
      • dump

        public ZMsg dump​(java.lang.Appendable out)
        Dump the message in human readable format. This should only be used for debugging and tracing, inefficient in handling large messages.
      • dump

        public ZMsg dump()
      • addFirst

        public ZMsg addFirst​(java.lang.String stringValue)
      • addFirst

        public ZMsg addFirst​(byte[] data)
      • addLast

        public ZMsg addLast​(java.lang.String stringValue)
      • addLast

        public ZMsg addLast​(byte[] data)
      • push

        public ZMsg push​(java.lang.String str)
      • push

        public ZMsg push​(byte[] data)
      • add

        public boolean add​(java.lang.String stringValue)
      • add

        public boolean add​(byte[] data)
      • append

        public ZMsg append​(java.lang.String stringValue)
        Adds a string as a new frame in the message.
        Parameters:
        stringValue - the value to add
        Returns:
        this
      • append

        public ZMsg append​(byte[] data)
        Adds bytes as a new frame in the message.
        Parameters:
        data - the value to add
        Returns:
        this
      • iterator

        public java.util.Iterator<ZFrame> iterator()
        Specified by:
        iterator in interface java.util.Collection<ZFrame>
        Specified by:
        iterator in interface java.util.Deque<ZFrame>
        Specified by:
        iterator in interface java.lang.Iterable<ZFrame>
      • addAll

        public boolean addAll​(java.util.Collection<? extends ZFrame> arg0)
        Specified by:
        addAll in interface java.util.Collection<ZFrame>
        Specified by:
        addAll in interface java.util.Deque<ZFrame>
      • clear

        public void clear()
        Specified by:
        clear in interface java.util.Collection<ZFrame>
      • containsAll

        public boolean containsAll​(java.util.Collection<?> arg0)
        Specified by:
        containsAll in interface java.util.Collection<ZFrame>
      • isEmpty

        public boolean isEmpty()
        Specified by:
        isEmpty in interface java.util.Collection<ZFrame>
      • removeAll

        public boolean removeAll​(java.util.Collection<?> arg0)
        Specified by:
        removeAll in interface java.util.Collection<ZFrame>
      • retainAll

        public boolean retainAll​(java.util.Collection<?> arg0)
        Specified by:
        retainAll in interface java.util.Collection<ZFrame>
      • toArray

        public java.lang.Object[] toArray()
        Specified by:
        toArray in interface java.util.Collection<ZFrame>
      • toArray

        public <T> T[] toArray​(T[] arg0)
        Specified by:
        toArray in interface java.util.Collection<ZFrame>
      • add

        public boolean add​(ZFrame e)
        Specified by:
        add in interface java.util.Collection<ZFrame>
        Specified by:
        add in interface java.util.Deque<ZFrame>
        Specified by:
        add in interface java.util.Queue<ZFrame>
      • addFirst

        public void addFirst​(ZFrame e)
        Specified by:
        addFirst in interface java.util.Deque<ZFrame>
      • addLast

        public void addLast​(ZFrame e)
        Specified by:
        addLast in interface java.util.Deque<ZFrame>
      • contains

        public boolean contains​(java.lang.Object o)
        Specified by:
        contains in interface java.util.Collection<ZFrame>
        Specified by:
        contains in interface java.util.Deque<ZFrame>
      • descendingIterator

        public java.util.Iterator<ZFrame> descendingIterator()
        Specified by:
        descendingIterator in interface java.util.Deque<ZFrame>
      • element

        public ZFrame element()
        Specified by:
        element in interface java.util.Deque<ZFrame>
        Specified by:
        element in interface java.util.Queue<ZFrame>
      • getFirst

        public ZFrame getFirst()
        Specified by:
        getFirst in interface java.util.Deque<ZFrame>
      • getLast

        public ZFrame getLast()
        Specified by:
        getLast in interface java.util.Deque<ZFrame>
      • offer

        public boolean offer​(ZFrame e)
        Specified by:
        offer in interface java.util.Deque<ZFrame>
        Specified by:
        offer in interface java.util.Queue<ZFrame>
      • offerFirst

        public boolean offerFirst​(ZFrame e)
        Specified by:
        offerFirst in interface java.util.Deque<ZFrame>
      • offerLast

        public boolean offerLast​(ZFrame e)
        Specified by:
        offerLast in interface java.util.Deque<ZFrame>
      • peek

        public ZFrame peek()
        Specified by:
        peek in interface java.util.Deque<ZFrame>
        Specified by:
        peek in interface java.util.Queue<ZFrame>
      • peekFirst

        public ZFrame peekFirst()
        Specified by:
        peekFirst in interface java.util.Deque<ZFrame>
      • peekLast

        public ZFrame peekLast()
        Specified by:
        peekLast in interface java.util.Deque<ZFrame>
      • poll

        public ZFrame poll()
        Specified by:
        poll in interface java.util.Deque<ZFrame>
        Specified by:
        poll in interface java.util.Queue<ZFrame>
      • pollFirst

        public ZFrame pollFirst()
        Specified by:
        pollFirst in interface java.util.Deque<ZFrame>
      • pollLast

        public ZFrame pollLast()
        Specified by:
        pollLast in interface java.util.Deque<ZFrame>
      • pop

        public ZFrame pop()
        Specified by:
        pop in interface java.util.Deque<ZFrame>
      • popString

        public java.lang.String popString()
        Pop a ZFrame and return the toString() representation of it.
        Returns:
        toString version of pop'ed frame, or null if no frame exists.
      • push

        public void push​(ZFrame e)
        Specified by:
        push in interface java.util.Deque<ZFrame>
      • remove

        public ZFrame remove()
        Specified by:
        remove in interface java.util.Deque<ZFrame>
        Specified by:
        remove in interface java.util.Queue<ZFrame>
      • remove

        public boolean remove​(java.lang.Object o)
        Specified by:
        remove in interface java.util.Collection<ZFrame>
        Specified by:
        remove in interface java.util.Deque<ZFrame>
      • removeFirst

        public ZFrame removeFirst()
        Specified by:
        removeFirst in interface java.util.Deque<ZFrame>
      • removeFirstOccurrence

        public boolean removeFirstOccurrence​(java.lang.Object o)
        Specified by:
        removeFirstOccurrence in interface java.util.Deque<ZFrame>
      • removeLast

        public ZFrame removeLast()
        Specified by:
        removeLast in interface java.util.Deque<ZFrame>
      • removeLastOccurrence

        public boolean removeLastOccurrence​(java.lang.Object o)
        Specified by:
        removeLastOccurrence in interface java.util.Deque<ZFrame>
      • size

        public int size()
        Specified by:
        size in interface java.util.Collection<ZFrame>
        Specified by:
        size in interface java.util.Deque<ZFrame>
      • append

        public ZMsg append​(ZMsg msg)
      • toString

        public java.lang.String toString()
        Returns pretty string representation of multipart message: [ frame0, frame1, ..., frameN ]
        Overrides:
        toString in class java.lang.Object
        Returns:
        toString version of ZMsg object