Package org.zeromq

Class ZMsg

java.lang.Object
org.zeromq.ZMsg
All Implemented Interfaces:
Iterable<ZFrame>, Collection<ZFrame>, Deque<ZFrame>, Queue<ZFrame>

public class ZMsg extends Object implements Iterable<ZFrame>, 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 Details

    • frames

      private final ArrayDeque<ZFrame> frames
      Hold internal list of ZFrame objects
  • Constructor Details

    • ZMsg

      public ZMsg()
      Class Constructor
  • Method Details

    • 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(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, 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(DataInputStream file)
      Load / append a ZMsg from an open DataInputStream
      Parameters:
      file - DataInputStream connected to file
      Returns:
      ZMsg object
    • newStringMsg

      public static ZMsg newStringMsg(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(Object o)
      Specified by:
      equals in interface Collection<ZFrame>
      Overrides:
      equals in class Object
    • hashCode

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

      public ZMsg dump(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(String stringValue)
    • addFirst

      public ZMsg addFirst(byte[] data)
    • addLast

      public ZMsg addLast(String stringValue)
    • addLast

      public ZMsg addLast(byte[] data)
    • push

      public ZMsg push(String str)
    • push

      public ZMsg push(byte[] data)
    • add

      public boolean add(String stringValue)
    • add

      public boolean add(byte[] data)
    • append

      public ZMsg append(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 Iterator<ZFrame> iterator()
      Specified by:
      iterator in interface Collection<ZFrame>
      Specified by:
      iterator in interface Deque<ZFrame>
      Specified by:
      iterator in interface Iterable<ZFrame>
    • addAll

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

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

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

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

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

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

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

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

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

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

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

      public boolean contains(Object o)
      Specified by:
      contains in interface Collection<ZFrame>
      Specified by:
      contains in interface Deque<ZFrame>
    • descendingIterator

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

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

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

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

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

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

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

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

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

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

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

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

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

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

      public 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 Deque<ZFrame>
    • remove

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

      public boolean remove(Object o)
      Specified by:
      remove in interface Collection<ZFrame>
      Specified by:
      remove in interface Deque<ZFrame>
    • removeFirst

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

      public boolean removeFirstOccurrence(Object o)
      Specified by:
      removeFirstOccurrence in interface Deque<ZFrame>
    • removeLast

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

      public boolean removeLastOccurrence(Object o)
      Specified by:
      removeLastOccurrence in interface Deque<ZFrame>
    • size

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

      public ZMsg append(ZMsg msg)
    • toString

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