Module: Stomper::Extensions::Common

Included in:
Connection, Scopes::HeaderScope
Defined in:
lib/stomper/extensions/common.rb

Overview

Provides the common interface for a Connection object.

Defined Under Namespace

Modules: V1_1

Constant Summary collapse

EXTEND_BY_VERSION =

A mapping between protocol versions and modules to include

{
  '1.0' => [ ],
  '1.1' => [ ::Stomper::Extensions::Common::V1_1 ]
}

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.extend_by_protocol_version(instance, version) ⇒ Object

Extends an object with any additional modules that are appropriate for the Stomp protocol being used.



7
8
9
10
11
12
13
 
# File 'lib/stomper/extensions/common.rb', line 7

def self.extend_by_protocol_version(instance, version)
  if EXTEND_BY_VERSION[version]
    EXTEND_BY_VERSION[version].each do |mod|
      instance.extend mod
    end
  end
end

Instance Method Details

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

Transmits an ABORT frame to the broker to rollback a transaction named by tx_id. When directly handling transaction management in this fashion, it is up to you to ensure the uniqueness of transaction ids, that frames within this transaction have their transaction header set, and that transactions are appropriately committed or aborted.

Parameters:

  • tx_id (String) —

    ID of the transaction to abort

  • additional ({Symbol => String}) —

    headers to include in the generated frame

Returns:

See Also:



94
95
96
 
# File 'lib/stomper/extensions/common.rb', line 94

def abort(tx_id, headers={})
  transmit create_frame('ABORT', headers, {:transaction => tx_id})
end

#ack(message, headers = {}) ⇒ Stomper::Frame #ack(message_id, headers = {}) ⇒ Stomper::Frame

Note:

If the negotiated Stomp protocol version is 1.1, this method will be overridden by Stomper::Extensions::Common::V1_1#ack

Transmits an ACK frame to the broker to acknowledge that a corresponding MESSAGE frame has been processed by the client.

Examples:

Gonna need some examples for this one…

Overloads:

  • #ack(message, headers = {}) ⇒ Stomper::Frame

    Parameters:

    • message (Stomper::Frame) —

      the MESSAGE frame to acknowledge

    • headers ({Object => String}) (defaults to: {}) —

      optional headers to include with the ACK frame

  • #ack(message_id, headers = {}) ⇒ Stomper::Frame

    Parameters:

    • message_id (String) —

      the ID of a MESSAGE frame to acknowledge

    • headers ({Object => String}) (defaults to: {}) —

      optional headers to include with the ACK frame

Returns:

Raises:

  • (::ArgumentError) 


136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/stomper/extensions/common.rb', line 136

def ack(*args)
  headers = args.last.is_a?(Hash) ? args.pop : {}
  m_id = args.shift
  if m_id.is_a?(::Stomper::Frame)
    m_id = m_id[:'message-id']
  end
  m_headers = [ [:'message-id', m_id] ].inject({}) do |mh, (k,v)|
    mh[k] = v unless v.nil? || v.empty?
    mh
  end
  an_frame = create_frame('ACK', headers, m_headers)
  raise ::ArgumentError, 'message ID could not be determined' if an_frame[:'message-id'].nil? || an_frame[:'message-id'].empty?
  transmit an_frame
end

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

Transmits a BEGIN frame to the broker to start a transaction named by tx_id. When directly handling transaction management in this fashion, it is up to you to ensure the uniqueness of transaction ids, that frames within this transaction have their transaction header set, and that transactions are appropriately committed or aborted.

Parameters:

  • tx_id (String) —

    ID of the transaction to begin

  • additional ({Symbol => String}) —

    headers to include in the generated frame

Returns:

See Also:



79
80
81
 
# File 'lib/stomper/extensions/common.rb', line 79

def begin(tx_id, headers={})
  transmit create_frame('BEGIN', headers, {:transaction => tx_id})
end

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

Transmits a COMMIT frame to the broker to complete a transaction named by tx_id. When directly handling transaction management in this fashion, it is up to you to ensure the uniqueness of transaction ids, that frames within this transaction have their transaction header set, and that transactions are appropriately committed or aborted.

Parameters:

  • tx_id (String) —

    ID of the transaction to complete

  • additional ({Symbol => String}) —

    headers to include in the generated frame

Returns:

See Also:



109
110
111
 
# File 'lib/stomper/extensions/common.rb', line 109

def commit(tx_id, headers={})
  transmit create_frame('COMMIT', headers, {:transaction => tx_id})
end

#disconnect(headers = {}) ⇒ Object

Disconnects from the broker. This is polite disconnect, in that it first transmits a DISCONNECT frame before closing the underlying socket. If the broker and client are using the Stomp 1.1 protocol, a receipt can be requested for the DISCONNECT frame, and the connection will remain active until the receipt is received or the broker closes the connection on its end.

Parameters:

  • an ({Symbol => String}) —

    optional set of headers to include in the DISCONNECT frame (these can include event handlers, such as :on_receipt)



120
121
122
 
# File 'lib/stomper/extensions/common.rb', line 120

def disconnect(headers={})
  transmit create_frame('DISCONNECT', headers, {})
end

#nack(*args) ⇒ Object

Note:

If the negotiated Stomp protocol version is 1.1, this method will be overridden by Stomper::Extensions::Common::V1_1#nack

Always raises an error because the NACK frame is only available to connections using version 1.1 of the Stomp protocol.

Raises:

See Also:

  • Protocol_1_1#nack


157
158
159
 
# File 'lib/stomper/extensions/common.rb', line 157

def nack(*args)
  raise ::Stomper::Errors::UnsupportedCommandError, 'NACK'
end

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

Note:

You will need to use __send__ if you want the behavior of Object#send

Transmits a SEND frame to the broker with the specified destination, body and headers. If a block is given, a receipt header will be included in the frame and the block will be invoked when the corresponding RECEIPT frame is received from the broker. The naming of this method bothers me as it overwrites a core Ruby method but doing so maintains the consistency of this interface. If you want to pass a message ala Object#send, use the __send__ method instead.

Parameters:

  • dest (String) —

    the destination for the SEND frame to be delivered to

  • body (String) —

    the body of the SEND frame

  • additional ({Symbol => String}) —

    headers to include in the generated frame

Yields:

  • (receipt) —

    invoked when the receipt for this SEND frame has been received

Yield Parameters:

Returns:



30
31
32
33
 
# File 'lib/stomper/extensions/common.rb', line 30

def send(dest, body, headers={}, &block)
  scoped_to = block ? with_receipt(&block) : self
  scoped_to.transmit create_frame('SEND', headers, { :destination => dest }, body)
end

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

Transmits a SUBSCRIBE frame to the broker with the specified destination and headers. If a block is given, it will be invoked every time a MESSAGE frame is received from the broker for this subscription.

Parameters:

  • dest (String) —

    the destination for the SEND frame to be delivered to

  • additional ({Symbol => String}) —

    headers to include in the generated frame

Yields:

  • (message) —

    invoked when a MESSAGE frame for this subscription is received

Yield Parameters:

Returns:



44
45
46
47
48
49
50
51
52
 
# File 'lib/stomper/extensions/common.rb', line 44

def subscribe(dest, headers={}, &block)
  ::Stomper::Support.keys_to_sym!(headers)
  if headers[:id].nil? || headers[:id].empty?
    headers[:id] = ::Stomper::Support.next_serial
  end
  subscribe = create_frame('SUBSCRIBE', headers, { :destination => dest })
  subscription_manager.add(subscribe, block) if block
  transmit subscribe
end

#unsubscribe(frame_or_id, headers = {}) ⇒ Stomper::Frame

Transmits an UNSUBSCRIBE frame to the broker for the supplied subscription ID, or SUBSCRIBE frame.

Parameters:

  • frame_or_id (Stomper::Frame, String) —

    the subscription ID or SUBSCRIBE frame to unsubscribe from

Returns:

Raises:

  • (ArgumentError) —

    if subscription ID cannot be determined.



60
61
62
63
64
65
66
 
# File 'lib/stomper/extensions/common.rb', line 60

def unsubscribe(frame_or_id, headers={})
  sub_id = frame_or_id.is_a?(::Stomper::Frame) ? frame_or_id[:id] : frame_or_id
  raise ArgumentError, 'subscription ID could not be determined' if sub_id.nil? || sub_id.empty?
  subscription_manager.remove(sub_id).map do |id|
    transmit create_frame('UNSUBSCRIBE', headers, { :id => id })
  end.last
end