gcloud 0.0.7 → 0.1.0

data/lib/gcloud/datastore/key.rb

@@ -0,0 +1,151 @@
+# Copyright 2014 Google Inc. All rights reserved.
+#
+# Licensed 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.
+
+require "gcloud/datastore/proto"
+
+module Gcloud
+  module Datastore
+    ##
+    # Datastore Key
+    #
+    # Every Datastore record has an identifying key, which includes the record's
+    # entity kind and a unique identifier. The identifier may be either a key
+    # name string, assigned explicitly by the application, or an integer numeric
+    # ID, assigned automatically by Datastore.
+    #
+    #   key = Gcloud::Datastore::Key.new "User", "username"
+    class Key
+      ##
+      # The kind of the Key.
+      attr_accessor :kind
+
+      ##
+      # The dataset_id of the Key.
+      attr_accessor :dataset_id
+
+      ##
+      # The namespace of the Key.
+      attr_accessor :namespace
+
+      def initialize kind = nil, id_or_name = nil
+        @kind = kind
+        if id_or_name.is_a? Integer
+          @id = id_or_name
+        else
+          @name = id_or_name
+        end
+      end
+
+      ##
+      # Set the id of the Key.
+      # If a name is already present it will be removed.
+      def id= new_id #:nodoc:
+        @name = nil if new_id
+        @id = new_id
+      end
+
+      ##
+      # The id of the Key.
+      attr_reader :id
+
+      ##
+      # Set the name of the Key.
+      # If an id is already present it will be removed.
+      def name= new_name #:nodoc:
+        @id = nil if new_name
+        @name = new_name
+      end
+
+      ##
+      # The name of the Key.
+      attr_reader :name
+
+      ##
+      # Set the parent of the Key.
+      def parent= new_parent #:nodoc:
+        # store key if given an entity
+        new_parent = new_parent.key if new_parent.respond_to? :key
+        @parent = new_parent
+      end
+
+      ##
+      # The parent of the Key.
+      attr_reader :parent
+
+      ##
+      # Represent the Key's path (including parent) as an array of arrays.
+      # Each inner array contains two values, the kind and the id or name.
+      # If neither an id or name exist then nil will be returned.
+      #
+      #   puts key.path #=> [["Person", "username"], ["Task", 123456]]
+      def path
+        new_path = parent ? parent.path : []
+        new_path << [kind, (id || name)]
+      end
+
+      ##
+      # Determine if the key is complete.
+      # A complete key has either an id or a name.
+      def complete?
+        !incomplete?
+      end
+
+      ##
+      # Determine if the key is incomplete.
+      # An incomplete key has neither an id nor a name.
+      def incomplete?
+        kind.nil? || (id.nil? && (name.nil? || name.empty?))
+      end
+
+      ##
+      # Convert the Key to a protocol buffer object.
+      # This is not part of the public API.
+      def to_proto #:nodoc:
+        Proto::Key.new.tap do |k|
+          k.path_element = path.map do |pe_kind, pe_id_or_name|
+            Proto.new_path_element pe_kind, pe_id_or_name
+          end
+          k.partition_id = Proto.new_partition_id dataset_id, namespace
+        end
+      end
+
+      # rubocop:disable all
+
+      ##
+      # Create a new Key from a protocol buffer object.
+      # This is not part of the public API.
+      def self.from_proto proto #:nodoc:
+        # Disable rules because the complexity here is neccessary.
+        key_proto = proto.dup
+        key = Key.new
+        proto_path_element = Array(key_proto.path_element).pop
+        if proto_path_element
+          key = Key.new proto_path_element.kind,
+                        proto_path_element.id || proto_path_element.name
+        end
+        if key_proto.partition_id
+          key.dataset_id = key_proto.partition_id.dataset_id
+          key.namespace  = key_proto.partition_id.namespace
+        end
+        if Array(key_proto.path_element).count > 0
+          key.parent = Key.from_proto(key_proto)
+        end
+        # Freeze the key to make it immutable.
+        key.freeze
+        key
+      end
+      # rubocop:enable all
+    end
+  end
+end

data/lib/gcloud/datastore/properties.rb

@@ -0,0 +1,102 @@
+# Copyright 2015 Google Inc. All rights reserved.
+#
+# Licensed 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 Gcloud
+  module Datastore
+    ##
+    # Properties
+    class Properties
+      def initialize properties = {}
+        @hash = {}
+        properties.each do |key, value|
+          key   = ensure_key_type key
+          value = ensure_value_type value
+          @hash[key] = value
+        end
+      end
+
+      def [] key
+        key = ensure_key_type key
+        @hash[key]
+      end
+      alias_method :read, :[]
+
+      def []= key, value
+        key   = ensure_key_type key
+        value = ensure_value_type value
+        @hash[key] = value
+      end
+      alias_method :write, :[]=
+
+      def exist? key
+        key = ensure_key_type key
+        @hash.key? key
+      end
+
+      def fetch key, &_block
+        key = ensure_key_type key
+        @hash[key] = yield unless exist? key
+        @hash[key]
+      end
+
+      def each &block
+        @hash.each(&block)
+      end
+
+      def delete key, &block
+        key = ensure_key_type key
+        @hash.delete key, &block
+      end
+
+      def to_h
+        @hash.dup
+      end
+      alias_method :to_hash, :to_h
+
+      protected
+
+      ##
+      # Ensures the key is the proper type,
+      # otherwise a PropertyError is raised.
+      def ensure_key_type key
+        return key.to_str if key.respond_to? :to_str
+        fail "Property key #{key} must be a String."
+      end
+
+      # rubocop:disable all
+      # Disabled rubocop because this needs to match Proto.to_proto_value
+
+      ##
+      # Ensures the value is a type that can be persisted,
+      # otherwise a PropertyError is raised.
+      def ensure_value_type value
+        if Time                      === value ||
+           Gcloud::Datastore::Key    === value ||
+           Gcloud::Datastore::Entity === value ||
+           TrueClass                 === value ||
+           FalseClass                === value ||
+           Float                     === value ||
+           Integer                   === value ||
+           String                    === value ||
+           Array                     === value
+          return value
+        elsif defined?(BigDecimal) && BigDecimal === value
+          return value
+        end
+        fail PropertyError, "A property of type #{value.class} is not supported."
+      end
+      # rubocop:enable all
+    end
+  end
+end

data/lib/gcloud/datastore/proto.rb

@@ -0,0 +1,253 @@
+# Copyright 2014 Google Inc. All rights reserved.
+#
+# Licensed 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.
+
+require "gcloud/proto/datastore_v1.pb"
+
+module Gcloud
+  module Datastore
+    # rubocop:disable all
+
+    ##
+    # Proto is the namespace that contains all Protocol Buffer objects.
+    #
+    # The methods in this module are for convenience in using the
+    # Protocol Buffer objects and as such can change in the future.
+    # Neither the convenience methods nor the Protocol Buffer objects
+    # are not part of the gcloud public API. These methods, and even
+    # this module's existance, may change in the future.
+    #
+    # You have been warned.
+    module Proto #:nodoc:
+      def self.from_proto_value proto_value
+        if !proto_value.timestamp_microseconds_value.nil?
+          microseconds = proto_value.timestamp_microseconds_value
+          self.time_from_microseconds microseconds
+        elsif !proto_value.key_value.nil?
+          Gcloud::Datastore::Key.from_proto(proto_value.key_value)
+        elsif !proto_value.entity_value.nil?
+          Gcloud::Datastore::Entity.from_proto(proto_value.entity_value)
+        elsif !proto_value.boolean_value.nil?
+          proto_value.boolean_value
+        elsif !proto_value.double_value.nil?
+          proto_value.double_value
+        elsif !proto_value.integer_value.nil?
+          proto_value.integer_value
+        elsif !proto_value.string_value.nil?
+          return proto_value.string_value
+        elsif !proto_value.list_value.nil?
+          return Array(proto_value.list_value).map do |item|
+            from_proto_value item
+          end
+        else
+          nil
+        end
+      end
+
+      def self.to_proto_value value
+        v = Gcloud::Datastore::Proto::Value.new
+        if Time === value
+          v.timestamp_microseconds_value = self.microseconds_from_time value
+        elsif Gcloud::Datastore::Key === value
+          v.key_value = value.to_proto
+        elsif Gcloud::Datastore::Entity === value
+          v.entity_value = value.to_proto
+        elsif TrueClass === value
+          v.boolean_value = true
+        elsif FalseClass === value
+          v.boolean_value = false
+        elsif Float === value
+          v.double_value = value
+        elsif defined?(BigDecimal) && BigDecimal === value
+          v.double_value = value
+        elsif Integer === value
+          v.integer_value = value
+        elsif String === value
+          v.string_value = value
+        elsif Array === value
+          v.list_value = value.map { |item| to_proto_value item }
+        else
+          fail PropertyError, "A property of type #{value.class} is not supported."
+        end
+        v
+      end
+
+      def self.from_proto_properties proto_properties
+        hash_properties = {}
+        Array(proto_properties).each do |p|
+          hash_properties[p.name] = Proto.from_proto_value p.value
+        end
+        hash_properties
+      end
+
+      def self.to_proto_properties hash_properties
+        hash_properties.map do |name, value|
+          Proto::Property.new.tap do |p|
+            p.name = name.to_s
+            p.value = Proto.to_proto_value value
+          end
+        end
+      end
+
+      def self.microseconds_from_time time
+        (time.utc.to_f * 1000000).to_i
+      end
+
+      def self.time_from_microseconds microseconds
+        Time.at(microseconds / 1000000, microseconds % 1000000).utc
+      end
+
+      #:nodoc:
+      PROP_FILTER_OPS = {
+        "<"   => PropertyFilter::Operator::LESS_THAN,
+        "lt"  => PropertyFilter::Operator::LESS_THAN,
+        "<="  => PropertyFilter::Operator::LESS_THAN_OR_EQUAL,
+        "lte" => PropertyFilter::Operator::LESS_THAN_OR_EQUAL,
+        ">"   => PropertyFilter::Operator::GREATER_THAN,
+        "gt"  => PropertyFilter::Operator::GREATER_THAN,
+        ">="  => PropertyFilter::Operator::GREATER_THAN_OR_EQUAL,
+        "gte" => PropertyFilter::Operator::GREATER_THAN_OR_EQUAL,
+        "="   => PropertyFilter::Operator::EQUAL,
+        "eq"  => PropertyFilter::Operator::EQUAL,
+        "eql" => PropertyFilter::Operator::EQUAL,
+        "~"            => PropertyFilter::Operator::HAS_ANCESTOR,
+        "~>"           => PropertyFilter::Operator::HAS_ANCESTOR,
+        "ancestor"     => PropertyFilter::Operator::HAS_ANCESTOR,
+        "has_ancestor" => PropertyFilter::Operator::HAS_ANCESTOR,
+        "has ancestor" => PropertyFilter::Operator::HAS_ANCESTOR }
+
+      def self.to_prop_filter_op str
+        PROP_FILTER_OPS[str.to_s.downcase] ||
+        PropertyFilter::Operator::EQUAL
+      end
+
+      def self.to_prop_order_direction direction
+        if direction.to_s.downcase.start_with? "d"
+          PropertyOrder::Direction::DESCENDING
+        else
+          PropertyOrder::Direction::ASCENDING
+        end
+      end
+
+      def self.encode_cursor cursor
+        Array(cursor.to_s).pack("m").chomp
+      end
+
+      def self.decode_cursor cursor
+        dc = cursor.to_s.unpack("m").first.force_encoding Encoding::ASCII_8BIT
+        dc = nil if dc.empty?
+        dc
+      end
+
+      def self.to_more_results_string more_results
+        if QueryResultBatch::MoreResultsType::NOT_FINISHED == more_results
+          "NOT_FINISHED"
+        elsif QueryResultBatch::MoreResultsType::MORE_RESULTS_AFTER_LIMIT == more_results
+          "MORE_RESULTS_AFTER_LIMIT"
+        elsif QueryResultBatch::MoreResultsType::NO_MORE_RESULTS == more_results
+          "NO_MORE_RESULTS"
+        else
+          nil
+        end
+      end
+
+      ##
+      # Convenience methods to create protocol buffer objects
+
+      def self.new_filter
+        Filter.new
+      end
+
+      def self.new_composite_filter
+        CompositeFilter.new.tap do |cf|
+          cf.operator = Proto::CompositeFilter::Operator::AND
+          cf.filter = []
+        end
+      end
+
+      def self.new_mutation
+        Mutation.new.tap do |m|
+          m.upsert = []
+          m.update = []
+          m.insert = []
+          m.insert_auto_id = []
+          m.delete = []
+        end
+      end
+
+      def self.new_property_filter name, operator, value
+        PropertyFilter.new.tap do |pf|
+          pf.property = new_property_reference name
+          pf.operator = Proto.to_prop_filter_op operator
+          pf.value = Proto.to_proto_value value
+        end
+      end
+
+      def self.new_property_expressions *names
+        names.map do |name|
+          new_property_expression name
+        end
+      end
+
+      def self.new_property_expression name
+        PropertyExpression.new.tap do |pe|
+          pe.property = new_property_reference name
+        end
+      end
+
+      def self.new_property_references *names
+        names.map do |name|
+          new_property_reference name
+        end
+      end
+
+      def self.new_property_reference name
+        PropertyReference.new.tap do |pr|
+          pr.name = name
+        end
+      end
+
+      def self.new_path_element new_kind, new_id_or_name
+        Key::PathElement.new.tap do |pe|
+          pe.kind = new_kind
+          if new_id_or_name.is_a? Integer
+            pe.id = new_id_or_name
+          else
+            pe.name = new_id_or_name
+          end
+        end
+      end
+
+      def self.new_partition_id new_dataset_id, new_namespace
+        PartitionId.new.tap do |pi|
+          pi.dataset_id = new_dataset_id
+          pi.namespace  = new_namespace
+        end
+      end
+
+      def self.new_run_query_request query_proto
+        RunQueryRequest.new.tap do |rq|
+          rq.query = query_proto
+        end
+      end
+
+      class Key
+        def dup
+          proto_request_body = ""
+          self.encode proto_request_body
+          Key.decode proto_request_body
+        end
+      end
+    end
+  end
+end