class Qpid::Messaging::Connection

A Connection represents a network connection to a remote endpoint.

Public Class Methods

new(opts = {}) click to toggle source

Creates a connection object. Raises a MessagingError if an invalid connection option is used.


  • :url - the URL for the broker

  • :options - connection options

Controlling Reconnect Behavior

The following connection options can be used to configure the reconnection behavior for this connection.

  • :username - the authentication username

  • :password - the authentication password

  • :heartbeat

  • :tcp_nodelay

  • :sasl_mechanism

  • :sasl_service

  • :sasl_min_ssf

  • :sasl_max_ssf

  • :transport

  • :reconnect - indicates whether to attempt reconnections

  • :reconnect_timeout - the number of seconds to attempt reconnecting

  • :reconnect_limit - the number of retries before reporting failure

  • :reconnect_interval_min - initial delay, in seconds, before attempting a reconnection

  • :reconnect_interval_max - number of seconds to wait before additional reconnect attempts

  • :reconnect_interval - shorthand for setting both min and max values

  • :reconnect_urls - a list of alternate URLs to use for reconnection attempts


# creates a connection to the broker running local *localhost*
conn =
# creates a connection to ** on port *5672*
conn = :url => ""
# creates a connection to localhost with the specified authentication credentials
conn = :options => {:username => "login", :password => "password"}
# File qpid/ruby/lib/qpid_messaging/connection.rb, line 68
def initialize(opts = {})
  @url = opts[:url] || "localhost"
  @options = Qpid::Messaging.stringify(opts[:options] || {})
  @connection_impl = opts[:impl] ||, @options)

Public Instance Methods

authenticated_username() click to toggle source

Returns the username used to authenticate with the connection.

If the connection did not user authentication credentials, then the username returned is “anonymous”.


# create a new connection for user "qpiduser"
conn = :username => "qpiduser"
# displays the authenticate username
puts "Connected as #{conn.authenticated_username}" # should say 'qpiduser'
# File qpid/ruby/lib/qpid_messaging/connection.rb, line 171
def authenticated_username; @connection_impl.getAuthenticatedUsername if open?; end
close() click to toggle source

Closes the connection.


# close a connection
# File qpid/ruby/lib/qpid_messaging/connection.rb, line 105
def close; @connection_impl.close; end
create_session(args = {}) click to toggle source

Creates a new session.


  • :name - specifies the name for this session

  • :transactional - if true then a creates a transaction session (def. false)


# create a session named 'session1'
session = conn.create_session :name => "session1"
# create a transactional session
session = conn.create_session :transaction => true
# File qpid/ruby/lib/qpid_messaging/connection.rb, line 121
def create_session(args = {})
  name = args[:name] || ""
  if open?
    if args[:transactional]
      session = @connection_impl.createTransactionalSession name
      session = @connection_impl.createSession name
    return, session)
    raise "No connection available."
open() click to toggle source

Establishes the connection.


# open a connection if it's not already open unless
# File qpid/ruby/lib/qpid_messaging/connection.rb, line 85
def open
open?() click to toggle source

Reports whether the connection is open.


# close the connection if it's not already closed
conn.close if
# File qpid/ruby/lib/qpid_messaging/connection.rb, line 96
def open?; true && !@connection_impl.nil? && @connection_impl.isOpen; end
session(name) click to toggle source

Returns a Session with the given name. Raises an exception if no session with the given name exists.


  • name - the existing session's name


# retrieve a session named 'mysession' from the current connection
name = "my-session"
# if no such session exists then catchh the exception raised
  session = conn.session name
rescue MessagingException => error
   puts "No such session: #{name}."
# File qpid/ruby/lib/qpid_messaging/connection.rb, line 153
def session name
  session_impl = @connection_impl.getSession name self, session_impl if session_impl