qpid_proton 0.9.0 → 0.10

data/lib/qpid_proton/data.rb

@@ -1,788 +0,0 @@
-#--
-# Licensed to the Apache Software Foundation (ASF) under one
-# or more contributor license agreements.  See the NOTICE file
-# distributed with this work for additional information
-# regarding copyright ownership.  The ASF licenses this file
-# to you under the Apache License, Version 2.0 (the
-# "License"); you may not use this file except in compliance
-# with the License.  You may obtain a copy of the License at
-#
-#   http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing,
-# software distributed under the License is distributed on an
-# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-# KIND, either express or implied.  See the License for the
-# specific language governing permissions and limitations
-# under the License.
-#++
-
-module Qpid # :nodoc:
-
-  module Proton # :nodoc:
-
-    # +DataError+ is raised when an error occurs while encoding
-    # or decoding data.
-    class DataError < Exception; end
-
-    # 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*
-    #
-    class Data
-
-      # Creates a new instance with the specified capacity.
-      #
-      # ==== Options
-      #
-      # * capacity - the capacity
-      #
-      def initialize(capacity = 16)
-        if (!capacity.nil?) &&
-            (capacity.is_a?(Fixnum) ||
-             capacity.is_a?(Bignum))
-          @data = Cproton.pn_data(capacity)
-          @free = true
-        else
-          @data = capacity
-          @free = false
-        end
-
-        # destructor
-        ObjectSpace.define_finalizer(self, self.class.finalize!(@data))
-      end
-
-      def self.finalize!(data) # :nodoc:
-        proc {
-          Cproton.pn_data_free(data) if @free
-        }
-      end
-
-      def to_s
-        tmp = Cproton.pn_string("")
-        Cproton.pn_inspect(@data, tmp)
-        result = Cproton.pn_string_get(tmp)
-        Cproton.pn_free(tmp)
-        return result
-      end
-
-      # Clears the object.
-      def clear
-        Cproton.pn_data_clear(@data)
-      end
-
-      # 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.
-      def rewind
-        Cproton.pn_data_rewind(@data)
-      end
-
-      # 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.
-      def next(print = false)
-        Cproton.pn_data_next(@data)
-      end
-
-      # 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.
-      def prev
-        return Cproton.pn_data_prev(@data) ? type : nil
-      end
-
-      # Sets the parent node to the current node and clears the current node.
-      #
-      # Clearing the current node sets it _before_ the first child.
-      def enter
-        Cproton.pn_data_enter(@data)
-      end
-
-      # Sets the current node to the parent node and the parent node to its own
-      # parent.
-      def exit
-        Cproton.pn_data_exit(@data)
-      end
-
-      # Returns the numeric type code of the current node.
-      def type_code
-        dtype = Cproton.pn_data_type(@data)
-        return (dtype == -1) ? nil : dtype
-      end
-
-      # Return the Type object for the current node
-      def type
-        Mapping.for_code(type_code)
-      end
-
-      # Returns a representation of the data encoded in AMQP format.
-      def encode
-        buffer = "\0"*1024
-        loop do
-          cd = Cproton.pn_data_encode(@data, buffer, buffer.length)
-          if cd == Cproton::PN_OVERFLOW
-            buffer *= 2
-          elsif cd >= 0
-            return buffer[0...cd]
-          else
-            check(cd)
-          end
-        end
-      end
-
-      # Decodes the first value from supplied AMQP data and returns the number
-      # of bytes consumed.
-      #
-      # ==== Options
-      #
-      # * encoded - the encoded data
-      #
-      def decode(encoded)
-        check(Cproton.pn_data_decode(@data, encoded, encoded.length))
-      end
-
-      # Puts a list value.
-      #
-      # Elements may be filled by entering the list node and putting element
-      # values.
-      #
-      # ==== Examples
-      #
-      #   data = Qpid::Proton::Data.new
-      #   data.put_list
-      #   data.enter
-      #   data.int = 1
-      #   data.int = 2
-      #   data.int = 3
-      #   data.exit
-      #
-      def put_list
-        check(Cproton.pn_data_put_list(@data))
-      end
-
-      # 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.
-      #
-      # ==== Examples
-      #
-      #   count = @data.list
-      #   @data.enter
-      #   (0...count).each
-      #     type = @data.next
-      #     puts "Value: #{@data.string}" if type == STRING
-      #     # ... process other node types
-      #   end
-      def list
-        Cproton.pn_data_get_list(@data)
-      end
-
-      # Puts a map value.
-      #
-      # Elements may be filled by entering the map node and putting alternating
-      # key/value pairs.
-      #
-      # ==== Examples
-      #
-      #   data = Qpid::Proton::Data.new
-      #   data.put_map
-      #   data.enter
-      #   data.string = "key"
-      #   data.string = "value"
-      #   data.exit
-      #
-      def put_map
-        check(Cproton.pn_data_put_map(@data))
-      end
-
-      # 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.
-      #
-      # ==== Examples
-      #
-      #   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
-      def map
-        Cproton.pn_data_get_map(@data)
-      end
-
-      def get_map # :nodoc:
-        ::Hash.proton_data_get(self)
-      end
-
-      # 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.
-      #
-      # ==== Options
-      #
-      # * described - specifies whether the array is described
-      # * element_type - the type of the array elements
-      #
-      # ==== Examples
-      #
-      #   # create an array of integer values
-      #   data = Qpid::Proton::Data.new
-      #   data.put_array(false, INT)
-      #   data.enter
-      #   data.int = 1
-      #   data.int = 2
-      #   data.int = 3
-      #   data.exit
-      #
-      #   # create an 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
-      #
-      def put_array(described, element_type)
-        check(Cproton.pn_data_put_array(@data, described, element_type.code))
-      end
-
-      # 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.
-      #
-      # ==== Examples
-      #
-      #   # 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
-      def array
-        count = Cproton.pn_data_get_array(@data)
-        described = Cproton.pn_data_is_array_described(@data)
-        array_type = Cproton.pn_data_get_array_type(@data)
-        return nil if array_type == -1
-        [count, described, Mapping.for_code(array_type) ]
-      end
-
-      def get_array # :nodoc:
-        ::Array.proton_get(self)
-      end
-
-      # 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.
-      #
-      # ==== Examples
-      #
-      #   data = Qpid::Proton::Data.new
-      #   data.put_described
-      #   data.enter
-      #   data.symbol = "value-descriptor"
-      #   data.string = "the value"
-      #   data.exit
-      #
-      def put_described
-        check(Cproton.pn_data_put_described(@data))
-      end
-
-      def get_described # :nodoc:
-        raise TypeError, "not a described type" unless self.described?
-        self.enter
-        self.next
-        type = self.type
-        descriptor = type.get(self)
-        self.next
-        type = self.type
-        value = type.get(self)
-        self.exit
-        Described.new(descriptor, value)
-      end
-
-      # Checks if the current node is a described value.
-      #
-      # The described and value may be accessed by entering the described value.
-      #
-      # ==== Examples
-      #
-      #   if @data.described?
-      #     @data.enter
-      #     puts "The symbol is #{@data.symbol}"
-      #     puts "The value is #{@data.string}"
-      #   end
-      def described?
-        Cproton.pn_data_is_described(@data)
-      end
-
-      # Puts a null value.
-      def null
-        check(Cproton.pn_data_put_null(@data))
-      end
-
-      # Utility method for Qpid::Proton::Mapping
-      def null=(value) # :nodoc:
-        null
-      end
-
-      # Checks if the current node is null.
-      def null?
-        Cproton.pn_data_is_null(@data)
-      end
-
-      # Puts a boolean value.
-      #
-      # ==== Options
-      #
-      # * value - the boolean value
-      def bool=(value)
-        check(Cproton.pn_data_put_bool(@data, value))
-      end
-
-      # If the current node is a boolean, then it returns the value. Otherwise,
-      # it returns false.
-      def bool
-        Cproton.pn_data_get_bool(@data)
-      end
-
-      # Puts an unsigned byte value.
-      #
-      # ==== Options
-      #
-      # * value - the unsigned byte value
-      def ubyte=(value)
-        check(Cproton.pn_data_put_ubyte(@data, value))
-      end
-
-      # If the current node is an unsigned byte, returns its value. Otherwise,
-      # it reutrns 0.
-      def ubyte
-        Cproton.pn_data_get_ubyte(@data)
-      end
-
-      # Puts a byte value.
-      #
-      # ==== Options
-      #
-      # * value - the byte value
-      def byte=(value)
-        check(Cproton.pn_data_put_byte(@data, value))
-      end
-
-      # If the current node is an byte, returns its value. Otherwise,
-      # it returns 0.
-      def byte
-        Cproton.pn_data_get_byte(@data)
-      end
-
-      # Puts an unsigned short value.
-      #
-      # ==== Options
-      #
-      # * value - the unsigned short value
-      def ushort=(value)
-        check(Cproton.pn_data_put_ushort(@data, value))
-      end
-
-      # If the current node is an unsigned short, returns its value. Otherwise,
-      # it returns 0.
-      def ushort
-        Cproton.pn_data_get_ushort(@data)
-      end
-
-      # Puts a short value.
-      #
-      # ==== Options
-      #
-      # * value - the short value
-      def short=(value)
-        check(Cproton.pn_data_put_short(@data, value))
-      end
-
-      # If the current node is a short, returns its value. Otherwise,
-      # returns a 0.
-      def short
-        Cproton.pn_data_get_short(@data)
-      end
-
-      # Puts an unsigned integer value.
-      #
-      # ==== Options
-      #
-      # * value - the unsigned integer value
-      def uint=(value)
-        raise TypeError if value.nil?
-        raise RangeError, "invalid uint: #{value}" if value < 0
-        check(Cproton.pn_data_put_uint(@data, value))
-      end
-
-      # If the current node is an unsigned int, returns its value. Otherwise,
-      # returns 0.
-      def uint
-        Cproton.pn_data_get_uint(@data)
-      end
-
-      # Puts an integer value.
-      #
-      # ==== Options
-      #
-      # * value - the integer value
-      def int=(value)
-        check(Cproton.pn_data_put_int(@data, value))
-      end
-
-      # If the current node is an integer, returns its value. Otherwise,
-      # returns 0.
-      def int
-        Cproton.pn_data_get_int(@data)
-      end
-
-      # Puts a character value.
-      #
-      # ==== Options
-      #
-      # * value - the character value
-      def char=(value)
-        check(Cproton.pn_data_put_char(@data, value))
-      end
-
-      # If the current node is a character, returns its value. Otherwise,
-      # returns 0.
-      def char
-        Cproton.pn_data_get_char(@data)
-      end
-
-      # Puts an unsigned long value.
-      #
-      # ==== Options
-      #
-      # * value - the unsigned long value
-      def ulong=(value)
-        raise TypeError if value.nil?
-        raise RangeError, "invalid ulong: #{value}" if value < 0
-        check(Cproton.pn_data_put_ulong(@data, value))
-      end
-
-      # If the current node is an unsigned long, returns its value. Otherwise,
-      # returns 0.
-      def ulong
-        Cproton.pn_data_get_ulong(@data)
-      end
-
-      # Puts a long value.
-      #
-      # ==== Options
-      #
-      # * value - the long value
-      def long=(value)
-        check(Cproton.pn_data_put_long(@data, value))
-      end
-
-      # If the current node is a long, returns its value. Otherwise, returns 0.
-      def long
-        Cproton.pn_data_get_long(@data)
-      end
-
-      # Puts a timestamp value.
-      #
-      # ==== Options
-      #
-      # * value - the timestamp value
-      def timestamp=(value)
-        value = value.to_i if (!value.nil? && value.is_a?(Time))
-        check(Cproton.pn_data_put_timestamp(@data, value))
-      end
-
-      # If the current node is a timestamp, returns its value. Otherwise,
-      # returns 0.
-      def timestamp
-        Cproton.pn_data_get_timestamp(@data)
-      end
-
-      # Puts a float value.
-      #
-      # ==== Options
-      #
-      # * value - the float value
-      def float=(value)
-        check(Cproton.pn_data_put_float(@data, value))
-      end
-
-      # If the current node is a float, returns its value. Otherwise,
-      # returns 0.
-      def float
-        Cproton.pn_data_get_float(@data)
-      end
-
-      # Puts a double value.
-      #
-      # ==== Options
-      #
-      # * value - the double value
-      def double=(value)
-        check(Cproton.pn_data_put_double(@data, value))
-      end
-
-      # If the current node is a double, returns its value. Otherwise,
-      # returns 0.
-      def double
-        Cproton.pn_data_get_double(@data)
-      end
-
-      # Puts a decimal32 value.
-      #
-      # ==== Options
-      #
-      # * value - the decimal32 value
-      def decimal32=(value)
-        check(Cproton.pn_data_put_decimal32(@data, value))
-      end
-
-      # If the current node is a decimal32, returns its value. Otherwise,
-      # returns 0.
-      def decimal32
-        Cproton.pn_data_get_decimal32(@data)
-      end
-
-      # Puts a decimal64 value.
-      #
-      # ==== Options
-      #
-      # * value - the decimal64 value
-      def decimal64=(value)
-        check(Cproton.pn_data_put_decimal64(@data, value))
-      end
-
-      # If the current node is a decimal64, returns its value. Otherwise,
-      # it returns 0.
-      def decimal64
-        Cproton.pn_data_get_decimal64(@data)
-      end
-
-      # Puts a decimal128 value.
-      #
-      # ==== Options
-      #
-      # * value - the decimal128 value
-      def decimal128=(value)
-        raise TypeError, "invalid decimal128 value: #{value}" if value.nil?
-        value = value.to_s(16).rjust(32, "0")
-        bytes = []
-        value.scan(/(..)/) {|v| bytes << v[0].to_i(16)}
-        check(Cproton.pn_data_put_decimal128(@data, bytes))
-      end
-
-      # If the current node is a decimal128, returns its value. Otherwise,
-      # returns 0.
-      def decimal128
-        value = ""
-        Cproton.pn_data_get_decimal128(@data).each{|val| value += ("%02x" % val)}
-        value.to_i(16)
-      end
-
-      # Puts a +UUID+ value.
-      #
-      # The UUID is expected to be in the format of a string or else a 128-bit
-      # integer value.
-      #
-      # ==== Options
-      #
-      # * value - the +UUID+
-      #
-      # ==== Examples
-      #
-      #   # 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
-      #
-      def uuid=(value)
-        raise ArgumentError, "invalid uuid: #{value}" if value.nil?
-
-        # if the uuid that was submitted was numeric value, then translated
-        # it into a hex string, otherwise assume it was a string represtation
-        # and attempt to decode it
-        if value.is_a? Numeric
-          value = "%032x" % value
-        else
-          raise ArgumentError, "invalid uuid: #{value}" if !valid_uuid?(value)
-
-          value = (value[0, 8]  +
-                   value[9, 4]  +
-                   value[14, 4] +
-                   value[19, 4] +
-                   value[24, 12])
-        end
-        bytes = []
-        value.scan(/(..)/) {|v| bytes << v[0].to_i(16)}
-        check(Cproton.pn_data_put_uuid(@data, bytes))
-      end
-
-      # If the current value is a +UUID+, returns its value. Otherwise,
-      # it returns nil.
-      def uuid
-        value = ""
-        Cproton.pn_data_get_uuid(@data).each{|val| value += ("%02x" % val)}
-        value.insert(8, "-").insert(13, "-").insert(18, "-").insert(23, "-")
-      end
-
-      # Puts a binary value.
-      #
-      # ==== Options
-      #
-      # * value - the binary value
-      def binary=(value)
-        check(Cproton.pn_data_put_binary(@data, value))
-      end
-
-      # If the current node is binary, returns its value. Otherwise, it returns
-      # an empty string ("").
-      def binary
-        Qpid::Proton::BinaryString.new(Cproton.pn_data_get_binary(@data))
-      end
-
-      # Puts a unicode string value.
-      #
-      # *NOTE:* A nil value is stored as an empty string rather than as a nil.
-      #
-      # ==== Options
-      #
-      # * value - the unicode string value
-      def string=(value)
-        check(Cproton.pn_data_put_string(@data, value))
-      end
-
-      # If the current node is a string, returns its value. Otherwise, it
-      # returns an empty string ("").
-      def string
-        Qpid::Proton::UTFString.new(Cproton.pn_data_get_string(@data))
-      end
-
-      # Puts a symbolic value.
-      #
-      # ==== Options
-      #
-      # * value - the symbol name
-      def symbol=(value)
-        check(Cproton.pn_data_put_symbol(@data, value))
-      end
-
-      # If the current node is a symbol, returns its value. Otherwise, it
-      # returns an empty string ("").
-      def symbol
-        Cproton.pn_data_get_symbol(@data)
-      end
-
-      # Get the current value as a single object.
-      def get
-        type.get(self);
-      end
-
-      # Put value as an object of type type_
-      def put(value, type_);
-        type_.put(self, value);
-      end
-
-      private
-
-      def valid_uuid?(value)
-        # ensure that the UUID is in the right format
-        # xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
-        value =~ /[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/
-      end
-
-      def check(err) # :nodoc:
-        if err < 0
-          raise DataError, "[#{err}]: #{Cproton.pn_data_error(@data)}"
-        else
-          return err
-        end
-      end
-    end
-  end
-end