class Qpid::Proton::Message

A Message represents an addressable quantity of data.

Message Body

The message body can be set using the body= method. The message will then attempt to determine how exactly to encode the content.

Examples

To create a message for sending:

# send a simple text message
msg = Qpid::Proton::Message.new
msg.body = "STATE: update"

# send a binary chunk of data
data = File.binread("/home/qpid/binfile.tar.gz")
msg = Qpid::Proton::Message.new
msg.body = Qpid::Proton::BinaryString.new(data)

Public Class Methods

new() click to toggle source

Creates a new Message instance.

# File lib/core/message.rb, line 132
def initialize
  @impl = Cproton.pn_message
  ObjectSpace.define_finalizer(self, self.class.finalize!(@impl))
  @properties = {}
  @instructions = {}
  @annotations = {}
  @body = nil
end

Public Instance Methods

[](name) click to toggle source

Retrieves the value for the specified property name. If not found, then it returns nil.

# File lib/core/message.rb, line 576
def [](name)
  @properties[name]
end
[]=(name, value) click to toggle source

Assigns the value given to the named property.

Arguments

  • name - the property name

  • value - the property value

# File lib/core/message.rb, line 569
def []=(name, value)
  @properties[name] = value
end
address() click to toggle source

Returns the destination address.

# File lib/core/message.rb, line 343
def address
  Cproton.pn_message_get_address(@impl)
end
address=(address) click to toggle source

Sets the destination address.

Options

  • address - the address

# File lib/core/message.rb, line 337
def address=(address)
  Cproton.pn_message_set_address(@impl, address)
end
annotations() click to toggle source

Returns the annotations for this message.

# File lib/core/message.rb, line 600
def annotations
  @annotations
end
annotations=(annotations) click to toggle source

Assigns annotations to this message.

# File lib/core/message.rb, line 606
def annotations=(annotations)
  @annotations = annotations
end
body() click to toggle source

Returns the body property of the message.

# File lib/core/message.rb, line 612
def body
  @body
end
body=(body) click to toggle source

Assigns a new value to the body of the message.

# File lib/core/message.rb, line 618
def body=(body)
  @body = body
end
clear() click to toggle source

Clears the state of the Message. This allows a single instance of Message to be reused.

# File lib/core/message.rb, line 165
def clear
  Cproton.pn_message_clear(@impl)
  @properties.clear unless @properties.nil?
  @instructions.clear unless @instructions.nil?
  @annotations.clear unless @annotations.nil?
  @body = nil
end
content() click to toggle source

Returns the message content.

WARNING: This method has been deprecated. Please use body instead to retrieve the content of a message.

# File lib/core/message.rb, line 429
def content
  size = 16
  loop do
    result = Cproton.pn_message_save(@impl, size)
    error = result[0]
    data = result[1]
    if error == Qpid::Proton::Error::OVERFLOW
      size = size * 2
    else
      check(error)
      return data
    end
  end
end
content=(content) click to toggle source

Sets the message content.

WARNING: This method has been deprecated. Please use body= instead to set the content of a message.

Options

  • content - the content

# File lib/core/message.rb, line 420
def content=(content)
  Cproton.pn_message_load(@impl, content)
end
content_encoding() click to toggle source

Returns the content encoding type.

# File lib/core/message.rb, line 456
def content_encoding
  Cproton.pn_message_get_content_encoding(@impl)
end
content_encoding=(encoding) click to toggle source

Sets the content encoding type.

Options

  • encoding - the content encoding

# File lib/core/message.rb, line 450
def content_encoding=(encoding)
  Cproton.pn_message_set_content_encoding(@impl, encoding)
end
content_type() click to toggle source

Returns the content type

# File lib/core/message.rb, line 407
def content_type
  Cproton.pn_message_get_content_type(@impl)
end
content_type=(content_type) click to toggle source

Sets the content type.

Options

# File lib/core/message.rb, line 401
def content_type=(content_type)
  Cproton.pn_message_set_content_type(@impl, content_type)
end
correlation_id() click to toggle source

Returns the correlation id.

# File lib/core/message.rb, line 391
def correlation_id
  Cproton.pn_message_get_correlation_id(@impl)
end
correlation_id=(id) click to toggle source

Sets the correlation id.

Options

  • id - the correlation id

# File lib/core/message.rb, line 385
def correlation_id=(id)
  Cproton.pn_message_set_correlation_id(@impl, id)
end
creation_time() click to toggle source

Returns the creation time.

# File lib/core/message.rb, line 492
def creation_time
  Cproton.pn_message_get_creation_time(@impl)
end
creation_time=(time) click to toggle source

Sets the creation time.

Options

  • time - the creation time

# File lib/core/message.rb, line 484
def creation_time=(time)
  raise TypeError.new("invalid time: #{time}") if time.nil?
  raise ::ArgumentError.new("time cannot be negative") if time < 0
  Cproton.pn_message_set_creation_time(@impl, time)
end
decode(encoded) click to toggle source

Decodes a message from supplied AMQP data and returns the number of bytes consumed.

Options

  • encoded - the encoded data

# File lib/core/message.rb, line 61
def decode(encoded)
  check(Cproton.pn_message_decode(@impl, encoded, encoded.length))

  post_decode
end
delete_property(name) click to toggle source

Deletes the named property.

# File lib/core/message.rb, line 582
def delete_property(name)
  @properties.delete(name)
end
delivery_count() click to toggle source

Returns the delivery count for the message.

This is the number of delivery attempts for the given message.

# File lib/core/message.rb, line 288
def delivery_count
  Cproton.pn_message_get_delivery_count(@impl)
end
delivery_count=(count) click to toggle source

Sets the delivery count for the message.

See ::delivery_count for more details.

Options

  • count - the delivery count

# File lib/core/message.rb, line 277
def delivery_count=(count)
  raise ::ArgumentError.new("invalid count: #{count}") if count.nil? || !([Float, Fixnum].include?(count.class))
  raise RangeError.new("count out of range: #{count}") if count < 0

  Cproton.pn_message_set_delivery_count(@impl, count.floor)
end
durable() click to toggle source

Returns the durable property.

The durable property indicates that the emessage should be held durably by any intermediaries taking responsibility for the message.

Examples

msg = Qpid::Proton::Message.new
msg.durable = true
# File lib/core/message.rb, line 214
def durable
  Cproton.pn_message_is_durable(@impl)
end
durable=(state) click to toggle source

Sets the durable flag.

See ::durable for more details on message durability.

Options

  • state - the durable state

# File lib/core/message.rb, line 199
def durable=(state)
  raise TypeError.new("state cannot be nil") if state.nil?
  Cproton.pn_message_set_durable(@impl, state)
end
encode() click to toggle source

Encodes the message.

# File lib/core/message.rb, line 92
def encode
  pre_encode
  size = 16
  loop do
    error, data = Cproton::pn_message_encode(@impl, size)
    if error == Qpid::Proton::Error::OVERFLOW
      size *= 2
    else
      check(error)
      return data
    end
  end
end
errno() click to toggle source

Returns the most recent error number.

# File lib/core/message.rb, line 175
def errno
  Cproton.pn_message_errno(@impl)
end
error() click to toggle source

Returns the most recent error message.

# File lib/core/message.rb, line 181
def error
  Cproton.pn_error_text(Cproton.pn_message_error(@impl))
end
error?() click to toggle source

Returns whether there is currently an error reported.

# File lib/core/message.rb, line 187
def error?
  !Cproton.pn_message_errno(@impl).zero?
end
expires() click to toggle source

Returns the expiration time.

# File lib/core/message.rb, line 474
def expires
  Cproton.pn_message_get_expiry_time(@impl)
end
expires=(time) click to toggle source

Sets the expiration time.

Options

  • time - the expiry time

# File lib/core/message.rb, line 466
def expires=(time)
  raise TypeError.new("invalid expiry time: #{time}") if time.nil?
  raise ::ArgumentError.new("expiry time cannot be negative: #{time}") if time < 0
  Cproton.pn_message_set_expiry_time(@impl, time)
end
first_acquirer=(state) click to toggle source

Sets whether this is the first time the message was acquired.

See ::first_acquirer? for more details.

Options

  • state - true if claiming the message

# File lib/core/message.rb, line 264
def first_acquirer=(state)
  raise TypeError.new("invalid state: #{state}") if state.nil? || !([TrueClass, FalseClass].include?(state.class))
  Cproton.pn_message_set_first_acquirer(@impl, state)
end
first_acquirer?() click to toggle source

Returns whether this is the first acquirer.

# File lib/core/message.rb, line 295
def first_acquirer?
  Cproton.pn_message_is_first_acquirer(@impl)
end
group_id() click to toggle source

Returns the group id.

# File lib/core/message.rb, line 508
def group_id
  Cproton.pn_message_get_group_id(@impl)
end
group_id=(id) click to toggle source

Sets the group id.

Options

  • id - the group id

# File lib/core/message.rb, line 502
def group_id=(id)
  Cproton.pn_message_set_group_id(@impl, id)
end
group_sequence() click to toggle source

Returns the group sequence number.

# File lib/core/message.rb, line 525
def group_sequence
  Cproton.pn_message_get_group_sequence(@impl)
end
group_sequence=(seq) click to toggle source

Sets the group sequence number.

Options

  • seq - the sequence number

# File lib/core/message.rb, line 518
def group_sequence=(seq)
  raise TypeError.new("invalid seq: #{seq}") if seq.nil?
  Cproton.pn_message_set_group_sequence(@impl, seq)
end
id() click to toggle source

Returns the message id.

# File lib/core/message.rb, line 311
def id
  Cproton.pn_message_get_id(@impl)
end
id=(id) click to toggle source

Sets the message id.

Options

  • id = the id

# File lib/core/message.rb, line 305
def id=(id)
  Cproton.pn_message_set_id(@impl, id)
end
instructions() click to toggle source

Returns the instructions for this message.

# File lib/core/message.rb, line 588
def instructions
  @instructions
end
instructions=(instr) click to toggle source

Assigns instructions to this message.

# File lib/core/message.rb, line 594
def instructions=(instr)
  @instructions = instr
end
priority() click to toggle source

Returns the priority.

# File lib/core/message.rb, line 234
def priority
  Cproton.pn_message_get_priority(@impl)
end
priority=(priority) click to toggle source

Sets the priority.

NOTE: Priority values are limited to the range [0,255].

Options

  • priority - the priority value

# File lib/core/message.rb, line 226
def priority=(priority)
  raise TypeError.new("invalid priority: #{priority}") if priority.nil? || !([Float, Fixnum].include?(priority.class))
  raise RangeError.new("priority out of range: #{priority}") if ((priority > 255) || (priority < 0))
  Cproton.pn_message_set_priority(@impl, priority.floor)
end
properties() click to toggle source

Returns the list of property names for associated with this message.

Examples

msg.properties.each do |name|
end
# File lib/core/message.rb, line 552
def properties
  @properties
end
properties=(properties) click to toggle source

Replaces the entire set of properties with the specified hash.

# File lib/core/message.rb, line 558
def properties=(properties)
  @properties = properties
end
proton_send(sender, tag = nil) click to toggle source

@private

# File lib/core/message.rb, line 45
def proton_send(sender, tag = nil)
  dlv = sender.delivery(tag || sender.delivery_tag)
  encoded = self.encode
  sender.stream(encoded)
  sender.advance
  dlv.settle if sender.snd_settle_mode == Link::SND_SETTLED
  return dlv
end
reply_to() click to toggle source

Returns the reply-to address

# File lib/core/message.rb, line 375
def reply_to
  Cproton.pn_message_get_reply_to(@impl)
end
reply_to=(address) click to toggle source

Sets the reply-to address.

Options

  • address - the reply-to address

# File lib/core/message.rb, line 369
def reply_to=(address)
  Cproton.pn_message_set_reply_to(@impl, address)
end
reply_to_group_id() click to toggle source

Returns the reply-to group id.

# File lib/core/message.rb, line 541
def reply_to_group_id
  Cproton.pn_message_get_reply_to_group_id(@impl)
end
reply_to_group_id=(id) click to toggle source

Sets the reply-to group id.

Options

  • id - the id

# File lib/core/message.rb, line 535
def reply_to_group_id=(id)
  Cproton.pn_message_set_reply_to_group_id(@impl, id)
end
subject() click to toggle source

Returns the subject

# File lib/core/message.rb, line 359
def subject
  Cproton.pn_message_get_subject(@impl)
end
subject=(subject) click to toggle source

Sets the subject.

Options

  • subject - the subject

# File lib/core/message.rb, line 353
def subject=(subject)
  Cproton.pn_message_set_subject(@impl, subject)
end
to_s() click to toggle source
# File lib/core/message.rb, line 141
def to_s
  tmp = Cproton.pn_string("")
  Cproton.pn_inspect(@impl, tmp)
  result = Cproton.pn_string_get(tmp)
  Cproton.pn_free(tmp)
  return result
end
ttl() click to toggle source

Returns the time-to-live, in milliseconds.

# File lib/core/message.rb, line 252
def ttl
  Cproton.pn_message_get_ttl(@impl)
end
ttl=(time) click to toggle source

Sets the time-to-live for the message.

Options

  • time - the time in milliseconds

# File lib/core/message.rb, line 244
def ttl=(time)
  raise TypeError.new("invalid ttl: #{time}") if time.nil? || !([Float, Fixnum].include?(time.class))
  raise RangeError.new("time out of range: #{time}") if ((time < 0))
  Cproton.pn_message_set_ttl(@impl, time.floor)
end
user_id() click to toggle source

Returns the user id.

# File lib/core/message.rb, line 327
def user_id
  Cproton.pn_message_get_user_id(@impl)
end
user_id=(id) click to toggle source

Sets the user id.

Options

  • id - the user id

# File lib/core/message.rb, line 321
def user_id=(id)
  Cproton.pn_message_set_user_id(@impl, id)
end