# -*- encoding: utf-8 -*-

# Mixin for {OnStomp::Client clients} to provide methods that create
# and transmit STOMP {OnStomp::Components::Frame frames}.
module OnStomp::Interfaces::FrameMethods
  # Transmits a SEND frame generated by the client's connection
  # @param [String] dest destination for the frame
  # @param [String] body body of the frame
  # @param [{#to_sym => #to_s}] headers additional headers to include in
  #   the frame
  # @return [OnStomp::Components::Frame] SEND frame
  # @yield [receipt] block to invoke when a RECEIPT frame is received for the
  #   transmitted SEND frame
  # @yieldparam [OnStomp::Components::Frame] receipt RECEIPT for the frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   SEND frames
  def send dest, body, headers={}, &cb
    transmit connection.send_frame(dest, body, headers), :receipt => cb
  end
  alias :puts :send

  # Transmits a SUBSCRIBE frame generated by the client's connection. Depending
  # upon the connection, a subscription can be set to various MESSAGE
  # acknowledgement modes by setting the +:ack+ header.
  # STOMP 1.0 and STOMP 1.1 connections support:
  # * :ack => 'auto'
  #   The broker assumes that MESSAGE frames received through the
  #   subscription have been properly received, the client should NOT attempt
  #   to ACK (or NACK) any of the messages.
  # * :ack => 'client'
  #   The broker assumes that MESSAGE frames should be acknowledged by the
  #   client through the use of ACK frames.
  # STOMP 1.1 connections support:
  # * :ack => 'client-individual'
  #   Upon receiving an ACK frame for a MESSAGE frame, some brokers will
  #   mark the MESSAGE frame and all those sent to the client before it
  #   as acknowledged. This mode indicates that each MESSAGE frame must
  #   be acknowledged by its own ACK frame for the broker can assume the
  #   MESSAGE frame has been received by the client.
  # @param [String] dest destination for the frame
  # @param [{#to_sym => #to_s}] headers additional headers to include in
  #   the frame
  # @return [OnStomp::Components::Frame] SUBSCRIBE frame
  # @yield [message] block to invoke for every MESSAGE frame received on the
  #   subscription
  # @yieldparam [OnStomp::Components::Frame] message MESSAGE frame received on
  #  the subscription
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   SUBSCRIBE frames
  # @see #unsubscribe
  # @see #ack
  # @see #nack
  def subscribe dest, headers={}, &cb
    transmit connection.subscribe_frame(dest, headers), :subscribe => cb
  end
  
  # Transmits an UNSUBSCRIBE frame generated by the client's connection.
  # @overload unsubscribe(subscribe_frame, headers={})
  #   Generates an UNSUBSCRIBE frame to match the given SUBSCRIBE frame
  #   @param [OnStomp::Components::Frame] subscribe_frame
  #   @param [{#to_sym => #to_s}] headers optional headers to include in
  #     the UNSUBSCRIBE frame
  # @overload unsubscribe(id, headers={})
  #   Generates an UNSUBSCRIBE frame with the given id
  #   @param [String] id
  #   @param [{#to_sym => #to_s}] headers optional headers to include in
  #     the UNSUBSCRIBE frame
  # @return [OnStomp::Components::Frame] UNSUBSCRIBE frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   UNSUBSCRIBE frames
  # @see #subscribe
  def unsubscribe frame_or_id, headers={}
    transmit connection.unsubscribe_frame(frame_or_id, headers)
  end
  
  # Transmits a BEGIN frame generated by the client's connection to start
  # a transaction.
  # @param [String] tx_id identifier for the transaction
  # @param [{#to_sym => #to_s}] headers additional headers to include in
  #   the frame
  # @return [OnStomp::Components::Frame] BEGIN frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   BEGIN frames
  # @see #abort
  # @see #commit
  def begin tx_id, headers={}
    transmit connection.begin_frame(tx_id, headers)
  end
  
  # Transmits an ABORT frame generated by the client's connection to rollback
  # a transaction.
  # @param [String] tx_id identifier for the transaction
  # @param [{#to_sym => #to_s}] headers additional headers to include in
  #   the frame
  # @return [OnStomp::Components::Frame] ABORT frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   ABORT frames
  # @see #begin
  # @see #commit
  def abort tx_id, headers={}
    transmit connection.abort_frame(tx_id, headers)
  end
  
  # Transmits a COMMIT frame generated by the client's connection to complete
  # a transaction.
  # @param [String] tx_id identifier for the transaction
  # @param [{#to_sym => #to_s}] headers additional headers to include in
  #   the frame
  # @return [OnStomp::Components::Frame] COMMIT frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   COMMIT frames
  # @see #abort
  # @see #begin
  def commit tx_id, headers={}
    transmit connection.commit_frame(tx_id, headers)
  end

  # Transmits a DISCONNECT frame generated by the client's connection to end
  # the STOMP session.
  # @param [{#to_sym => #to_s}] headers additional headers to include in
  #   the frame
  # @return [OnStomp::Components::Frame] DISCONNECT frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   DISCONNECT frames
  def disconnect headers={}
    transmit connection.disconnect_frame headers
  end

  # Transmits an ACK frame generated by the client's connection.
  # @overload ack(message_frame, headers={})
  #   @note Users should use this form whenever possible as it will work
  #     with STOMP 1.0 and 1.1 connections.
  #   @param [OnStomp::Components::Frame] message_frame the MESSAGE frame to
  #     acknowledge.
  #   @param [{#to_sym => #to_s}] headers additional headers to include in
  #     the frame
  # @overload ack(message_id, headers={})
  #   @note This form will raise an +ArgumentError+ with STOMP 1.1 connections
  #     as a subscription ID is also required to ACK a received MESSAGE.
  #   @param [String] message_id +message-id+ header of MESSAGE frame to
  #     acknowledge.
  #   @param [{#to_sym => #to_s}] headers additional headers to include in
  #     the frame
  # @overload ack(message_id, subscription_id, heders={})
  #   @note This form should be used with STOMP 1.1 connections when it is
  #     not possible to provide the actual MESSAGE frame.
  #   @param [String] message_id +message-id+ header of MESSAGE frame to
  #     acknowledge.
  #   @param [String] subscription_id +subscription+ header of MESSAGE frame to
  #     acknowledge.
  #   @param [{#to_sym => #to_s}] headers additional headers to include in
  #     the frame
  # @return [OnStomp::Components::Frame] ACK frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   ACK frames
  # @see #nack
  def ack *args
    transmit connection.ack_frame(*args)
  end

  # Transmits a NACK frame generated by the client's connection.
  # @overload nack(message_frame, headers={})
  #   Generates a NACK frame for the given MESSAGE frame.
  #   @param [OnStomp::Components::Frame] message_frame the MESSAGE frame to
  #     un-acknowledge.
  #   @param [{#to_sym => #to_s}] headers additional headers to include in
  #     the frame
  # @overload nack(message_id, subscription_id, heders={})
  #   @param [String] message_id +message-id+ header of MESSAGE frame to
  #     un-acknowledge.
  #   @param [String] subscription_id +subscription+ header of MESSAGE frame to
  #     un-acknowledge.
  #   @param [{#to_sym => #to_s}] headers additional headers to include in
  #     the frame
  # @return [OnStomp::Components::Frame] NACK frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   NACK frames
  # @see #ack
  def nack *args
    transmit connection.nack_frame(*args)
  end
  
  # Transmits a client heartbeat frame generated by the client's connection.
  # @return [OnStomp::Components::Frame] heartbeat frame
  # @raise OnStomp::UnsupportedCommandError if the connection does not support
  #   heartbeat frames
  def beat
    transmit connection.heartbeat_frame
  end
end