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.

Options

  • :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

Examples

# creates a connection to the broker running local *localhost*
conn = Qpid::Messaging::Connnection.new
# creates a connection to *broker1.domain.com* on port *5672*
conn = Qpid::Messaging::Connection.new :url => "amqp:tcp:broker1.domain.com:5672"
# creates a connection to localhost with the specified authentication credentials
conn = Qpid::Messaging::Connection.new :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] || Cqpid::Connection.new(@url, @options)
end

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”.

Examples

# create a new connection for user "qpiduser"
conn = Qpid::Messaging::Connection.new :username => "qpiduser"
conn.open
# 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.

Examples

# close a connection
conn.close
# 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.

Arguments

  • :name - specifies the name for this session

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

Examples

# 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
    else
      session = @connection_impl.createSession name
    end
    return Session.new(self, session)
  else
    raise RuntimeError.new "No connection available."
  end
end
open() click to toggle source

Establishes the connection.

Examples

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

Reports whether the connection is open.

Examples

# close the connection if it's not already closed
conn.close if conn.open?
# 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.

Options

  • name - the existing session's name

Examples

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