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¶ ↑

#content_type - the content type

# 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