class Qpid::Proton::Message

Messsage data and headers that can sent or received on a {Link}

{#body} is the main message content. {#properties} is a {Hash} of extra properties that can be attached to the message.

@example Create a message containing a Unicode string

msg = Qpid::Proton::Message.new "this is a string"

@example Create a message containing binary data

msg = Qpid::Proton::Message.new
msg.body = Qpid::Proton::BinaryString.new(File.binread("/home/qpid/binfile.tar.gz"))

Constants

PROTON_METHOD_PREFIX

@private

Attributes

annotations[RW]

@return [Hash] Delivery annotations for this message.

body[RW]

@return [Object] body of the message.

instructions[RW]

@return [Hash] Delivery instructions for this message.

properties[RW]

@return [Hash] Application properties for the message

Public Class Methods

new(body = nil, opts={}) click to toggle source

Creates a new Message instance. @param body the body of the message, equivalent to calling m.body=(body) @param opts [Hash] additional options, equivalent to +Message#key=value+ for each +key=>value+

# File lib/core/message.rb, line 92
def initialize(body = nil, opts={})
  @impl = Cproton.pn_message
  ObjectSpace.define_finalizer(self, self.class.finalize!(@impl))
  @properties = {}
  @instructions = {}
  @annotations = {}
  self.body = body unless body.nil?
  if !opts.nil? then
    opts.each do |k, v|
      setter = (k.to_s+"=").to_sym()
      self.send setter, v
    end
  end
end

Public Instance Methods

[](name) click to toggle source

Equivalent to +#properties+

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

Equivalent to +#properties = value+

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

Returns the destination address.

# File lib/core/message.rb, line 300
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 294
def address=(address)
  Cproton.pn_message_set_address(@impl, address)
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 123
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

@deprecated use {#body}

# File lib/core/message.rb, line 375
def content
  deprecated __method__, "body"
  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

@deprecated use {#body=}

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

Returns the content encoding type.

# File lib/core/message.rb, line 403
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 397
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 364
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 358
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 348
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 342
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 439
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 431
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 AMQP binary data. @param encoded [String] the encoded bytes @return the number of bytes consumed

# File lib/core/message.rb, line 44
def decode(encoded)
  check(Cproton.pn_message_decode(@impl, encoded, encoded.length))
  post_decode
end
delete_property(name) click to toggle source

Equivalent to +{#properties}.delete(name)+

# File lib/core/message.rb, line 502
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 245
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 235
def delivery_count=(count)
  raise ::ArgumentError.new("invalid count: #{count}") if not count.is_a?(Numeric)
  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 172
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 157
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 59
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 133
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 139
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 145
def error?
  !Cproton.pn_message_errno(@impl).zero?
end
expires() click to toggle source

Returns the expiration time.

# File lib/core/message.rb, line 421
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 413
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 222
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 252
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 455
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 449
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 472
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 465
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 268
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 262
def id=(id)
  Cproton.pn_message_set_id(@impl, id)
end
post_decode() click to toggle source

@private

# File lib/core/message.rb, line 50
def post_decode
  # decode elements from the message
  @properties = Codec::Data.to_object(Cproton::pn_message_properties(@impl)) || {}
  @instructions = Codec:: Data.to_object(Cproton::pn_message_instructions(@impl)) || {}
  @annotations = Codec::Data.to_object(Cproton::pn_message_annotations(@impl)) || {}
  @body = Codec::Data.to_object(Cproton::pn_message_body(@impl))
end
pre_encode() click to toggle source

@private

# File lib/core/message.rb, line 74
def pre_encode
  # encode elements from the message
  Codec::Data.from_object(Cproton::pn_message_properties(@impl),
                          !@properties.empty? && Types.symbol_keys!(@properties))
  Codec::Data.from_object(Cproton::pn_message_instructions(@impl),
                          !@instructions.empty? && Types.symbol_keys!(@instructions))
  if @annotations           # Make sure keys are symbols
    @annotations.keys.each do |k|
      @annotations[k.to_sym] = @annotations.delete(k) unless k.is_a? Symbol
    end
  end
  Codec::Data.from_object(Cproton::pn_message_annotations(@impl), !@annotations.empty? && @annotations)
  Codec::Data.from_object(Cproton::pn_message_body(@impl), @body)
end
priority() click to toggle source

Returns the priority.

# File lib/core/message.rb, line 192
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 184
def priority=(priority)
  raise TypeError.new("invalid priority: #{priority}") if not priority.is_a?(Numeric)
  raise RangeError.new("priority out of range: #{priority}") if ((priority > 255) || (priority < 0))
  Cproton.pn_message_set_priority(@impl, priority.floor)
end
reply_to() click to toggle source

Returns the reply-to address

# File lib/core/message.rb, line 332
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 326
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 488
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 482
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 316
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 310
def subject=(subject)
  Cproton.pn_message_set_subject(@impl, subject)
end
ttl() click to toggle source

Returns the time-to-live, in milliseconds.

# File lib/core/message.rb, line 210
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 202
def ttl=(time)
  raise TypeError.new("invalid ttl: #{time}") if not time.is_a?(Numeric)
  raise RangeError.new("ttl out of range: #{time}") if ((time.to_i < 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 284
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 278
def user_id=(id)
  Cproton.pn_message_set_user_id(@impl, id)
end