Class Qpid::Proton::Codec::Data
In: lib/codec/data.rb
Parent: Object

The Data class provides an interface for decoding, extracting, creating, and encoding arbitrary AMQP data. A Data object contains a tree of AMQP values. Leaf nodes in this tree correspond to scalars in the AMQP type system such as INT or STRING. Interior nodes in this tree correspond to compound values in the AMQP type system such as LIST,MAP, ARRAY, or DESCRIBED. The root node of the tree is the Data object itself and can have an arbitrary number of children.

A Data object maintains the notion of the current sibling node and a current parent node. Siblings are ordered within their parent. Values are accessed and/or added by using the next, prev, enter, and exit methods to navigate to the desired location in the tree and using the supplied variety of mutator and accessor methods to access or add a value of the desired type.

The mutator methods will always add a value after the current node in the tree. If the current node has a next sibling the mutator method will overwrite the value on this node. If there is no current node or the current node has no next sibling then one will be added. The accessor methods always set the added/modified node to the current node. The accessor methods read the value of the current node and do not change which node is current.

The following types of scalar values are supported:

  • NULL
  • BOOL
  • UBYTE
  • BYTE
  • USHORT
  • SHORT
  • UINT
  • INT
  • CHAR
  • ULONG
  • LONG
  • TIMESTAMP
  • FLOAT
  • DOUBLE
  • DECIMAL32
  • DECIMAL64
  • DECIMAL128
  • UUID
  • BINARY
  • STRING
  • SYMBOL

The following types of compound values are supported:

  • DESCRIBED
  • ARRAY
  • LIST
  • MAP

Methods

array   binary   binary=   bool   bool=   byte   byte=   char   char=   clear   decimal128   decimal128=   decimal32   decimal32=   decimal64   decimal64=   decode   described?   double   double=   encode   enter   exit   finalize!   float   float=   get   get_array   get_described   get_map   int   int=   list   long   long=   map   new   next   null   null=   null?   object   object=   prev   put   put_array   put_described   put_list   put_map   rewind   short   short=   string   string=   symbol   symbol=   timestamp   timestamp=   to_s   type   type_code   ubyte   ubyte=   uint   uint=   ulong   ulong=   ushort   ushort=   uuid   uuid=  

Public Class methods

Creates a new instance with the specified capacity.

@param capacity [Fixnum, Object] The initial capacity or content.

Public Instance methods

If the current node is an array, returns a tuple of the element count, a boolean indicating whether the array is described, and the type of each element. Otherwise it returns +(0, false, nil).

Array data can be accessed by entering the array.

@example

  # get the details of thecurrent array
  count, described, array_type = @data.array

  # enter the node
  data.enter

  # get the next node
  data.next
  puts "Descriptor: #{data.symbol}" if described
  (0...count).each do
    @data.next
    puts "Element: #{@data.string}"
  end

If the current node is binary, returns its value. Otherwise, it returns an empty string ("").

@return [String] The binary string.

@see string

Puts a binary value.

A binary string is encoded as an ASCII 8-bit string value. This is in contranst to other strings, which are treated as UTF-8 encoded.

@param value [String] An arbitrary string value.

@see string=

If the current node is a boolean, then it returns the value. Otherwise, it returns false.

@return [Boolean] The boolean value.

Puts a boolean value.

@param value [Boolean] The boolean value.

If the current node is an byte, returns its value. Otherwise, it returns 0.

@return [Fixnum] The byte value.

Puts a byte value.

@param value [Fixnum] The byte value.

If the current node is a character, returns its value. Otherwise, returns 0.

@return [Fixnum] The character value.

Puts a character value.

@param value [Fixnum] The character value.

Clears the object.

If the current node is a decimal128, returns its value. Otherwise, returns 0.

@return [Fixnum] The decimal128 value.

Puts a decimal128 value.

@param value [Fixnum] The decimal128 value.

If the current node is a decimal32, returns its value. Otherwise, returns 0.

@return [Fixnum] The decimal32 value.

Puts a decimal32 value.

@param value [Fixnum] The decimal32 value.

If the current node is a decimal64, returns its value. Otherwise, it returns 0.

@return [Fixnum] The decimal64 value.

Puts a decimal64 value.

@param value [Fixnum] The decimal64 value.

Decodes the first value from supplied AMQP data and returns the number of bytes consumed.

@param encoded [String] The encoded data.

@example

  # SCENARIO: A string of encoded data, @encoded, contains the text
  #           of "This is a test." and is passed to an instance of Data
  #           for decoding.

  @data.decode(@encoded)
  @data.string #=> "This is a test."

Checks if the current node is a described value.

The described and value may be accessed by entering the described value.

@example

  if @data.described?
    @data.enter
    puts "The symbol is #{@data.symbol}"
    puts "The value is #{@data.string}"
  end

If the current node is a double, returns its value. Otherwise, returns 0.

@return [Float] The double precision floating point value.

Puts a double value.

@param value [Float] The double precision floating point value.

Returns a representation of the data encoded in AMQP format.

@return [String] The context of the Data as an AMQP data string.

@example

  @data.string = "This is a test."
  @encoded = @data.encode

  # @encoded now contains the text "This is a test." encoded for
  # AMQP transport.

Sets the parent node to the current node and clears the current node.

Clearing the current node sets it before the first child.

Sets the current node to the parent node and the parent node to its own parent.

If the current node is a float, returns its value. Otherwise, returns 0.

@return [Float] The floating point value.

Puts a float value.

@param value [Float] The floating point value.

Get the current value as a single object.

@return [Object] The current node‘s object.

@see type_code @see type

@private

@private

If the current node is an integer, returns its value. Otherwise, returns 0.

@return [Fixnum] The integer value.

Puts an integer value.

Options

  • value - the integer value

If the current node is a list, this returns the number of elements. Otherwise, it returns zero.

List elements can be accessed by entering the list.

@example

  count = @data.list
  @data.enter
  (0...count).each
    type = @data.next
    puts "Value: #{@data.string}" if type == STRING
    # ... process other node types
  end

If the current node is a long, returns its value. Otherwise, returns 0.

@return [Fixnum] The long value.

Puts a long value.

@param value [Fixnum] The long value.

If the current node is a map, this returns the number of child elements. Otherwise, it returns zero.

Key/value pairs can be accessed by entering the map.

@example

  count = @data.map
  @data.enter
  (0...count).each do
    type = @data.next
    puts "Key=#{@data.string}" if type == STRING
    # ... process other key types
    type = @data.next
    puts "Value=#{@data.string}" if type == STRING
    # ... process other value types
  end
  @data.exit

Advances the current node to its next sibling and returns its types.

If there is no next sibling the current node remains unchanged and nil is returned.

Puts a null value.

Utility method for Qpid::Proton::Codec::Mapping

@private

Checks if the current node is null.

@return [Boolean] True if the node is null.

Gets the current node, based on how it was encoded.

@return [Object] The current node.

Puts an arbitrary object type.

The Data instance will determine which AMQP type is appropriate and will use that to encode the object.

@param object [Object] The value.

Advances the current node to its previous sibling and returns its type.

If there is no previous sibling then the current node remains unchanged and nil is return.

Puts a new value with the given type into the current node.

@param value [Object] The value. @param type_code [Mapping] The value‘s type.

@private

Puts an array value.

Elements may be filled by entering the array node and putting the element values. The values must all be of the specified array element type.

If an array is described then the first child value of the array is the descriptor and may be of any type.

@param described [Boolean] True if the array is described. @param element_type [Fixnum] The AMQP type for each element of the array.

@example

  # create an array of integer values
  data = Qpid::Proton::Codec::Data.new
  data.put_array(false, INT)
  data.enter
  data.int = 1
  data.int = 2
  data.int = 3
  data.exit

  # create a described  array of double values
  data.put_array(true, DOUBLE)
  data.enter
  data.symbol = "array-descriptor"
  data.double = 1.1
  data.double = 1.2
  data.double = 1.3
  data.exit

Puts a described value.

A described node has two children, the descriptor and the value. These are specified by entering the node and putting the desired values.

@example

  data = Qpid::Proton::Codec::Data.new
  data.put_described
  data.enter
  data.symbol = "value-descriptor"
  data.string = "the value"
  data.exit

Puts a list value.

Elements may be filled by entering the list node and putting element values.

@example

  data = Qpid::Proton::Codec::Data.new
  data.put_list
  data.enter
  data.int = 1
  data.int = 2
  data.int = 3
  data.exit

Puts a map value.

Elements may be filled by entering the map node and putting alternating key/value pairs.

@example

  data = Qpid::Proton::Codec::Data.new
  data.put_map
  data.enter
  data.string = "key"
  data.string = "value"
  data.exit

Clears the current node and sets the parent to the root node.

Clearing the current node sets it before the first node, calling next will advance to the first node.

If the current node is a short, returns its value. Otherwise, returns a 0.

@return [Fixnum] The short value.

Puts a short value.

@param value [Fixnum] The short value.

If the current node is a string, returns its value. Otherwise, it returns an empty string ("").

@return [String] The UTF-8 encoded string.

@see binary

Puts a UTF-8 encoded string value.

*NOTE:* A nil value is stored as an empty string rather than as a nil.

@param value [String] The UTF-8 encoded string value.

@see binary=

If the current node is a symbol, returns its value. Otherwise, it returns an empty string ("").

@return [String] The symbolic string value.

Puts a symbolic value.

@param value [String] The symbolic string value.

If the current node is a timestamp, returns its value. Otherwise, returns 0.

@return [Fixnum] The timestamp value.

Puts a timestamp value.

@param value [Fixnum] The timestamp value.

@private

Return the type object for the current node

@param [Fixnum] The object type.

@see type_code

Returns the numeric type code of the current node.

@return [Fixnum] The current node type. @return [nil] If there is no current node.

If the current node is an unsigned byte, returns its value. Otherwise, it returns 0.

@return [Fixnum] The unsigned byte value.

Puts an unsigned byte value.

@param value [Fixnum] The unsigned byte value.

If the current node is an unsigned int, returns its value. Otherwise, returns 0.

@return [Fixnum] The unsigned integer value.

Puts an unsigned integer value.

@param value [Fixnum] the unsigned integer value

If the current node is an unsigned long, returns its value. Otherwise, returns 0.

@return [Fixnum] The unsigned long value.

Puts an unsigned long value.

@param value [Fixnum] The unsigned long value.

If the current node is an unsigned short, returns its value. Otherwise, it returns 0.

@return [Fixnum] The unsigned short value.

Puts an unsigned short value.

@param value [Fixnum] The unsigned short value

If the current value is a UUID, returns its value. Otherwise, it returns nil.

@return [String] The string representation of the UUID.

Puts a UUID value.

The UUID is expected to be in the format of a string or else a 128-bit integer value.

@param value [String, Numeric] A string or numeric representation of the UUID.

@example

  # set a uuid value from a string value
  require 'securerandom'
  @data.uuid = SecureRandom.uuid

  # or
  @data.uuid = "fd0289a5-8eec-4a08-9283-81d02c9d2fff"

  # set a uuid value from a 128-bit value
  @data.uuid = 0 # sets to 00000000-0000-0000-0000-000000000000

[Validate]