Class: Qpid::Proton::Message
- Inherits:
-
Object
- Object
- Qpid::Proton::Message
- Defined in:
- lib/core/message.rb
Overview
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)
Class Method Summary collapse
-
.finalize!(impl) ⇒ Object
Invoked by garbage collection to clean up resources used by the underlying message implementation.
Instance Method Summary collapse
-
#[](name) ⇒ Object
Retrieves the value for the specified property name.
-
#[]=(name, value) ⇒ Object
Assigns the value given to the named property.
-
#address ⇒ Object
Returns the destination address.
-
#address=(address) ⇒ Object
Sets the destination address.
-
#annotations ⇒ Object
Returns the annotations for this message.
-
#annotations=(annotations) ⇒ Object
Assigns annotations to this message.
-
#body ⇒ Object
Returns the body property of the message.
-
#body=(body) ⇒ Object
Assigns a new value to the body of the message.
-
#clear ⇒ Object
Clears the state of the
Message
. -
#content ⇒ Object
Returns the message content.
-
#content=(content) ⇒ Object
Sets the message content.
-
#content_encoding ⇒ Object
Returns the content encoding type.
-
#content_encoding=(encoding) ⇒ Object
Sets the content encoding type.
-
#content_type ⇒ Object
Returns the content type.
-
#content_type=(content_type) ⇒ Object
Sets the content type.
-
#correlation_id ⇒ Object
Returns the correlation id.
-
#correlation_id=(id) ⇒ Object
Sets the correlation id.
-
#creation_time ⇒ Object
Returns the creation time.
-
#creation_time=(time) ⇒ Object
Sets the creation time.
-
#decode(encoded) ⇒ Object
Decodes a message from supplied AMQP data and returns the number of bytes consumed.
-
#delete_property(name) ⇒ Object
Deletes the named property.
-
#delivery_count ⇒ Object
Returns the delivery count for the message.
-
#delivery_count=(count) ⇒ Object
Sets the delivery count for the message.
-
#durable ⇒ Object
Returns the durable property.
-
#durable=(state) ⇒ Object
Sets the durable flag.
-
#encode ⇒ Object
Encodes the message.
-
#errno ⇒ Object
Returns the most recent error number.
-
#error ⇒ Object
Returns the most recent error message.
-
#error? ⇒ Boolean
Returns whether there is currently an error reported.
-
#expires ⇒ Object
Returns the expiration time.
-
#expires=(time) ⇒ Object
Sets the expiration time.
-
#first_acquirer=(state) ⇒ Object
Sets whether this is the first time the message was acquired.
-
#first_acquirer? ⇒ Boolean
Returns whether this is the first acquirer.
-
#group_id ⇒ Object
Returns the group id.
-
#group_id=(id) ⇒ Object
Sets the group id.
-
#group_sequence ⇒ Object
Returns the group sequence number.
-
#group_sequence=(seq) ⇒ Object
Sets the group sequence number.
-
#id ⇒ Object
Returns the message id.
-
#id=(id) ⇒ Object
Sets the message id.
-
#impl ⇒ Object
Returns the underlying message implementation.
-
#initialize ⇒ Message
constructor
Creates a new
Message
instance. -
#instructions ⇒ Object
Returns the instructions for this message.
-
#instructions=(instr) ⇒ Object
Assigns instructions to this message.
-
#post_decode ⇒ Object
:nodoc:.
-
#pre_encode ⇒ Object
:nodoc:.
-
#priority ⇒ Object
Returns the priority.
-
#priority=(priority) ⇒ Object
Sets the priority.
-
#properties ⇒ Object
Returns the list of property names for associated with this message.
-
#properties=(properties) ⇒ Object
Replaces the entire set of properties with the specified hash.
-
#reply_to ⇒ Object
Returns the reply-to address.
-
#reply_to=(address) ⇒ Object
Sets the reply-to address.
-
#reply_to_group_id ⇒ Object
Returns the reply-to group id.
-
#reply_to_group_id=(id) ⇒ Object
Sets the reply-to group id.
-
#subject ⇒ Object
Returns the subject.
-
#subject=(subject) ⇒ Object
Sets the subject.
- #to_s ⇒ Object
-
#ttl ⇒ Object
Returns the time-to-live, in milliseconds.
-
#ttl=(time) ⇒ Object
Sets the time-to-live for the message.
-
#user_id ⇒ Object
Returns the user id.
-
#user_id=(id) ⇒ Object
Sets the user id.
Constructor Details
#initialize ⇒ Message
Creates a new Message
instance.
132 133 134 135 136 137 138 139 |
# File 'lib/core/message.rb', line 132 def initialize @impl = Cproton. ObjectSpace.define_finalizer(self, self.class.finalize!(@impl)) @properties = {} @instructions = {} @annotations = {} @body = nil end |
Class Method Details
.finalize!(impl) ⇒ Object
Invoked by garbage collection to clean up resources used by the underlying message implementation.
151 152 153 154 155 |
# File 'lib/core/message.rb', line 151 def self.finalize!(impl) # :nodoc: proc { Cproton.(impl) } end |
Instance Method Details
#[](name) ⇒ Object
Retrieves the value for the specified property name. If not found, then it returns nil.
576 577 578 |
# File 'lib/core/message.rb', line 576 def [](name) @properties[name] end |
#[]=(name, value) ⇒ Object
Assigns the value given to the named property.
Arguments
-
name - the property name
-
value - the property value
569 570 571 |
# File 'lib/core/message.rb', line 569 def []=(name, value) @properties[name] = value end |
#address ⇒ Object
Returns the destination address.
343 344 345 |
# File 'lib/core/message.rb', line 343 def address Cproton.(@impl) end |
#address=(address) ⇒ Object
Sets the destination address.
Options
-
address - the address
337 338 339 |
# File 'lib/core/message.rb', line 337 def address=(address) Cproton.(@impl, address) end |
#annotations ⇒ Object
Returns the annotations for this message.
600 601 602 |
# File 'lib/core/message.rb', line 600 def annotations @annotations end |
#annotations=(annotations) ⇒ Object
Assigns annotations to this message.
606 607 608 |
# File 'lib/core/message.rb', line 606 def annotations=(annotations) @annotations = annotations end |
#body ⇒ Object
Returns the body property of the message.
612 613 614 |
# File 'lib/core/message.rb', line 612 def body @body end |
#body=(body) ⇒ Object
Assigns a new value to the body of the message.
618 619 620 |
# File 'lib/core/message.rb', line 618 def body=(body) @body = body end |
#clear ⇒ Object
Clears the state of the Message
. This allows a single instance of Message
to be reused.
165 166 167 168 169 170 171 |
# File 'lib/core/message.rb', line 165 def clear Cproton.(@impl) @properties.clear unless @properties.nil? @instructions.clear unless @instructions.nil? @annotations.clear unless @annotations.nil? @body = nil end |
#content ⇒ Object
Returns the message content.
WARNING: This method has been deprecated. Please use #body instead to retrieve the content of a message.
429 430 431 432 433 434 435 436 437 438 439 440 441 442 |
# File 'lib/core/message.rb', line 429 def content size = 16 loop do result = Cproton.(@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) ⇒ Object
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
420 421 422 |
# File 'lib/core/message.rb', line 420 def content=(content) Cproton.(@impl, content) end |
#content_encoding ⇒ Object
Returns the content encoding type.
456 457 458 |
# File 'lib/core/message.rb', line 456 def content_encoding Cproton.(@impl) end |
#content_encoding=(encoding) ⇒ Object
Sets the content encoding type.
Options
-
encoding - the content encoding
450 451 452 |
# File 'lib/core/message.rb', line 450 def content_encoding=(encoding) Cproton.(@impl, encoding) end |
#content_type ⇒ Object
Returns the content type
407 408 409 |
# File 'lib/core/message.rb', line 407 def content_type Cproton.(@impl) end |
#content_type=(content_type) ⇒ Object
Sets the content type.
Options
-
content_type - the content type
401 402 403 |
# File 'lib/core/message.rb', line 401 def content_type=(content_type) Cproton.(@impl, content_type) end |
#correlation_id ⇒ Object
Returns the correlation id.
391 392 393 |
# File 'lib/core/message.rb', line 391 def correlation_id Cproton.(@impl) end |
#correlation_id=(id) ⇒ Object
Sets the correlation id.
Options
-
id - the correlation id
385 386 387 |
# File 'lib/core/message.rb', line 385 def correlation_id=(id) Cproton.(@impl, id) end |
#creation_time ⇒ Object
Returns the creation time.
492 493 494 |
# File 'lib/core/message.rb', line 492 def creation_time Cproton.(@impl) end |
#creation_time=(time) ⇒ Object
Sets the creation time.
Options
-
time - the creation time
484 485 486 487 488 |
# 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.(@impl, time) end |
#decode(encoded) ⇒ Object
Decodes a message from supplied AMQP data and returns the number of bytes consumed.
Options
-
encoded - the encoded data
61 62 63 64 65 |
# File 'lib/core/message.rb', line 61 def decode(encoded) check(Cproton.(@impl, encoded, encoded.length)) post_decode end |
#delete_property(name) ⇒ Object
Deletes the named property.
582 583 584 |
# File 'lib/core/message.rb', line 582 def delete_property(name) @properties.delete(name) end |
#delivery_count ⇒ Object
Returns the delivery count for the message.
This is the number of delivery attempts for the given message.
288 289 290 |
# File 'lib/core/message.rb', line 288 def delivery_count Cproton.(@impl) end |
#delivery_count=(count) ⇒ Object
Sets the delivery count for the message.
See ::delivery_count for more details.
Options
-
count - the delivery count
277 278 279 280 281 282 |
# 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.(@impl, count.floor) end |
#durable ⇒ Object
214 215 216 |
# File 'lib/core/message.rb', line 214 def durable Cproton.(@impl) end |
#durable=(state) ⇒ Object
Sets the durable flag.
See ::durable for more details on message durability.
Options
-
state - the durable state
199 200 201 202 |
# File 'lib/core/message.rb', line 199 def durable=(state) raise TypeError.new("state cannot be nil") if state.nil? Cproton.(@impl, state) end |
#encode ⇒ Object
Encodes the message.
92 93 94 95 96 97 98 99 100 101 102 103 104 |
# File 'lib/core/message.rb', line 92 def encode pre_encode size = 16 loop do error, data = Cproton::(@impl, size) if error == Qpid::Proton::Error::OVERFLOW size *= 2 else check(error) return data end end end |
#errno ⇒ Object
Returns the most recent error number.
175 176 177 |
# File 'lib/core/message.rb', line 175 def errno Cproton.(@impl) end |
#error ⇒ Object
Returns the most recent error message.
181 182 183 |
# File 'lib/core/message.rb', line 181 def error Cproton.pn_error_text(Cproton.(@impl)) end |
#error? ⇒ Boolean
Returns whether there is currently an error reported.
187 188 189 |
# File 'lib/core/message.rb', line 187 def error? !Cproton.(@impl).zero? end |
#expires ⇒ Object
Returns the expiration time.
474 475 476 |
# File 'lib/core/message.rb', line 474 def expires Cproton.(@impl) end |
#expires=(time) ⇒ Object
Sets the expiration time.
Options
-
time - the expiry time
466 467 468 469 470 |
# 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.(@impl, time) end |
#first_acquirer=(state) ⇒ Object
Sets whether this is the first time the message was acquired.
See ::first_acquirer? for more details.
Options
-
state - true if claiming the message
264 265 266 267 |
# 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.(@impl, state) end |
#first_acquirer? ⇒ Boolean
Returns whether this is the first acquirer.
295 296 297 |
# File 'lib/core/message.rb', line 295 def first_acquirer? Cproton.(@impl) end |
#group_id ⇒ Object
Returns the group id.
508 509 510 |
# File 'lib/core/message.rb', line 508 def group_id Cproton.(@impl) end |
#group_id=(id) ⇒ Object
Sets the group id.
Options
-
id - the group id
502 503 504 |
# File 'lib/core/message.rb', line 502 def group_id=(id) Cproton.(@impl, id) end |
#group_sequence ⇒ Object
Returns the group sequence number.
525 526 527 |
# File 'lib/core/message.rb', line 525 def group_sequence Cproton.(@impl) end |
#group_sequence=(seq) ⇒ Object
Sets the group sequence number.
Options
-
seq - the sequence number
518 519 520 521 |
# File 'lib/core/message.rb', line 518 def group_sequence=(seq) raise TypeError.new("invalid seq: #{seq}") if seq.nil? Cproton.(@impl, seq) end |
#id ⇒ Object
Returns the message id.
311 312 313 |
# File 'lib/core/message.rb', line 311 def id Cproton.(@impl) end |
#id=(id) ⇒ Object
Sets the message id.
Options
-
id = the id
305 306 307 |
# File 'lib/core/message.rb', line 305 def id=(id) Cproton.(@impl, id) end |
#impl ⇒ Object
Returns the underlying message implementation.
158 159 160 |
# File 'lib/core/message.rb', line 158 def impl # :nodoc: @impl end |
#instructions ⇒ Object
Returns the instructions for this message.
588 589 590 |
# File 'lib/core/message.rb', line 588 def instructions @instructions end |
#instructions=(instr) ⇒ Object
Assigns instructions to this message.
594 595 596 |
# File 'lib/core/message.rb', line 594 def instructions=(instr) @instructions = instr end |
#post_decode ⇒ Object
:nodoc:
67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 |
# File 'lib/core/message.rb', line 67 def post_decode # :nodoc: # decode elements from the message @properties = {} props = Codec::Data.new(Cproton::(@impl)) if props.next @properties = props.type.get(props) end @instructions = nil insts = Codec::Data.new(Cproton::(@impl)) if insts.next @instructions = insts.type.get(insts) end @annotations = nil annts = Codec::Data.new(Cproton::(@impl)) if annts.next @annotations = annts.type.get(annts) end @body = nil body = Codec::Data.new(Cproton::(@impl)) if body.next @body = body.type.get(body) end end |
#pre_encode ⇒ Object
:nodoc:
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 |
# File 'lib/core/message.rb', line 106 def pre_encode # :nodoc: # encode elements from the message props = Codec::Data.new(Cproton::(@impl)) props.clear Codec::Mapping.for_class(@properties.class).put(props, @properties) unless @properties.empty? insts = Codec::Data.new(Cproton::(@impl)) insts.clear if !@instructions.nil? mapping = Codec::Mapping.for_class(@instructions.class) mapping.put(insts, @instructions) end annts = Codec::Data.new(Cproton::(@impl)) annts.clear if !@annotations.nil? mapping = Codec::Mapping.for_class(@annotations.class) mapping.put(annts, @annotations, :keys => :SYMBOL) end body = Codec::Data.new(Cproton::(@impl)) body.clear if !@body.nil? mapping = Codec::Mapping.for_class(@body.class) mapping.put(body, @body) end end |
#priority ⇒ Object
Returns the priority.
234 235 236 |
# File 'lib/core/message.rb', line 234 def priority Cproton.(@impl) end |
#priority=(priority) ⇒ Object
Sets the priority.
NOTE:
Priority values are limited to the range [0,255].
Options
-
priority - the priority value
226 227 228 229 230 |
# 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.(@impl, priority.floor) end |
#properties ⇒ Object
Returns the list of property names for associated with this message.
Examples
msg.properties.each do |name|
end
552 553 554 |
# File 'lib/core/message.rb', line 552 def properties @properties end |
#properties=(properties) ⇒ Object
Replaces the entire set of properties with the specified hash.
558 559 560 |
# File 'lib/core/message.rb', line 558 def properties=(properties) @properties = properties end |
#reply_to ⇒ Object
Returns the reply-to address
375 376 377 |
# File 'lib/core/message.rb', line 375 def reply_to Cproton.(@impl) end |
#reply_to=(address) ⇒ Object
Sets the reply-to address.
Options
-
address - the reply-to address
369 370 371 |
# File 'lib/core/message.rb', line 369 def reply_to=(address) Cproton.(@impl, address) end |
#reply_to_group_id ⇒ Object
Returns the reply-to group id.
541 542 543 |
# File 'lib/core/message.rb', line 541 def reply_to_group_id Cproton.(@impl) end |
#reply_to_group_id=(id) ⇒ Object
Sets the reply-to group id.
Options
-
id - the id
535 536 537 |
# File 'lib/core/message.rb', line 535 def reply_to_group_id=(id) Cproton.(@impl, id) end |
#subject ⇒ Object
Returns the subject
359 360 361 |
# File 'lib/core/message.rb', line 359 def subject Cproton.(@impl) end |
#subject=(subject) ⇒ Object
Sets the subject.
Options
-
subject - the subject
353 354 355 |
# File 'lib/core/message.rb', line 353 def subject=(subject) Cproton.(@impl, subject) end |
#to_s ⇒ Object
141 142 143 144 145 146 147 |
# 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 ⇒ Object
Returns the time-to-live, in milliseconds.
252 253 254 |
# File 'lib/core/message.rb', line 252 def ttl Cproton.(@impl) end |
#ttl=(time) ⇒ Object
Sets the time-to-live for the message.
Options
-
time - the time in milliseconds
244 245 246 247 248 |
# 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.(@impl, time.floor) end |
#user_id ⇒ Object
Returns the user id.
327 328 329 |
# File 'lib/core/message.rb', line 327 def user_id Cproton.(@impl) end |
#user_id=(id) ⇒ Object
Sets the user id.
Options
-
id - the user id
321 322 323 |
# File 'lib/core/message.rb', line 321 def user_id=(id) Cproton.(@impl, id) end |