Module: OnStomp::Interfaces::FrameMethods

Included in:
Client, Components::Scopes::HeaderScope, Components::Scopes::ReceiptScope, Components::Scopes::TransactionScope, Failover::Client
Defined in:
lib/onstomp/interfaces/frame_methods.rb

Overview

Mixin for clients to provide methods that create and transmit STOMP frames.

Instance Method Summary collapse

Instance Method Details

#abort(tx_id, headers = {}) ⇒ OnStomp::Components::Frame

Transmits an ABORT frame generated by the client's connection to rollback a transaction.

Examples:

client.begin 't-1234'
client.send '/queue/test', 'hello transaction!', :transaction => 't-1234'
client.abort 't-1234'

Parameters:

  • tx_id (String) —

    identifier for the transaction

  • headers ({#to_sym => #to_s}) (defaults to: {}) —

    additional headers to include in the frame

Options Hash (headers):

  • :receipt (String) —

    A receipt ID for the frame, this will be matched by the :'receipt-id' header in the broker's RECEIPT response.

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support ABORT frames

See Also:



194
195
196
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 194

def abort tx_id, headers={}
  transmit connection.abort_frame(tx_id, headers)
end

#ack(message_frame, headers = {}) ⇒ OnStomp::Components::Frame #ack(message_id, headers = {}) ⇒ OnStomp::Components::Frame #ack(message_id, subscription_id, headers = {}) ⇒ OnStomp::Components::Frame

Transmits an ACK frame generated by the client's connection.

Overloads:

  • #ack(message_frame, headers = {}) ⇒ OnStomp::Components::Frame
    Note:

    Users should use this form whenever possible as it will work with STOMP 1.0 and 1.1 connections.

    Generates an ACK frame for the given MESSAGE frame.

    Examples:

    client.subscribe '/queue/test', :ack => 'client' do |m|
  if m[:'x-of-interest-to-me'] == 'hells yes'
    client.ack m
  end
end

    Parameters:

    • message_frame (OnStomp::Components::Frame) —

      the MESSAGE frame to acknowledge.

    • headers ({#to_sym => #to_s}) (defaults to: {}) —

      additional headers to include in the frame

    Returns:

  • #ack(message_id, headers = {}) ⇒ OnStomp::Components::Frame
    Note:

    This form will raise an ArgumentError with STOMP 1.1 connections as a subscription ID is also required to ACK a received MESSAGE.

    Generates an ACK frame for the given message-id.

    Examples:

    client.subscribe '/queue/test', :ack => 'client' do |m|
  if m[:'x-of-interest-to-me'] == 'hells yes'
    client.ack m[:'message-id']
  end
end

    Parameters:

    • message_id (String) —

      message-id header of MESSAGE frame to acknowledge.

    • headers ({#to_sym => #to_s}) (defaults to: {}) —

      additional headers to include in the frame

    Returns:

  • #ack(message_id, subscription_id, headers = {}) ⇒ OnStomp::Components::Frame
    Note:

    This form should be used with STOMP 1.1 connections when it is not possible to provide the actual MESSAGE frame.

    Generates an ACK frame for the given message-id and subscription.

    Examples:

    client.subscribe '/queue/test', :ack => 'client' do |m|
  if m[:'x-of-interest-to-me'] == 'hells yes'
    client.ack m[:'message-id'], m[:subscription]
  end
end

    Parameters:

    • message_id (String) —

      message-id header of MESSAGE frame to acknowledge.

    • subscription_id (String) —

      subscription header of MESSAGE frame to acknowledge.

    • headers ({#to_sym => #to_s}) (defaults to: {}) —

      additional headers to include in the frame

    Returns:

Parameters:

  • headers (Hash) —

    a customizable set of options

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support ACK frames

See Also:



300
301
302
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 300

def ack *args
  transmit connection.ack_frame(*args)
end

#beat ⇒ OnStomp::Components::Frame

Transmits a client heartbeat frame generated by the client's connection.

Examples:

# If it's been a while since you've sent any data to the broker:
client.beat
# Now the broker knows you're still listening, nay hanging on its every
# every word.

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support heartbeat frames



357
358
359
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 357

def beat
  transmit connection.heartbeat_frame
end

#begin(tx_id, headers = {}) ⇒ OnStomp::Components::Frame

Transmits a BEGIN frame generated by the client's connection to start a transaction.

Examples:

client.begin 't-1234'
client.send '/queue/test', 'hello transaction!', :transaction => 't-1234'
client.commit 't-1234'

Parameters:

  • tx_id (String) —

    identifier for the transaction

  • headers ({#to_sym => #to_s}) (defaults to: {}) —

    additional headers to include in the frame

Options Hash (headers):

  • :receipt (String) —

    A receipt ID for the frame, this will be matched by the :'receipt-id' header in the broker's RECEIPT response.

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support BEGIN frames

See Also:



172
173
174
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 172

def begin tx_id, headers={}
  transmit connection.begin_frame(tx_id, headers)
end

#commit(tx_id, headers = {}) ⇒ OnStomp::Components::Frame

Transmits a COMMIT frame generated by the client's connection to complete a transaction.

Examples:

client.begin 't-1234'
client.send '/queue/test', 'hello transaction!', :transaction => 't-1234'
client.commit 't-1234'

Parameters:

  • tx_id (String) —

    identifier for the transaction

  • headers ({#to_sym => #to_s}) (defaults to: {}) —

    additional headers to include in the frame

Options Hash (headers):

  • :receipt (String) —

    A receipt ID for the frame, this will be matched by the :'receipt-id' header in the broker's RECEIPT response.

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support COMMIT frames

See Also:



216
217
218
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 216

def commit tx_id, headers={}
  transmit connection.commit_frame(tx_id, headers)
end

#disconnect(headers = {}) ⇒ OnStomp::Components::Frame

Transmits a DISCONNECT frame generated by the client's connection to end the STOMP session.

Examples:

client.connect
client.send '/queue/test', 'a quick message'
client.disconnect

Parameters:

  • headers ({#to_sym => #to_s}) (defaults to: {}) —

    additional headers to include in the frame

Options Hash (headers):

  • :receipt (String) —

    A receipt ID for the frame, this will be matched by the :'receipt-id' header in the broker's RECEIPT response.

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support DISCONNECT frames



235
236
237
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 235

def disconnect headers={}
  transmit connection.disconnect_frame headers
end

#nack(message_frame, headers = {}) ⇒ OnStomp::Components::Frame #nack(message_id, subscription_id, heders = {}) ⇒ OnStomp::Components::Frame

Transmits a NACK frame generated by the client's connection.

Overloads:

  • #nack(message_frame, headers = {}) ⇒ OnStomp::Components::Frame

    Generates a NACK frame for the given MESSAGE frame.

    Examples:

    client.subscribe '/queue/test', :ack => 'client' do |m|
  if m[:'x-of-interest-to-me'] == 'hells no!'
    client.nack m
  end
end

    Parameters:

    • message_frame (OnStomp::Components::Frame) —

      the MESSAGE frame to un-acknowledge.

    • headers ({#to_sym => #to_s}) (defaults to: {}) —

      additional headers to include in the frame

    Returns:

  • #nack(message_id, subscription_id, heders = {}) ⇒ OnStomp::Components::Frame

    Generates a NACK frame for the given message-id and subscription.

    Examples:

    client.subscribe '/queue/test', :ack => 'client' do |m|
  if m[:'x-of-interest-to-me'] == 'hells no!'
    client.nack m[:'message-id'], m[:subscription]
  end
end

    Parameters:

    • message_id (String) —

      message-id header of MESSAGE frame to un-acknowledge.

    • subscription_id (String) —

      subscription header of MESSAGE frame to un-acknowledge.

    • headers ({#to_sym => #to_s}) —

      additional headers to include in the frame

    Returns:

Parameters:

  • headers (Hash) —

    a customizable set of options

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support NACK frames

See Also:



343
344
345
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 343

def nack *args
  transmit connection.nack_frame(*args)
end

#send(dest, body, headers = {}) {|receipt| ... } ⇒ OnStomp::Components::Frame Also known as: puts

Transmits a SEND frame generated by the client's connection

Examples:

# Transmit a simple SEND frame to the broker
client.send '/queue/example', 'Hello STOMP'

# Everything's better with umlauts.
client.send '/topic/example', "Hëllo Wörld",
  :'content-type' => 'text/plain;charset=UTF-8'

# Get a receipt for the SEND frame
client.send '/queue/example', "Did you get that thing I sent you?" do |r|
  puts "The broker received our SEND frame"
end

Parameters:

  • dest (String) —

    destination for the frame

  • body (String) —

    body of the frame

  • headers ({#to_sym => #to_s}) (defaults to: {}) —

    additional headers to include in the frame

Options Hash (headers):

  • :'content-type' (String) —

    The content type of the SEND frame's body. If the body is text (ie: has a non-binary encoding) onstomp will set the :'content-type' header to 'text/plain' if it has not been set. See Encodings for more details.

  • :receipt (String) —

    A receipt ID for the frame, this will be matched by the :'receipt-id' header in the broker's RECEIPT response.

  • :transaction (String) —

    The ID of an existing transaction to add this frame to.

  • :'content-length' (String) —

    If you set this header, it will be overwritten, so save your fingers from a few keystrokes by not setting it. All SEND frames generated by onstomp will have a :'content-length' header.

Yields:

  • (receipt) —

    block to invoke when a RECEIPT frame is received for the transmitted SEND frame

Yield Parameters:

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support SEND frames



59
60
61
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 59

def send dest, body, headers={}, &cb
  transmit connection.send_frame(dest, body, headers), :receipt => cb
end

#subscribe(dest, headers = {}) {|message| ... } ⇒ OnStomp::Components::Frame

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.

Examples:

# A basic subscription
client.subscribe '/queue/example' do |m|
  puts "Got a MESSAGE: #{m.body}"
end

# ACK our MESSAGE frames
client.subscribe '/queue/example', :ack => 'client' do |m|
  client.ack m
  puts "Got (and ACK'd) a MESSAGE: #{m.body}"
end

Parameters:

  • dest (String) —

    destination for the frame

  • headers ({#to_sym => #to_s}) (defaults to: {}) —

    additional headers to include in the frame

Options Hash (headers):

  • :id (String) —

    A unique ID for the subscription. If you do not set this header, an subscription ID will be automatically generated ensuring that all onstomp SUBSCRIBE frames have an ID.

  • :ack (String) — default: 'auto' —

    The ack mode to use with this subscription. A value of 'auto' means MESSAGE frames are assumed received and no ACK frame is necessary. A value of 'client' or 'client-individual' means all MESSAGE frames should be acknowledged with an ACK (or un-acknowledged with a NACK.)

  • :selector (String) —

    A SQL style filter to use against MESSAGE frames (the form and availability of this will vary by broker.)

  • :receipt (String) —

    A receipt ID for the frame, this will be matched by the :'receipt-id' header in the broker's RECEIPT response.

Yields:

  • (message) —

    block to invoke for every MESSAGE frame received on the subscription

Yield Parameters:

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support SUBSCRIBE frames

See Also:



121
122
123
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 121

def subscribe dest, headers={}, &cb
  transmit connection.subscribe_frame(dest, headers), :subscribe => cb
end

#unsubscribe(subscribe_frame, headers = {}) ⇒ OnStomp::Components::Frame #unsubscribe(id, headers = {}) ⇒ OnStomp::Components::Frame

Transmits an UNSUBSCRIBE frame generated by the client's connection.

Overloads:

  • #unsubscribe(subscribe_frame, headers = {}) ⇒ OnStomp::Components::Frame

    Generates an UNSUBSCRIBE frame to match the given SUBSCRIBE frame

    Examples:

    sub = client.subscribe('/queue/test') { |m| ... }
client.unsubscribe sub

    Parameters:

    • subscribe_frame (OnStomp::Components::Frame)
    • headers ({#to_sym => #to_s}) (defaults to: {}) —

      optional headers to include in the UNSUBSCRIBE frame

  • #unsubscribe(id, headers = {}) ⇒ OnStomp::Components::Frame

    Generates an UNSUBSCRIBE frame with the given id

    Examples:

    client.subscribe('/queue/test', :id => 's-1234') { |m| ... }
client.unsubscribe 's-1234'

    Parameters:

    • id (String)
    • headers ({#to_sym => #to_s}) (defaults to: {}) —

      optional headers to include in the UNSUBSCRIBE frame

Parameters:

  • headers (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (headers):

  • :receipt (String) —

    A receipt ID for the frame, this will be matched by the :'receipt-id' header in the broker's RECEIPT response.

Returns:

Raises:

  • OnStomp::UnsupportedCommandError if the connection does not support UNSUBSCRIBE frames

See Also:



150
151
152
 
# File 'lib/onstomp/interfaces/frame_methods.rb', line 150

def unsubscribe frame_or_id, headers={}
  transmit connection.unsubscribe_frame(frame_or_id, headers)
end