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 85
def initialize(body = nil, opts={})
  @impl = Cproton.pn_message
  ObjectSpace.define_finalizer(self, self.class.finalize!(@impl))
  @properties = {}
  @instructions = {}
  @annotations = {}
  @body = nil
  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 490
def [](name) @properties[name]; end
[]=(name, value) click to toggle source

Equivalent to +#properties = value+

# File lib/core/message.rb, line 487
def []=(name, value) @properties[name] = value; end
address()
Alias for: to
address=(address)
Alias for: to=
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 117
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 366
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 360
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 394
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 388
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 355
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 349
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 339
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 333
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 430
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 422
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 493
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 239
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 229
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 166
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 151
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 127
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 133
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 139
def error?
  !Cproton.pn_message_errno(@impl).zero?
end
expires() click to toggle source

Returns the expiration time.

# File lib/core/message.rb, line 412
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 404
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 216
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 246
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 446
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 440
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 463
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 456
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 262
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 256
def id=(id)
  Cproton.pn_message_set_id(@impl, id)
end
inspect() click to toggle source
Calls superclass method Qpid::Proton::Util::Wrapper#inspect
# File lib/core/message.rb, line 504
def inspect() pre_encode; super; 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? && @properties)
  Codec::Data.from_object(Cproton::pn_message_instructions(@impl), !@instructions.empty? && @instructions)
  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 186
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 178
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 323
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 317
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 479
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 473
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 307
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 301
def subject=(subject)
  Cproton.pn_message_set_subject(@impl, subject)
end
to() click to toggle source

@return [String] get the destination address.

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

@param address set the destination address

# File lib/core/message.rb, line 283
def to=(address)
  Cproton.pn_message_set_address(@impl, address)
end
Also aliased as: address=
ttl() click to toggle source

Returns the time-to-live, in milliseconds.

# File lib/core/message.rb, line 204
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 196
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 278
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 272
def user_id=(id)
  Cproton.pn_message_set_user_id(@impl, id)
end