class Qpid::Messaging::Session

A Session represents a distinct conversation between end points.

Public Instance Methods

acknowledge(args = {}) click to toggle source

Acknowledges one or more outstanding messages that have been received on this session.

Arguments

  • :message - if specified, then only the Message specified is acknowledged

  • :sync - if true then the call will block until processed by the server (def. false)

Examples

session.acknowledge                     # acknowledges all received messages
session.acknowledge :message => message # acknowledge one message
session.acknowledge :sync => true       # blocks until the call completes
# File qpid/ruby/lib/qpid_messaging/session.rb, line 169
def acknowledge(args = {})
  sync = args[:sync] || false
  message = args[:message] if args[:message]

  unless message.nil?
    @session_impl.acknowledge message.message_impl, sync
  else
    @session_impl.acknowledge sync
  end
end
close() click to toggle source

Closes the Session and all associated Sender and Receiver instances.

NOTE: All Session instances for a Connection are closed when the Connection is closed.

# File qpid/ruby/lib/qpid_messaging/session.rb, line 144
def close; @session_impl.close; end
commit() click to toggle source

Commits any pending transactions for a transactional session.

# File qpid/ruby/lib/qpid_messaging/session.rb, line 147
def commit; @session_impl.commit; end
connection() click to toggle source

Returns the Connection associated with this session.

# File qpid/ruby/lib/qpid_messaging/session.rb, line 39
def connection
  @connection
end
create_receiver(address) click to toggle source

Creates a new endpoint for receiving messages.

The address can either be an instance Address or else a string that describes an address endpoint.

Arguments

  • address The end point address.

Examples

receiver = session.create_receiver "my-queue"
# File qpid/ruby/lib/qpid_messaging/session.rb, line 103
def create_receiver(address)
  result        = nil
  receiver_impl = nil

  if address.class == Qpid::Messaging::Address
    address_impl = address.address_impl
    receiver_impl = @session_impl.createReceiver address_impl
  else
    receiver_impl = @session_impl.createReceiver(address)
  end

  receiver_name = receiver_impl.getName

  @receivers[receiver_name] = Qpid::Messaging::Receiver.new self, receiver_impl

  @receivers[receiver_name]
end
create_sender(address) click to toggle source

Creates a new endpoint for sending messages.

The address can either be an instance Address or else a string that describes an address endpoint.

Arguments

  • address The end point address.

Examples

sender = session.create_sender "my-queue;{create:always}"
# File qpid/ruby/lib/qpid_messaging/session.rb, line 56
def create_sender(address)
  _address = address

  if address.class == Qpid::Messaging::Address
    _address = address.address_impl
  end

  sender_impl = @session_impl.createSender(_address)
  sender_name = sender_impl.getName

  @senders[sender_name] = Qpid::Messaging::Sender.new(self, sender_impl)

  @senders[sender_name]
end
errors() click to toggle source

If the Session has been rendered invalid due to some exception, this method will result in that exception being raised.

If none have occurred, then no exceptions are raised.

Examples

if @session.errors?
  begin
    @session.errors
  rescue Exception => error
    puts "An error occurred: #{error}"
  end
end
# File qpid/ruby/lib/qpid_messaging/session.rb, line 260
def errors; @session_impl.checkError; end
errors?() click to toggle source

Returns true if there were exceptions on this session.

Examples

puts "There were session errors." if @session.errors?
# File qpid/ruby/lib/qpid_messaging/session.rb, line 244
def errors?; @session_impl.hasError; end
next_receiver(timeout = Qpid::Messaging::Duration::FOREVER, &block) click to toggle source

Fetches the Receiver for the next message.

Arguments

  • timeout - time to wait for a Receiver before timing out

Examples

recv = session.next_receiver # wait forever for the next +Receiver+
# execute a block on the next receiver
session.next_receiver do |recv|
  msg = recv.get
  puts "Received message: #{msg.content}"
end
# File qpid/ruby/lib/qpid_messaging/session.rb, line 228
def next_receiver(timeout = Qpid::Messaging::Duration::FOREVER, &block)
  receiver_impl = @session_impl.nextReceiver(timeout.duration_impl)

  unless receiver_impl.nil?
    recv = Qpid::Messaging::Receiver.new self, receiver_impl
    block.call recv unless block.nil?
  end

  return recv
end
receivable() click to toggle source

Returns the total number of receivable messages, and messages already received, by Receiver instances associated with this Session.

# File qpid/ruby/lib/qpid_messaging/session.rb, line 208
def receivable; @session_impl.getReceivable; end
receiver(name) click to toggle source

Retrieves the Receiver with the specified name.

The Receiver must have been previously created using the create_receiver method.

Arguments

  • name The Receiver name.

Examples

receiver = session.receiver "my-queue"
# File qpid/ruby/lib/qpid_messaging/session.rb, line 134
def receiver(name)
  raise Qpid::Messaging::KeyError, "No such receiver: #{name}" unless @receivers.has_key? name

  @receivers[name]
end
reject(message) click to toggle source

Rejects the specified message. A rejected message will not be redelivered.

NOTE: A message cannot be rejected once it has been acknowledged.

# File qpid/ruby/lib/qpid_messaging/session.rb, line 184
def reject(message); @session_impl.reject message.message_impl; end
release(message) click to toggle source

Releases the message, which allows the broker to attempt to redeliver it.

NOTE: A message connot be released once it has been acknowled.

# File qpid/ruby/lib/qpid_messaging/session.rb, line 190
def release(message); @session_impl.release message.message_impl; end
rollback() click to toggle source

Rolls back any uncommitted transactions on a transactional session.

# File qpid/ruby/lib/qpid_messaging/session.rb, line 150
def rollback; @session_impl.rollback; end
sender(name) click to toggle source

Retrieves the Sender with the specified name.

The Sender must have been previously created using the create_sender method.

Arguments

  • name The Sender name.

Examples

sender = session.sender "my-queue"
# File qpid/ruby/lib/qpid_messaging/session.rb, line 84
def sender(name)
  raise Qpid::Messaging::KeyError, "No such sender: #{name}" unless @senders.has_key? name

  @senders[name]
end
sync(args = {}) click to toggle source

Requests synchronization with the server.

Arguments

  • :block - if true then the call blocks until the server acknowledges it (def. false)

# File qpid/ruby/lib/qpid_messaging/session.rb, line 201
def sync(args = {})
  block = args[:block] || false
  @session_impl.sync block
end
unsettled_acks() click to toggle source

Returns the number of messages that have been acknowledged by this session whose acknowledgements have not been confirmed as processed by the server.

# File qpid/ruby/lib/qpid_messaging/session.rb, line 212
def unsettled_acks; @session_impl.getUnsettledAcks; end