Class: Qpid::Proton::Message

Inherits:
Object
  • Object
show all
Defined in:
lib/core/message.rb

Overview

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.

Examples:

Create a message containing a Unicode string

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

Create a message containing binary data

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(body = nil, opts = {}) ⇒ Message

Creates a new Message instance.

Parameters:

  • body (defaults to: nil) —

    the body of the message, equivalent to calling m.body=(body)

  • opts (Hash) (defaults to: {}) —

    additional options, equivalent to Message#key=value for each key=>value



85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# 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

Instance Attribute Details

#annotations ⇒ Hash

Returns Delivery annotations for this message.

Returns:

  • (Hash) —

    Delivery annotations for this message.



499
500
501
 
# File 'lib/core/message.rb', line 499

def annotations
  @annotations
end

#body ⇒ Object

Returns body of the message.

Returns:

  • (Object) —

    body of the message.



502
503
504
 
# File 'lib/core/message.rb', line 502

def body
  @body
end

#instructions ⇒ Hash

Returns Delivery instructions for this message.

Returns:

  • (Hash) —

    Delivery instructions for this message.



496
497
498
 
# File 'lib/core/message.rb', line 496

def instructions
  @instructions
end

#properties ⇒ Hash

Returns Application properties for the message.

Returns:

  • (Hash) —

    Application properties for the message



484
485
486
 
# File 'lib/core/message.rb', line 484

def properties
  @properties
end

Class Method Details

.finalize!(impl)

Invoked by garbage collection to clean up resources used by the underlying message implementation.



103
104
105
106
107
 
# File 'lib/core/message.rb', line 103

def self.finalize!(impl) # :nodoc:
  proc {
    Cproton.pn_message_free(impl)
  }
end

Instance Method Details

#[](name)

Equivalent to #properties



490
 
# File 'lib/core/message.rb', line 490

def [](name) @properties[name]; end

#[]=(name, value)

Equivalent to #properties = value



487
 
# File 'lib/core/message.rb', line 487

def []=(name, value) @properties[name] = value; end

#clear

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



117
118
119
120
121
122
123
 
# 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

Deprecated.

use #body



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
 
# 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)

Deprecated.

use #body=



360
361
362
363
 
# File 'lib/core/message.rb', line 360

def content=(content)
  deprecated __method__, "body="
  Cproton.pn_message_load(@impl, content)
end

#content_encoding

Returns the content encoding type.



394
395
396
 
# File 'lib/core/message.rb', line 394

def content_encoding
  Cproton.pn_message_get_content_encoding(@impl)
end

#content_encoding=(encoding)

Sets the content encoding type.

Options

  • encoding - the content encoding



388
389
390
 
# File 'lib/core/message.rb', line 388

def content_encoding=(encoding)
  Cproton.pn_message_set_content_encoding(@impl, encoding)
end

#content_type

Returns the content type



355
356
357
 
# File 'lib/core/message.rb', line 355

def content_type
  Cproton.pn_message_get_content_type(@impl)
end

#content_type=(content_type)

Sets the content type.

Options

  • content_type - the content type



349
350
351
 
# File 'lib/core/message.rb', line 349

def content_type=(content_type)
  Cproton.pn_message_set_content_type(@impl, content_type)
end

#correlation_id

Returns the correlation id.



339
340
341
 
# File 'lib/core/message.rb', line 339

def correlation_id
  Cproton.pn_message_get_correlation_id(@impl)
end

#correlation_id=(id)

Sets the correlation id.

Options

  • id - the correlation id



333
334
335
 
# File 'lib/core/message.rb', line 333

def correlation_id=(id)
  Cproton.pn_message_set_correlation_id(@impl, id)
end

#creation_time

Returns the creation time.



430
431
432
 
# File 'lib/core/message.rb', line 430

def creation_time
  Cproton.pn_message_get_creation_time(@impl)
end

#creation_time=(time)

Sets the creation time.

Options

  • time - the creation time

Raises:

  • (TypeError) 


422
423
424
425
426
 
# 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)

Decodes a message from AMQP binary data. @return the number of bytes consumed

Parameters:

  • encoded (String) —

    the encoded bytes



44
45
46
47
 
# 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)

Equivalent to {#properties}.delete(name)



493
 
# File 'lib/core/message.rb', line 493

def delete_property(name) @properties.delete(name); end

#delivery_count

Returns the delivery count for the message.

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



239
240
241
 
# File 'lib/core/message.rb', line 239

def delivery_count
  Cproton.pn_message_get_delivery_count(@impl)
end

#delivery_count=(count)

Sets the delivery count for the message.

See ::delivery_count for more details.

Options

  • count - the delivery count

Raises:

  • (::ArgumentError) 


229
230
231
232
233
 
# 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

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



166
167
168
 
# File 'lib/core/message.rb', line 166

def durable
  Cproton.pn_message_is_durable(@impl)
end

#durable=(state)

Sets the durable flag.

See ::durable for more details on message durability.

Options

  • state - the durable state

Raises:

  • (TypeError) 


151
152
153
154
 
# 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

Encodes the message.



59
60
61
62
63
64
65
66
67
68
69
70
71
 
# 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

Returns the most recent error number.



127
128
129
 
# File 'lib/core/message.rb', line 127

def errno
  Cproton.pn_message_errno(@impl)
end

#error

Returns the most recent error message.



133
134
135
 
# File 'lib/core/message.rb', line 133

def error
  Cproton.pn_error_text(Cproton.pn_message_error(@impl))
end

#error? ⇒ Boolean

Returns whether there is currently an error reported.

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/core/message.rb', line 139

def error?
  !Cproton.pn_message_errno(@impl).zero?
end

#expires

Returns the expiration time.



412
413
414
 
# File 'lib/core/message.rb', line 412

def expires
  Cproton.pn_message_get_expiry_time(@impl)
end

#expires=(time)

Sets the expiration time.

Options

  • time - the expiry time

Raises:

  • (TypeError) 


404
405
406
407
408
 
# 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)

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

See ::first_acquirer? for more details.

Options

  • state - true if claiming the message

Raises:

  • (TypeError) 


216
217
218
219
 
# 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? ⇒ Boolean

Returns whether this is the first acquirer.

Returns:

  • (Boolean) 


246
247
248
 
# File 'lib/core/message.rb', line 246

def first_acquirer?
  Cproton.pn_message_is_first_acquirer(@impl)
end

#group_id

Returns the group id.



446
447
448
 
# File 'lib/core/message.rb', line 446

def group_id
  Cproton.pn_message_get_group_id(@impl)
end

#group_id=(id)

Sets the group id.

Options

  • id - the group id



440
441
442
 
# File 'lib/core/message.rb', line 440

def group_id=(id)
  Cproton.pn_message_set_group_id(@impl, id)
end

#group_sequence

Returns the group sequence number.



463
464
465
 
# File 'lib/core/message.rb', line 463

def group_sequence
  Cproton.pn_message_get_group_sequence(@impl)
end

#group_sequence=(seq)

Sets the group sequence number.

Options

  • seq - the sequence number

Raises:

  • (TypeError) 


456
457
458
459
 
# 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

Returns the message id.



262
263
264
 
# File 'lib/core/message.rb', line 262

def id
  Cproton.pn_message_get_id(@impl)
end

#id=(id)

Sets the message id.

Options

  • id = the id



256
257
258
 
# File 'lib/core/message.rb', line 256

def id=(id)
  Cproton.pn_message_set_id(@impl, id)
end

#impl

Returns the underlying message implementation.



110
111
112
 
# File 'lib/core/message.rb', line 110

def impl # :nodoc:
  @impl
end

#inspect 



504
 
# File 'lib/core/message.rb', line 504

def inspect() pre_encode; super; end

#priority

Returns the priority.



186
187
188
 
# File 'lib/core/message.rb', line 186

def priority
  Cproton.pn_message_get_priority(@impl)
end

#priority=(priority)

Sets the priority.

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

Options

  • priority - the priority value

Raises:

  • (TypeError) 


178
179
180
181
182
 
# 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

Returns the reply-to address



323
324
325
 
# File 'lib/core/message.rb', line 323

def reply_to
  Cproton.pn_message_get_reply_to(@impl)
end

#reply_to=(address)

Sets the reply-to address.

Options

  • address - the reply-to address



317
318
319
 
# File 'lib/core/message.rb', line 317

def reply_to=(address)
  Cproton.pn_message_set_reply_to(@impl, address)
end

#reply_to_group_id

Returns the reply-to group id.



479
480
481
 
# 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)

Sets the reply-to group id.

Options

  • id - the id



473
474
475
 
# 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

Returns the subject



307
308
309
 
# File 'lib/core/message.rb', line 307

def subject
  Cproton.pn_message_get_subject(@impl)
end

#subject=(subject)

Sets the subject.

Options

  • subject - the subject



301
302
303
 
# File 'lib/core/message.rb', line 301

def subject=(subject)
  Cproton.pn_message_set_subject(@impl, subject)
end

#to ⇒ String Also known as: address

Returns get the destination address.

Returns:

  • (String) —

    get the destination address.



289
290
291
 
# File 'lib/core/message.rb', line 289

def to
  Cproton.pn_message_get_address(@impl)
end

#to=(address) Also known as: address=

Parameters:

  • address (String) —

    set the destination address



283
284
285
 
# File 'lib/core/message.rb', line 283

def to=(address)
  Cproton.pn_message_set_address(@impl, address)
end

#ttl

Returns the time-to-live, in milliseconds.



204
205
206
 
# File 'lib/core/message.rb', line 204

def ttl
  Cproton.pn_message_get_ttl(@impl)
end

#ttl=(time)

Sets the time-to-live for the message.

Options

  • time - the time in milliseconds

Raises:

  • (TypeError) 


196
197
198
199
200
 
# 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

Returns the user id.



278
279
280
 
# File 'lib/core/message.rb', line 278

def user_id
  Cproton.pn_message_get_user_id(@impl)
end

#user_id=(id)

Sets the user id.

Options

  • id - the user id



272
273
274
 
# File 'lib/core/message.rb', line 272

def user_id=(id)
  Cproton.pn_message_set_user_id(@impl, id)
end