You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by mc...@apache.org on 2013/02/07 16:50:11 UTC
svn commit: r1443577 - in /qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib: ./
qpid_messaging/
Author: mcpierce
Date: Thu Feb 7 15:50:11 2013
New Revision: 1443577
URL: http://svn.apache.org/viewvc?rev=1443577&view=rev
Log:
QPID-4568: Improved the Ruby rdocs.
Added more detailed examples. Fixed up the rdoc markups to make the docs
more useful to developers. Added a comprehensive example to the
Qpid::Messaging module rdocs.
Modified:
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb
qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging.rb Thu Feb 7 15:50:11 2013
@@ -28,3 +28,56 @@ require 'qpid_messaging/receiver'
require 'qpid_messaging/session'
require 'qpid_messaging/connection'
+module Qpid
+
+ # The Qpid Messaging framework is an enterprise messaging framework
+ # based on the open-source AMQP protocol.
+ #
+ # ==== Example Application
+ #
+ # Here is a simple example application. It creates a link to a broker located
+ # on a system named *broker.myqpiddomain.com*. It then creates a new messaging
+ # queue named "qpid-examples" and publishes a message to it. It then consumes
+ # that same message and closes the connection.
+ #
+ # require 'rubygems'
+ # gem 'qpid_messaging'
+ # require 'qpid_messaging'
+ #
+ # # create a connection, open it and then create a session named "session1"
+ # conn = Qpid::Messaging::Connection.new :name => "broker.myqpiddomain.com"
+ # conn.open
+ # session = conn.create_session "session1"
+ #
+ # # create a sender and a receiver
+ # # the sender marks the queue as one that is deleted when trhe sender disconnects
+ # send = session.create_sender "qpid-examples;{create:always,delete:always}"
+ # recv = session.create_receiver "qpid-examples"
+ #
+ # # create an outgoing message and send it
+ # outgoing = Qpid::Messaging::Message.new :content => "The time is #{Time.new}"
+ # sender.send outgoing
+ #
+ # # set the receiver's capacity to 10 and then check out many messages are pending
+ # recv.capacity = 10
+ # puts "There are #{recv.available} messages waiting." # should report 1 message
+ #
+ # # get the nextwaiting message, which should be in the local queue now,
+ # # and output the contents
+ # incoming = recv.get Qpid::Messaging::Duration::IMMEDIATE
+ # puts "Received the following message: #{incoming.content}"
+ # # the output should be the text that was sent earlier
+ #
+ # # acknowledge the message, letting the sender know the message was received
+ # puts "The sender currently has #{send.unsettled} message(s) pending."
+ # # should report 1 unsettled message
+ # session.acknowledge incoming # acknowledge the received message
+ # puts "Now sender currently has #{send.unsettled} message(s) pending."
+ # # should report 0 unsettled messages
+ #
+ # # close the connection
+ # conn.close
+ #
+ module Messaging; end
+
+end
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/address.rb Thu Feb 7 15:50:11 2013
@@ -24,13 +24,17 @@ module Qpid
# Address represents an address to which messages can be sent or from
# which they can be received.
#
- # An Address can be described using the following pattern:
+ # == The +Address+ String
+ #
+ # An +Address+ can be described using the following pattern:
#
# <address> [ / <subject> ] ; [ { <key> : <value> , ... } ]
#
# where *address* is a simple name and *subject* is a subject or subject
# pattern.
#
+ # === Options
+ #
# The options, enclosed in curly braces, are key:value pairs delimited by
# a comma. The values can be nested maps also enclosed in curly braces.
# Or they can be lists of values, where they are contained within square
@@ -40,44 +44,45 @@ module Qpid
#
# The following are the list of supported options:
#
- # [:create]
+ # [create]
# Indicates if the address should be created; values are *always*,
# *never*, *sender* or *reciever*.
#
- # [:assert]
+ # [assert]
# Indicates whether or not to assert any specified node properties;
# values are *always*, *never*, *sender* or *receiver*.
#
- # [:delete]
+ # [delete]
# Indicates whether or not to delete the addressed node when a sender
# or receiver is cancelled; values are *always*, *never*, *sender* or
# *receiver*.
#
- # [:node]
+ # [node]
# A nested map describing properties for the addressed node. Properties
# are *type* (*topic* or *queue*), *durable* (a boolean), *x-declare*
# (a nested map of amqp 0.10-specific options) and *x-bindings*. (nested
# list which specifies a queue, exchange or a binding key and arguments.
#
- # [:link]
+ # [link]
# A nested map through which properties of the link can be specified;
# properties are *durable*, *reliability*, *x-declare*, *x-subscribe*
# and *x-bindings*.
#
- # [:mode]
+ # [mode]
# (*For receivers only*) indicates whether the receiver should consume
# or browse messages; values are *consume* (the default) and *browse*.
- #
class Address
- # Creates a new +Address+ object from an address string.
+ # Creates a new +Address+ from an address string.
#
- # ==== Options
+ # ==== Attributes
#
- # * address - the address string
+ # * +address+ - the address string
#
# ==== Examples
#
+ # # create a new address for a queue named "my-queue" that will
+ # # be created if it doesn't already exist
# addr = Qpid::Messaging::Address.new "my-queue;{create:always}"
#
def initialize(address, address_impl = nil)
@@ -92,7 +97,10 @@ module Qpid
#
# ==== Examples
#
- # puts "The address name is #{addr.name}."
+ # # display the name of the address
+ # addr = Qpid::Messaging::Address.new "foo;{create:always}"
+ # # outputs the word 'foo'
+ # puts addr.name
#
def name; @address_impl.getName; end
@@ -100,6 +108,9 @@ module Qpid
#
# ==== Examples
#
+ # # create a new address with the name "my-queue"
+ # addr = Qpid::Messaging::Address.new "my-queue/my-subject;{create:always}"
+ # # changes the name to "my-new-queue"
# addr.name = "my-new-queue"
#
def name=(name); @address_impl.setName name; end
@@ -108,7 +119,8 @@ module Qpid
#
# ==== Examples
#
- # puts "The subject is #{addr.subject}."
+ # # creates a new address with the subject "bar"
+ # addr = Qpid::Messaging::Address.new "my-queue/bar;{create:always}"
#
def subject; @address_impl.getSubject; end
@@ -116,30 +128,40 @@ module Qpid
#
# ==== Examples
#
- # addr.subject = "testing"
+ # # creates an address with the subject "example"
+ # addr = Qpid::Messaging::Address.new "my-queue/example;{create:always}"
+ # # changes the subject to "test"
+ # addr.subject = "test"
#
def subject=(subject); @address_impl.setSubject(subject); end
# Returns the type for the +Address+.
- #
- # ==== Examples
- #
- # puts "The address is a #{address.address_type}."
- #
- #---
+ #--
# We cannot use "type" since that clashes with the Ruby object.type
# identifier.
+ #++
def address_type; @address_impl.getType; end
# Sets the type for the +Address+.
#
# The type of the address determines how +Sender+ and +Receiver+ objects
- # are constructed for it. If no type is specified then it will be
- # determined by querying the broker.
+ # are constructed for it. It also affects how a reply-to address is
+ # encoded.
#
- # ===== Options
+ # If no type is specified then it will be determined by querying the
+ # broker. Explicitly setting the type prevents this.
#
- # * type - the address type
+ # Values are either *queue* or *topic*.
+ #
+ # ==== Options
+ #
+ # * +type+ - the address type
+ #
+ # ==== Examples
+ #
+ # # creates an queue address
+ # addr = Qpid::Messaging::Address.new "my-queue;{create:always}"
+ # addr.address_type = "queue"
#
def address_type=(type); @address_impl.setType(type); end
@@ -153,6 +175,7 @@ module Qpid
# ==== Examples
#
# addr.options = :create => :always
+ # addr.options = :create => :always, :delete => :always
#
def options=(options = {}); @address_impl.setOptions(convert_options(options)); end
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/connection.rb Thu Feb 7 15:50:11 2013
@@ -21,50 +21,53 @@ module Qpid
module Messaging
- # Establishes a connection to a remote endpoint.
+ # A +Connection+ represents a network connection to a remote endpoint.
class Connection
attr_reader :options # :nodoc:
- # Creates a connection object, but does not actually connect to
- # the specified location.
+ # Creates a connection object. Raises a MessagingError if an invalid
+ # connection option is used.
#
- # ==== Options
+ # == Options
#
- # :url - the URL for the broker (def. +"localhost"+)
- # :options - connection options (def. +{}+)
+ # * +:url+ - the URL for the broker
+ # * +:options+ - connection options
#
- # ==== Controlling Reconnect Behavior
+ # == Controlling Reconnect Behavior
#
# The following connection options can be used to configure
# the reconnection behavior for this connection.
#
- # * :username
- # * :password
- # * :heartbeat
- # * :tcp_nodelay
- # * :sasl_mechanism
- # * :sasl_service
- # * :sasl_min_ssf
- # * :sasl_max_ssf
- # * :transport
- # * :reconnect - +true+ or +false+; indicates wehtehr 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
+ # * +: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
+ # == 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"}
#
def initialize(opts = {})
@url = opts[:url] || "localhost"
- @options = convert_options(opts[:options] || {})
+ @options = Qpid::Messaging.stringify(opts[:options] || {})
@connection_impl = opts[:impl] || Cqpid::Connection.new(@url, @options)
end
@@ -74,8 +77,9 @@ module Qpid
# Establishes the connection.
#
- # ==== Examples
+ # == Examples
#
+ # # open a connection if it's not already open
# conn.open unless conn.open?
#
def open
@@ -84,25 +88,34 @@ module Qpid
# Reports whether the connection is open.
#
- # ==== Examples
+ # == Examples
#
+ # # close the connection if it's not already closed
# conn.close if conn.open?
#
def open?; true && !@connection_impl.nil? && @connection_impl.isOpen; end
# Closes the connection.
+ #
+ # == Examples
+ #
+ # # close a connection
+ # conn.close
+ #
def close; @connection_impl.close; end
# Creates a new session.
#
- # ==== Arguments
+ # == Arguments
#
- # * :name - specifies the name for this session
- # * :transactional - if +true+ then a creates a transaction session (def. +false+)
+ # * +:name+ - specifies the name for this session
+ # * +:transactional+ - if +true+ then a creates a transaction session (def. +false+)
#
- # ==== Examples
+ # == Examples
#
+ # # create a session named 'session1'
# session = conn.create_session :name => "session1"
+ # # create a transactional session
# session = conn.create_session :transaction => true
#
def create_session(args = {})
@@ -119,17 +132,18 @@ module Qpid
end
end
- # Returns a Session with the given name.
+ # Returns a Session with the given name. Raises an exception if no
+ # session with the given name exists.
#
- # If no such Session exists then a MessagingException is raised.
# == Options
#
- # * +name+ - the session name
+ # * +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
@@ -142,6 +156,18 @@ module Qpid
end
# 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'
+ #
def authenticated_username; @connection_impl.getAuthenticatedUsername if open?; end
private
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/duration.rb Thu Feb 7 15:50:11 2013
@@ -23,19 +23,21 @@ module Qpid
# A Duration represents a period of time in milliseconds
#
- # It defines the following named values as symbols:
+ # == Named Durations
#
- # [:FOREVER]
+ # The following named +Durations+ are available as symbols:
+ #
+ # [FOREVER]
# The maximum integer value for the platform. Effectively this will wait
# forever.
#
- # [:IMMEDIATE]
+ # [IMMEDIATE]
# An alias for 0 milliseconds.
#
- # [:SECOND]
+ # [SECOND]
# An alias for 1,000 milliseconds.
#
- # [:MINUTE]
+ # [MINUTE]
# And alias for 60,000 millisecons.
#
class Duration
@@ -44,12 +46,13 @@ module Qpid
#
# ==== Options
#
- # * length - The duration in milliseconds.
+ # * +length+ - The duration in +milliseconds+.
#
# ==== Examples
#
- # # Wait up to 10 seconds for an incoming message
- # receiver.get Qpid::Messaging::Duration.new 10000
+ # # creates a duration of 15 seconds
+ # # REMEMBER: Duration deals in milliseconds
+ # delay = Qpid::Messaging::Duration.new 15000
#
def initialize length
@duration_impl = Cqpid::Duration.new length
@@ -59,26 +62,42 @@ module Qpid
@duration_impl
end
- # Returns the period of time in milliseconds
+ # Returns the period of time in +milliseconds+.
#
# ==== Examples
#
- # duration = Qpid::Messaging::Duration.new :length => 5000
- # puts "Waiting #{duration.milliseconds} ms for a message."
- # msg = receiver.fetch duration
+ # # doubling growth in waiting for messages in a loop
+ # do loop
+ # set the base duration waiting length
+ # timeout = Qpid::Messaging::Duration::SECOND
+ # msg = nil
+ # # loop until we receive a message
+ # while msg.nil?
+ # puts "Waiting #{timeout.milliseconds}ms"
+ # msg = recv.get timeout
+ # # if nothing was received, double the duration
+ # if msg.nil?
+ # # double out timeout
+ # timeout = timeout * 2
+ # else
+ # # do something with the message
+ # puts "Received: #{msg.content}"
+ # end
+ # end
+ # end
#
def milliseconds
@duration_impl.getMilliseconds
end
- # Returns a new Duration with a period of time that is a multiple
- # of the original Duration.
+ # Multiplies the duration of the +Duration+ and returns a new instance.
#
# Raises exceptions on a negative factor. Returns
# Qpid::Messaging::Duration::IMMEDIATE when the factor is 0.
#
# ==== Examples
#
+ # # return a duration that is 2 minutes (120,000 ms)
# twominutes = Qpid::Messaging::Duration::MINUTE * 2
#
def *(factor)
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/encoding.rb Thu Feb 7 15:50:11 2013
@@ -22,12 +22,12 @@ module Qpid
module Messaging
# Encodes the supplied content into the given message.
- def self.encode content, message, encoding = nil
+ def self.encode content, message, encoding = nil # :nodoc:
Cqpid::encode content, message.message_impl, encoding
end
# Decodes and returns the message's content.
- def self.decode(message, content_type = nil)
+ def self.decode(message, content_type = nil) # :nodoc:
content_type = message.content_type if content_type.nil?
case content_type
@@ -42,7 +42,7 @@ module Qpid
# Takes as input any type and converts anything that's a symbol
# into a string.
- def self.stringify(value)
+ def self.stringify(value) # :nodoc:
# set the default value
result = value
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/message.rb Thu Feb 7 15:50:11 2013
@@ -22,20 +22,19 @@ module Qpid
module Messaging
# A +Message+ represents an routable piece of information.
- #
- # The content for a message is automatically encoded and decoded.
- #
class Message
- # Creates a new instance of +Message+.
+ # Creates a +Message+.
#
# ==== Options
#
- # * :content - The content.
+ # * +:content+ - the content
#
# ==== Examples
#
+ # # create a simple message and sends it
# message = Qpid::Messaging::Message.new :content => "This is a message."
+ # sender.send message
#
def initialize(args = {})
@message_impl = (args[:impl] if args[:impl]) || nil
@@ -49,15 +48,20 @@ module Qpid
@message_impl
end
- # Sets the address to which replies should be sent for the +Message+.
+ # Sets the reply-to address.
+ #
+ # The address can either be an instance of Address or else and
+ # address string.
#
# ==== Options
#
- # * address - an instance of +Address+, or an address string
+ # * +address+ - the address
#
# ==== Examples
#
+ # # set replies using an Address
# msg.reply_to = Qpid:Messaging::Address.new "my-responses"
+ # # set replies using an address string
# msg.reply_to = "my-feed/responses"
#
def reply_to=(address)
@@ -67,7 +71,6 @@ module Qpid
end
# Returns the reply to address for the +Message+.
- #
def reply_to
address_impl = @message_impl.getReplyTo
# only return an address if a reply to was specified
@@ -78,25 +81,15 @@ module Qpid
#
# ==== Options
#
- # * subject - the subject
- #
- # ==== Examples
- #
- # msg.subject = "mysubject"
- #
+ # * +subject+ - the subject
def subject=(subject); @message_impl.setSubject subject; end
# Returns the subject of the +Message+.
- #
- # ==== Options
- #
- # puts "The subject is #{msg.subject}"
- #
def subject; @message_impl.getSubject; end
# Sets the content type for the +Message+.
#
- # This should be set by the sending applicaton and indicates to
+ # This should be set by the sending applicaton and indicates to the
# recipients of the message how to interpret or decode the content.
#
# By default, only dictionaries and maps are automatically given a content
@@ -105,23 +98,17 @@ module Qpid
#
# ==== Options
#
- # * content_type - the content type.
- #
- def content_type=(content_type); @message_impl.setContentType content_type; end
-
- # Returns the content type for the +Message+.
+ # * +content_type+ - the content type
#
# ==== Examples
#
- # case msg.content_type
- # when "myapp/image"
- # ctl.handle_image msg
- # end
- # when "myapp/audio"
- # ctl.handle_audio msg
- # end
- # end
+ # # send base64 encoded data in a mesage
+ # msg = Qpid::Messaging::Message.new :content = "UXBpZCBSdWxlcyEK"
+ # msg.content_type = "application/base64"
#
+ def content_type=(content_type); @message_impl.setContentType content_type; end
+
+ # Returns the content type for the +Message+.
def content_type; @message_impl.getContentType; end
# Sets the message id.
@@ -131,16 +118,17 @@ module Qpid
#
# ==== Options
#
- # * id - the id
+ # * +id+ - the id
#
# ==== Examples
#
+ # # this example only works in Ruby >= 1.9, for 1.8 use a UUID library
+ # require 'SecureRandom'
+ # msg.message_id = SecureRandom.uuid
#
def message_id=(message_id); @message_impl.setMessageId message_id.to_s; end
# Returns the message id.
- #
- # See +message_id=+ for details.
def message_id; @message_impl.getMessageId; end
# Sets the user id for the +Message+.
@@ -149,21 +137,18 @@ module Qpid
# the connection itself, as the messaging infrastructure will verify
# this.
#
- # See +Qpid::Messaging::Connection.authenticated_username+
+ # See Qpid::Messaging::Connection.authenticated_username
#
# *NOTE:* If the id is not a +String+ then the id is set using
# the object's string representation.
#
# ==== Options
#
- # * id - the id
+ # * +id+ - the id
#
def user_id=(user_id); @message_impl.setUserId user_id; end
# Returns the user id for the +Message+.
- #
- # See +user_id=+ for details.
- #
def user_id; @message_impl.getUserId; end
# Sets the correlation id of the +Message+.
@@ -179,14 +164,11 @@ module Qpid
#
# ==== Options
#
- # * id - the id
+ # * +id+ - the id
#
def correlation_id=(correlation_id); @message_impl.setCorrelationId correlation_id; end
# Returns the correlation id of the +Message+.
- #
- # *NOTE:* See +correlation_id=+ for details.
- #
def correlation_id; @message_impl.getCorrelationId; end
# Sets the priority of the +Message+.
@@ -200,19 +182,18 @@ module Qpid
#
# ==== Options
#
- # * priority - the priority
+ # * +priority+ - the priority
#
def priority=(priority); @message_impl.setPriority priority; end
# Returns the priority for the +Message+.
- #
def priority; @message_impl.getPriority; end
# Sets the time-to-live in milliseconds.
#
# ==== Options
#
- # * duration - the number of milliseconds
+ # * +duration+ - the number of milliseconds
#
def ttl=(duration)
if duration.is_a? Qpid::Messaging::Duration
@@ -233,12 +214,11 @@ module Qpid
#
# ==== Options
#
- # * durable - the durability flag (def. false)
+ # * +durable+ - the durability flag (def. false)
#
def durable=(durable); @message_impl.setDurable durable; end
# Returns the durability for the +Message+.
- #
def durable; @message_impl.getDurable; end
# This is a hint to the messaging infrastructure that if de-duplication
@@ -247,17 +227,16 @@ module Qpid
#
# ==== Options
#
- # * redelivered - sets the redelivered state (def. false)
+ # * +redelivered+ - sets the redelivered state (def. false)
#
# ==== Examples
#
- # # processed is an array of processed message ids
+ # # processed is a collection of messages already received
# msg.redelivered = true if processed.include? msg.message_id
#
def redelivered=(redelivered); @message_impl.setRedelivered redelivered; end
# Returns whether the +Message+ has been marked as redelivered.
- #
def redelivered; @message_impl.getRedelivered; end
# Returns all named properties.
@@ -265,14 +244,13 @@ module Qpid
# *NOTE:* It is recommended to use the []= method for
# retrieving and setting properties. Using this method may
# result in non-deterministic behavior.
- #
def properties; @message_impl.getProperties; end
# Returns the value for the named property.
#
# ==== Options
#
- # * name - the property name
+ # * +name+ - the property name
#
# ==== Examples
#
@@ -283,10 +261,21 @@ module Qpid
# Assigns a value to the named property.
#
+ # A property's name or value, if a symbol, will be converted to a string
+ # representation. However, you will still be able to access them using
+ # a symbol for the name.
+ #
# ==== Options
#
- # * name - the property name
- # * value - the property value
+ # * +name+ - the property name
+ # * +value+ - the property value
+ #
+ # ==== Examples
+ #
+ # # set the signed attribute on a message and then retrieve it
+ # msg[:signed] = true # sets "signed" => true
+ # puts "It's signed" if msg["signed"] # outputs "It's signed"
+ #
def []=(key, value)
@message_impl.setProperty(key.to_s,
Qpid::Messaging.stringify(value))
@@ -295,17 +284,19 @@ module Qpid
# Sets the content for the +Message+.
#
# Content is automatically encoded for Array and Hash types. Other types
- # need to set their own content types (via +content_type+) in order to
+ # need to set their own content types (via content_type) in order to
# specify how recipients should process the content.
#
# ==== Options
#
- # * content - the content
+ # * +content+ - the content
#
# ==== Examples
#
- # msg.content = "This is a simple message." # a simple message
- # msg.content = {:foo => :bar} # content is automatically encoded
+ # # set a simple content for a message
+ # msg.content = "This is a simple message."
+ # # sets content that is automatically encoded
+ # msg.content = {:foo => :bar}
#
def content=(content)
content_type = nil
@@ -348,8 +339,7 @@ module Qpid
@content
end
- # Returns the content's size.
- #
+ # Returns the content's size in bytes.
def content_size; @message_impl.getContentSize; end
end
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/receiver.rb Thu Feb 7 15:50:11 2013
@@ -21,17 +21,26 @@ module Qpid
module Messaging
- # Receiver is the entity through which messages are received.
+ # +Receiver+ is the entity through which messages are received.
#
- # An instance of Receiver can only be created using an active (not
- # previously closed) Session.
+ # An instance of +Receiver+ can only be created using an active (i.e., not
+ # previously closed) Session. See Qpid::Messaging::Session.create_receiver
+ # for more details.
#
# ==== Example
#
+ # # create a connection and a session
# conn = Qpid::Messaging::Connection.new :url => "mybroker:5762"
# conn.open
# session = conn.create_session
- # receiver = session.create_receiver "my-sender-queue"
+ #
+ # # create a receiver that listens on the "updates" topic of "alerts"
+ # receiver = session.create_receiver "alerts/updates"t
+ #
+ # # wait for an incoming message and process it
+ # incoming = receiver.get Qpid::Messaging::Duration::FOREVER
+ # process(incoming)
+ #
class Receiver
def initialize(session, receiver_impl) # :nodoc:
@@ -46,27 +55,24 @@ module Qpid
# Retrieves a message from the local queue, or waits for up to
# the duration specified for one to become available.
#
- # If a block is given, then it will be invaked after the next message
- # is received or the call times out, passing in the message or nil
- # respectively.
+ # If no message is received within the specified time then a
+ # MessagingException is raised.
#
# ==== Options
- # * duration - the timeout to wait (def. Duration::FOREVER)
#
- # ==== Examples
- #
- # msg = rcvr.get # Uses the default timeout of forever
+ # * duration - the timeout to wait
#
- # msg = rcvr.get Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
+ # ==== Examples
#
- # # passes in a block to handle the received message
- # rcvr.get Qpid::Messaging::Duration::SECOND do |message|
- # if message.nil?
- # puts "No message was received."
- # else
- # puts "Received this message: #{message.content}"
- # end
+ # # retrieves a message, also handles exceptions raised on no messages
+ # begin
+ # # checks for a message, returning immediately
+ # msg = recv.get Qpid::Messaging::Duration::IMMEDIATE
+ # puts "Received this message: #{message.content}"
+ # rescue
+ # puts "No messages available.
# end
+ #
def get(duration = Qpid::Messaging::Duration::FOREVER)
message_impl = @receiver_impl.get duration.duration_impl
create_message_wrapper message_impl unless message_impl.nil?
@@ -75,33 +81,35 @@ module Qpid
# Retrieves a message from the receiver's subscription, or waits
# for up to the duration specified for one to become available.
#
- # If a block is given, then it will be invaked after the next message
- # is received or the call times out, passing in the message or nil
- # respectively.
+ # If no message is fetched within the specified time then a
+ # MessagingException is raised.
#
# ==== Options
+ #
# * duration - the timeout to wait (def. Duration::FOREVER)
#
# ==== Examples
#
- # msg = rcvr.fetch # Uses the default timeout of forever
- #
- # msg = rcvr.fetch Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
- #
- # # passes in a block to handle the received message
- # rcvr.fetch Qpid::Messaging::Duration::SECOND do |message|
- # if message.nil?
- # puts "No message was received."
- # else
- # puts "Received this message: #{message.content}"
- # end
+ # # retrieves a message, also handles exceptions raised on no messages
+ # begin
+ # # checks for a message, times out after one second
+ # msg = recv.fetch Qpid::Messaging::Duration::SECOND
+ # puts "Fetched this message: #{message.content}"
+ # rescue
+ # puts "No messages available.
# end
+ #
def fetch(duration = Qpid::Messaging::Duration::FOREVER)
message_impl = @receiver_impl.fetch duration.duration_impl
create_message_wrapper message_impl unless message_impl.nil?
end
- # Sets the capacity for this +Receiver+.
+ # Sets the capacity.
+ #
+ # The capacity of a +Receiver+ is the number of Messages that can be
+ # pre-fetched from the broker and held locally. If capacity is 0 then
+ # messages will never be pre-fetched and all messages must instead be
+ # retrieved using #fetch.
#
# ==== Options
#
@@ -109,63 +117,50 @@ module Qpid
#
# ==== Examples
#
- # receiver.capacity = 50 # sets the incoming capacity to 50 messages
+ # # create a receiver and give it a capacity of 50
+ # recv = session.create_receiver "alerts/minor"
+ # recv.capacity = 50
#
def capacity=(capacity); @receiver_impl.setCapacity capacity; end
# Returns the capacity.
- #
- #
- # The capacity is the numnber of incoming messages that can be held
- # locally before being fetched.
- #
- # ==== Examples
- #
- # puts "The receiver can hold #{rcv.capacity} messages."
- #
def capacity; @receiver_impl.getCapacity; end
- # Returns the number of slots for receiving messages.
+ # Returns the number of messages locally held.
+ #
+ # The available is always 0 <= available <= capacity.
#
- # This differs from +capacity+ in that it is the available slots in
- # the capacity for holding incoming messages, where available <= capacity.
+ # If the #capacity is set to 0 then available will always be 0.
#
# ==== Examples
#
- # puts "You can receive #{rcv.available} messages before blocking."
+ # # output the number of messages waiting while processing
+ # loop do
+ # puts "There are #{recv.available} messages pending..."
+ # # wait forever (the default) for the next message
+ # msg = recv.get
+ # # process the message
+ # dispatch_message msg
+ # end
#
def available; @receiver_impl.getAvailable; end
# Returns the number of messages that have been received and acknowledged
# but whose acknowledgements have not been confirmed by the sender.
- #
- # ==== Examples
- #
- # puts "You have #{rcv.unsettled} messages to be confirmed."
- #
def unsettled; @receiver_impl.getUnsettled; end
# Closes this +Receiver+.
#
- # This does not affect the +Session+.
+ # This does not affect the owning Session or Connection.
def close; @receiver_impl.close; end
- # Returns whether the receiver is closed.
- #
- # ==== Examples
- #
- # recv.close unless recv.closed?
- #
+ # Returns whether the +Receiver+ is closed.
def closed?; @receiver_impl.isClosed; end
# Returns the name of this +Receiver+.
- #
- # ==== Examples
- #
- # puts "Receiver: #{recv.name}"
def name; @receiver_impl.getName; end
- # Returns the Session for this +Receiver+.
+ # Returns the owning Session for this +Receiver+.
def session; @session; end
private
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/sender.rb Thu Feb 7 15:50:11 2013
@@ -21,17 +21,33 @@ module Qpid
module Messaging
- # Sender is the entity through which messages sent.
+ # +Sender+ is the entity through which messages sent.
#
- # An instance of Sender can only be created using an active (not previously
- # closed) Session.
+ # An instance of +Sender+ can only be created using an active (not previously
+ # closed) Session. See Qpid::Messaging::Session.create_sender for more details.
#
# ==== Examples
#
- # conn = Qpid::Messaging::Connection.new :url => "mybroker:5762"
+ # # create a connection
+ # conn = Qpid::Messaging::Connection.new "mybroker:5672"
# conn.open
- # session = conn.create_session
- # sender = session.create_session "my-sender-queue;{create:always}"
+ #
+ # if conn.open?
+ #
+ # # create a session
+ # session = conn.create_session
+ #
+ # # create a sender that posts messages to the "updates" queue
+ # sender = session.create_sender "updates;{create:always}
+ #
+ # # begin sending updates
+ # loop do
+ # # wait for the next event content then send it
+ # content = wait_for_event
+ # sender.send Qpid::Messaging::Message.new :content => content
+ # end
+ # end
+ #
class Sender
def initialize(session, sender_impl) # :nodoc:
@@ -43,15 +59,13 @@ module Qpid
@sender_impl
end
- # Sends a message.
- #
- # If a block is given, then it will be invoked after the message
- # is sent.
+ # Sends a message, optionally blocking until the message is received
+ # by the broker.
#
# ==== Options
#
- # * message - The message to send.
- # * :sync - See note below on synching.
+ # * +message+ - The message to send.
+ # * +:sync+ - Block until received. See note below on synching.
#
# ==== Synching
#
@@ -61,9 +75,13 @@ module Qpid
#
# ==== Examples
#
- # sender.send message do |message|
- # puts "Message sent: #{message.content}"
- # end
+ # # send a message
+ # outgoing = Qpid::Messaging::Message.new :content => content
+ # sender.send outgoing
+ #
+ # # send a message, wait for confirmation from the broker
+ # outgoing = Qpid::Messaging::Message.new :content => content
+ # sender.send outgoing, :sync => true
#
def send(message, args = {}, &block)
sync = args[:sync] || false
@@ -73,52 +91,27 @@ module Qpid
# Closes this +Sender+.
#
- # This does not affect the +Session+.
+ # This does not affect the owning Session or Connection.
def close; @sender_impl.close; end
# Returns the human-readable name for this +Sender+.
- #
- # ==== Examples
- #
- # puts "Sender: #{sender.name}"
- #
def name; @sender_impl.getName; end
# Sets the capacity for this +Sender+.
#
# The capacity is the number of outgoing messages that can be held
- # pending confirmation or receipt by the broker.
+ # pending confirmation of receipt by the broker.
#
# ==== Options
#
- # * capacity - the capacity
- #
- # ==== Examples
- #
- # sender.capacity = 50 # sets the outgoing capacity to 50 messages
- #
+ # * +capacity+ - the capacity
def capacity=(capacity); @sender_impl.setCapacity capacity; end
# Returns the capacity.
- #
- # The capacity is the total number of outgoing messages that can be
- # sent before a called to +send+ begins to block by default.
- #
- # ==== Examples
- #
- # puts "You can send a maximum of #{sender.capacity} messages."
- #
def capacity; @sender_impl.getCapacity; end
# Returns the number of messages sent that are pending receipt
# confirmation by the broker.
- #
- # ==== Examples
- #
- # if sender.unsettled > 0
- # puts "There are #{sender.unsettled} messages pending."
- # end
- #
def unsettled; @sender_impl.getUnsettled; end
# Returns the available slots for sending messages.
@@ -127,21 +120,11 @@ module Qpid
# the senders capacity for holding outgoing messages. The difference
# between capacity and available is the number of messages that
# have not been delivered yet.
- #
- # ==== Examples
- #
- # puts "You can send #{sender.available} messages before blocking."
- #
def available
@sender_impl.getAvailable
end
- # Returns the +Session+ for this sender.
- #
- # ==== Examples
- #
- # recv.session.close if done
- #
+ # Returns the Session for this sender.
def session; @session; end
end
Modified: qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb
URL: http://svn.apache.org/viewvc/qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb?rev=1443577&r1=1443576&r2=1443577&view=diff
==============================================================================
--- qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb (original)
+++ qpid/trunk/qpid/cpp/bindings/qpid/ruby/lib/qpid_messaging/session.rb Thu Feb 7 15:50:11 2013
@@ -21,7 +21,11 @@ module Qpid
module Messaging
- # A Session represents a distinct conversation between end points.
+ # A +Session+ represents a distinct conversation between end points. They are
+ # created from an active (i.e., not closed) Connection.
+ #
+ # A +Session+ is used to acknowledge individual or all messages that have
+ # passed through it
class Session
def initialize(connection, session) # :nodoc:
@@ -33,24 +37,19 @@ module Qpid
@session_impl
end
- # Returns the +Connection+ associated with this session.
+ # Returns the Connection associated with this session.
def connection
@connection
end
# Creates a new endpoint for sending messages.
#
- # The +address+ can either be an instance +Address+ or else a
- # string that describes an address endpoint.
+ # The address can either be an instance Address or else an
+ # address string.
#
# ==== Arguments
#
- # * +address+ The end point address.
- #
- # ==== Examples
- #
- # sender = session.create_sender "my-queue;{create:always}"
- #
+ # * +address+ - the end point address.
def create_sender(address)
_address = address
@@ -64,35 +63,25 @@ module Qpid
Qpid::Messaging::Sender.new(self, sender_impl)
end
- # Retrieves the +Sender+ with the specified name.
+ # Retrieves the Sender with the specified name.
#
- # Raises an exception when no such Sender exists.
+ # Raises an exception if no such Sender exists.
#
# ==== Arguments
#
- # * +name+ The +Sender+ name.
- #
- # ==== Examples
- #
- # sender = session.sender "my-queue"
- #
+ # * +name+ - the name of the Sender
def sender(name)
Qpid::Messaging::Sender.new self, @session_impl.getSender(name)
end
# Creates a new endpoint for receiving messages.
#
- # The +address+ can either be an instance +Address+ or else a
- # string that describes an address endpoint.
+ # The +address+ can either be an instance Address or else an
+ # address string.
#
# ==== Arguments
#
- # * +address+ The end point address.
- #
- # ==== Examples
- #
- # receiver = session.create_receiver "my-queue"
- #
+ # * +address+ - the end point address.
def create_receiver(address)
result = nil
receiver_impl = nil
@@ -112,20 +101,16 @@ module Qpid
#
# ==== Arguments
#
- # * +name+ The +Receiver+ name.
- #
- # ==== Examples
- #
- # receiver = session.receiver "my-queue"
- #
+ # * +name+ - the name of the Receiver
def receiver(name)
Qpid::Messaging::Receiver.new self, @session_impl.getReceiver(name)
end
# Closes the +Session+ and all associated +Sender+ and +Receiver+ instances.
#
- # NOTE: All +Session+ instances for a +Connection+ are closed when the
- # +Connection+ is closed.
+ # *NOTE:* All +Session+ instances for a Connection are closed when the
+ # Connection is closed. But closing a +Session+ does not affect the
+ # owning Connection.
def close; @session_impl.close; end
# Commits any pending transactions for a transactional session.
@@ -139,21 +124,30 @@ module Qpid
#
# ==== 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)
+ # * +options+ - the set of options
+ #
+ # ==== Options
+ #
+ # * :message - if specified, then only that Message is acknowledged
+ # * :sync - if true, the call will block until processed by the server
#
# ==== Examples
#
- # session.acknowledge # acknowledges all received messages
- # session.acknowledge :message => message # acknowledge one message
- # session.acknowledge :sync => true # blocks until the call completes
+ # # acknowledge all received messages
+ # session.acknowledge
+ #
+ # # acknowledge a single message
+ # session.acknowledge :message => message
+ #
+ # # acknowledge all messages, wait until the call finishes
+ # session.acknowledge :sync => true
#
#--
# TODO: Add an optional block to be used for blocking calls.
#++
- def acknowledge(args = {})
- sync = args[:sync] || false
- message = args[:message] if args[:message]
+ def acknowledge(options = {})
+ sync = options[:sync] || false
+ message = options[:message] if options[:message]
unless message.nil?
@session_impl.acknowledge message.message_impl, sync
@@ -178,7 +172,11 @@ module Qpid
#
# ==== Arguments
#
- # * :block - if true then the call blocks until the server acknowledges it (def. false)
+ # * +options+ - the list of options
+ #
+ # ==== Options
+ #
+ # * +:block+ - if true, the call blocks until the server acknowledges it
#
#--
# TODO: Add an optional block to be used for blocking calls.
@@ -189,26 +187,43 @@ module Qpid
end
# Returns the total number of receivable messages, and messages already
- # received, by +Receiver+ instances associated with this +Session+.
+ # received, by Receiver instances associated with this +Session+.
def receivable; @session_impl.getReceivable; end
- # Returns the number of messages that have been acknowledged by this session
- # whose acknowledgements have not been confirmed as processed by the server.
+ # Returns the number of messages that have been acknowledged by this
+ # +Session+ whose acknowledgements have not been confirmed as processed
+ # by the server.
def unsettled_acks; @session_impl.getUnsettledAcks; end
- # Fetches the +Receiver+ for the next message.
+ # Fetches the next Receiver with a message pending. Waits the specified
+ # number of milliseconds before timing out.
+ #
+ # For a Receiver to be returned, it must have a capacity > 0 and have
+ # Messages locally queued.
+ #
+ # If no Receiver is found within the time out period, then a MessageError
+ # is raised.
#
# ==== Arguments
#
- # * timeout - time to wait for a +Receiver+ before timing out
+ # * +timeout+ - the duration
#
# ==== 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}"
+ # loop do
+ #
+ # begin
+ # # wait a maximum of one minute for the next receiver to be ready
+ # recv = session.next_receiver Qpid::Messaging::Duration::MINUTE
+ #
+ # # get and dispatch the message
+ # msg = recv.get
+ # dispatch_message msg
+ #
+ # rescue
+ # puts "No receivers were returned"
+ # end
+ #
# end
def next_receiver(timeout = Qpid::Messaging::Duration::FOREVER, &block)
receiver_impl = @session_impl.nextReceiver(timeout.duration_impl)
@@ -222,10 +237,6 @@ module Qpid
end
# Returns true if there were exceptions on this session.
- #
- # ==== Examples
- #
- # puts "There were session errors." if @session.errors?
def errors?; @session_impl.hasError; end
# If the +Session+ has been rendered invalid due to some exception,
@@ -235,6 +246,7 @@ module Qpid
#
# ==== Examples
#
+ # # show any errors that occurred during the Session
# if @session.errors?
# begin
# @session.errors
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org