gcloud 0.8.2 → 0.9.0

data/lib/gcloud/datastore/errors.rb

@@ -31,27 +31,6 @@ module Gcloud
     class KeyfileError < Gcloud::Datastore::Error
     end
 
-    ##
-    # # ApiError
-    #
-    # Raised when an API call is not successful.
-    class ApiError < Gcloud::Datastore::Error
-      ##
-      # The API method of the failed HTTP request.
-      attr_reader :method
-
-      ##
-      # The response object of the failed HTTP request.
-      attr_reader :response
-
-      # @private
-      def initialize method, response = nil
-        super("API call to #{method} was not successful")
-        @method = method
-        @response = response
-      end
-    end
-
     ##
     # # PropertyError
     #

data/lib/gcloud/datastore/gql_query.rb

@@ -0,0 +1,211 @@
+# Copyright 2016 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/entity"
+require "gcloud/datastore/key"
+
+module Gcloud
+  module Datastore
+    ##
+    # # GqlQuery
+    #
+    # Represents a GQL query.
+    #
+    # GQL is a SQL-like language for retrieving entities or keys from Datastore.
+    #
+    # @see https://cloud.google.com/datastore/docs/apis/gql/gql_reference GQL
+    #   Reference
+    #
+    # @example
+    #   gql_query = Gcloud::Datastore::GqlQuery.new
+    #   gql_query.query_string = "SELECT * FROM Task ORDER BY created ASC"
+    #   tasks = datastore.run gql_query
+    #
+    class GqlQuery
+      ##
+      # Returns a new GqlQuery instance.
+      #
+      # @example
+      #   gql_query = Gcloud::Datastore::GqlQuery.new
+      #
+      def initialize
+        @grpc = Google::Datastore::V1beta3::GqlQuery.new
+      end
+
+      ##
+      # The GQL query string for the query. The string may contain named
+      # or positional argument binding sites that start with `@`. Corresponding
+      # binding values should be set with {#named_bindings=} or
+      # {#positional_bindings=}.
+      #
+      # @return [String] a GQL statement
+      #
+      def query_string
+        gql = @grpc.query_string.dup
+        gql.freeze
+        gql
+      end
+
+      ##
+      # Sets the GQL query string for the query. The string may contain named
+      # or positional argument binding sites that start with `@`. Corresponding
+      # binding values should be set with {#named_bindings=} or
+      # {#positional_bindings=}.
+      #
+      # See the [GQL
+      # Reference](https://cloud.google.com/datastore/docs/apis/gql/gql_reference).
+      #
+      # @param [String] new_query_string a valid GQL statement
+      #
+      # @example
+      #   gql_query = Gcloud::Datastore::GqlQuery.new
+      #   gql_query.query_string = "SELECT * FROM Task " \
+      #                            "WHERE done = @done AND priority = @priority"
+      #   gql_query.named_bindings = {done: false, priority: 4}
+      #
+      def query_string= new_query_string
+        @grpc.query_string = new_query_string.to_s
+      end
+
+      ##
+      # Whether the query may contain literal values. When false, the query
+      # string must not contain any literals and instead must bind all values
+      # using {#named_bindings=} or {#positional_bindings=}.
+      #
+      # @return [Boolean] `true` if the query may contain literal values
+      #
+      def allow_literals
+        @grpc.allow_literals
+      end
+
+      ##
+      # Sets whether the query may contain literal values. When false, the query
+      # string must not contain any literals and instead must bind all values
+      # using {#named_bindings=} or {#positional_bindings=}.
+      #
+      # @param [Boolean] new_allow_literals `true` if the query may contain
+      #   literal values
+      #
+      # @example
+      #   gql_query = Gcloud::Datastore::GqlQuery.new
+      #   gql_query.query_string = "SELECT * FROM Task " \
+      #                            "WHERE completed = false AND priority = 4"
+      #   gql_query.allow_literals = true
+      #
+      def allow_literals= new_allow_literals
+        @grpc.allow_literals = new_allow_literals
+      end
+
+      ##
+      # The named binding values for a query that contains named argument
+      # binding sites that start with `@`.
+      #
+      # @return [Hash] a frozen hash that maps the binding site names in the
+      #   query string to valid GQL arguments
+      #
+      def named_bindings
+        bindings = Hash[@grpc.named_bindings.map do |name, gql_query_param|
+          if gql_query_param.cursor
+            [name, Cursor.from_grpc(gql_query_param.cursor)]
+          else
+            [name, GRPCUtils.from_value(gql_query_param.value)]
+          end
+        end]
+        bindings.freeze
+        bindings
+      end
+
+      ##
+      # Sets named binding values for a query that contains named argument
+      # binding sites that start with `@`.
+      #
+      # @param [Hash] new_named_bindings a hash that maps the binding site names
+      #   in the query string to valid GQL arguments
+      #
+      # @example
+      #   gql_query = Gcloud::Datastore::GqlQuery.new
+      #   gql_query.query_string = "SELECT * FROM Task " \
+      #                            "WHERE done = @done AND priority = @priority"
+      #   gql_query.named_bindings = {done: false, priority: 4}
+      #
+      def named_bindings= new_named_bindings
+        @grpc.named_bindings.clear
+        new_named_bindings.map do |name, value|
+          if value.is_a? Gcloud::Datastore::Cursor
+            @grpc.named_bindings[name.to_s] = \
+              Google::Datastore::V1beta3::GqlQueryParameter.new(
+                cursor: value.to_grpc)
+          else
+            @grpc.named_bindings[name.to_s] = \
+              Google::Datastore::V1beta3::GqlQueryParameter.new(
+                value: GRPCUtils.to_value(value))
+          end
+        end
+      end
+
+      ##
+      # The binding values for a query that contains numbered argument binding
+      # sites that start with `@`.
+      #
+      # @return [Array] a frozen array containing the query arguments in the
+      #   order of the numbered binding sites in the query string
+      #
+      def positional_bindings
+        bindings = @grpc.positional_bindings.map do |gql_query_param|
+          if gql_query_param.cursor
+            Cursor.from_grpc gql_query_param.cursor
+          else
+            GRPCUtils.from_value gql_query_param.value
+          end
+        end
+        bindings.freeze
+        bindings
+      end
+
+      ##
+      # Sets the binding values for a query that contains numbered argument
+      # binding sites that start with `@`.
+      #
+      # @param [Array] new_positional_bindings query arguments in the order
+      #   of the numbered binding sites in the query string
+      #
+      # @example
+      #   gql_query = Gcloud::Datastore::GqlQuery.new
+      #   gql_query.query_string = "SELECT * FROM Task" \
+      #                            "WHERE completed = @1 AND priority = @2"
+      #   gql_query.positional_bindings = [false, 4]
+      #
+      def positional_bindings= new_positional_bindings
+        @grpc.positional_bindings.clear
+        new_positional_bindings.map do |value|
+          if value.is_a? Gcloud::Datastore::Cursor
+            @grpc.positional_bindings << \
+              Google::Datastore::V1beta3::GqlQueryParameter.new(
+                cursor: value.to_grpc)
+          else
+            @grpc.positional_bindings << \
+              Google::Datastore::V1beta3::GqlQueryParameter.new(
+                value: GRPCUtils.to_value(value))
+          end
+        end
+      end
+
+      # @private
+      def to_grpc
+        @grpc
+      end
+    end
+  end
+end

data/lib/gcloud/datastore/grpc_utils.rb

@@ -0,0 +1,131 @@
+# Copyright 2016 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/grpc_utils"
+require "gcloud/datastore/errors"
+require "stringio"
+
+module Gcloud
+  ##
+  # @private Conversion to/from Datastore GRPC objects.
+  # This file adds Datastore methods to GRPCUtils.
+  module GRPCUtils
+    # rubocop:disable all
+
+    PROP_FILTER_OPS = { "<"            => :LESS_THAN,
+                        "lt"           => :LESS_THAN,
+                        "<="           => :LESS_THAN_OR_EQUAL,
+                        "lte"          => :LESS_THAN_OR_EQUAL,
+                        ">"            => :GREATER_THAN,
+                        "gt"           => :GREATER_THAN,
+                        ">="           => :GREATER_THAN_OR_EQUAL,
+                        "gte"          => :GREATER_THAN_OR_EQUAL,
+                        "="            => :EQUAL,
+                        "eq"           => :EQUAL,
+                        "eql"          => :EQUAL,
+                        "~"            => :HAS_ANCESTOR,
+                        "~>"           => :HAS_ANCESTOR,
+                        "ancestor"     => :HAS_ANCESTOR,
+                        "has_ancestor" => :HAS_ANCESTOR,
+                        "has ancestor" => :HAS_ANCESTOR }
+
+    ##
+    # Get a property filter operator from op
+    def self.to_prop_filter_op op
+      PROP_FILTER_OPS[op.to_s.downcase] || :EQUAL
+    end
+
+    ##
+    # Gets an object from a Google::Datastore::V1beta3::Value.
+    def self.from_value grpc_value
+      if grpc_value.value_type == :null_value
+        return nil
+      elsif grpc_value.value_type == :key_value
+        return Gcloud::Datastore::Key.from_grpc(grpc_value.key_value)
+      elsif grpc_value.value_type == :entity_value
+        return Gcloud::Datastore::Entity.from_grpc(grpc_value.entity_value)
+      elsif grpc_value.value_type == :boolean_value
+        return grpc_value.boolean_value
+      elsif grpc_value.value_type == :double_value
+        return grpc_value.double_value
+      elsif grpc_value.value_type == :integer_value
+        return grpc_value.integer_value
+      elsif grpc_value.value_type == :string_value
+        return grpc_value.string_value
+      elsif grpc_value.value_type == :array_value
+        return Array(grpc_value.array_value.values).map { |v| from_value v }
+      elsif grpc_value.value_type == :timestamp_value
+        return Time.at grpc_value.timestamp_value.seconds,
+                       grpc_value.timestamp_value.nanos/1000.0
+      elsif grpc_value.value_type == :geo_point_value
+        return grpc_value.geo_point_value.to_hash
+      elsif grpc_value.value_type == :blob_value
+        return StringIO.new(grpc_value.blob_value.force_encoding("ASCII-8BIT"))
+      else
+        nil
+      end
+    end
+
+    ##
+    # Stores an object into a Google::Datastore::V1beta3::Value.
+    def self.to_value value
+      v = Google::Datastore::V1beta3::Value.new
+      if NilClass === value
+        v.null_value = :NULL_VALUE
+      elsif TrueClass === value
+        v.boolean_value = true
+      elsif FalseClass === value
+        v.boolean_value = false
+      elsif Integer === value
+        v.integer_value = value
+      elsif Float === value
+        v.double_value = value
+      elsif defined?(BigDecimal) && BigDecimal === value
+        v.double_value = value
+      elsif Gcloud::Datastore::Key === value
+        v.key_value = value.to_grpc
+      elsif Gcloud::Datastore::Entity === value
+        v.entity_value = value.to_grpc
+      elsif String === value
+        v.string_value = value
+      elsif Array === value
+        v.array_value = Google::Datastore::V1beta3::ArrayValue.new(
+          values: value.map { |v| to_value v }
+        )
+      elsif value.respond_to? :to_time
+        v.timestamp_value = Google::Protobuf::Timestamp.new(
+          seconds: value.to_time.to_i, nanos: value.to_time.nsec)
+      elsif value.respond_to?(:to_hash) && value.keys.sort == [:latitude, :longitude]
+        v.geo_point_value = Google::Type::LatLng.new(value)
+      elsif value.respond_to?(:read) && value.respond_to?(:rewind)
+        value.rewind
+        v.blob_value = value.read.force_encoding("ASCII-8BIT")
+      else
+        fail Gcloud::Datastore::PropertyError,
+             "A property of type #{value.class} is not supported."
+      end
+      v
+    end
+
+    def self.encode_bytes bytes
+      Array(bytes.to_s).pack("m").chomp.encode("ASCII-8BIT")
+    end
+
+    def self.decode_bytes bytes
+      bytes.to_s.unpack("m").first.force_encoding Encoding::ASCII_8BIT
+    end
+    # rubocop:enable all
+  end
+end

data/lib/gcloud/datastore/key.rb

@@ -13,8 +13,6 @@
 # limitations under the License.
 
 
-require "gcloud/datastore/proto"
-
 module Gcloud
   module Datastore
     ##
@@ -26,7 +24,7 @@ module Gcloud
     # ID, assigned automatically by Datastore.
     #
     # @example
-    #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
+    #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
     #
     class Key
       ##
@@ -35,14 +33,14 @@ module Gcloud
       # @return [String]
       #
       # @example
-      #   key = Gcloud::Datastore::Key.new "User"
-      #   key.kind #=> "User"
+      #   key = Gcloud::Datastore::Key.new "TaskList"
+      #   key.kind #=> "TaskList"
       #   key.kind = "Task"
       #
       attr_accessor :kind
 
       ##
-      # The dataset_id of the Key.
+      # The project of the Key.
       #
       # @return [String]
       #
@@ -52,11 +50,13 @@ module Gcloud
       #   gcloud = Gcloud.new "my-todo-project",
       #                       "/path/to/keyfile.json"
       #
-      #   dataset = gcloud.datastore
-      #   entity = dataset.find "User", "heidi@example.com"
-      #   entity.key.dataset_id #=> "my-todo-project"
+      #   datastore = gcloud.datastore
+      #   task = datastore.find "Task", "sampleTask"
+      #   task.key.project #=> "my-todo-project"
       #
-      attr_accessor :dataset_id
+      attr_accessor :project
+      alias_method :dataset_id,  :project
+      alias_method :dataset_id=, :project=
 
       ##
       # The namespace of the Key.
@@ -69,9 +69,9 @@ module Gcloud
       #   gcloud = Gcloud.new "my-todo-project",
       #                       "/path/to/keyfile.json"
       #
-      #   dataset = gcloud.datastore
-      #   entity = dataset.find "User", "heidi@example.com"
-      #   entity.key.namespace #=> "ns~todo-project"
+      #   datastore = gcloud.datastore
+      #   task = datastore.find "Task", "sampleTask"
+      #   task.key.namespace #=> "ns~todo-project"
       #
       attr_accessor :namespace
 
@@ -85,7 +85,7 @@ module Gcloud
       # @return [Gcloud::Datastore::Dataset::Key]
       #
       # @example
-      #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
       #
       def initialize kind = nil, id_or_name = nil
         @kind = kind
@@ -103,12 +103,12 @@ module Gcloud
       # @return [Integer, nil]
       #
       # @example
-      #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
-      #   key.id #=> nil
-      #   key.name #=> "heidi@example.com"
-      #   key.id = 654321
-      #   key.id #=> 654321
-      #   key.name #=> nil
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
+      #   task_key.id #=> nil
+      #   task_key.name #=> "sampleTask"
+      #   task_key.id = 654321
+      #   task_key.id #=> 654321
+      #   task_key.name #=> nil
       #
       def id= new_id
         @name = nil if new_id
@@ -121,8 +121,8 @@ module Gcloud
       # @return [Integer, nil]
       #
       # @example
-      #   key = Gcloud::Datastore::Key.new "User", 123456
-      #   key.id #=> 123456
+      #   task_key = Gcloud::Datastore::Key.new "Task", 123456
+      #   task_key.id #=> 123456
       #
       attr_reader :id
 
@@ -133,12 +133,12 @@ module Gcloud
       # @return [String, nil]
       #
       # @example
-      #   key = Gcloud::Datastore::Key.new "User", 123456
-      #   key.id #=> 123456
-      #   key.name #=> nil
-      #   key.name = "heidi@example.com"
-      #   key.id #=> nil
-      #   key.name #=> "heidi@example.com"
+      #   task_key = Gcloud::Datastore::Key.new "Task", 123456
+      #   task_key.id #=> 123456
+      #   task_key.name #=> nil
+      #   task_key.name = "sampleTask"
+      #   task_key.id #=> nil
+      #   task_key.name #=> "sampleTask"
       #
       def name= new_name
         @id = nil if new_name
@@ -151,19 +151,26 @@ module Gcloud
       # @return [String, nil]
       #
       # @example
-      #   key = Gcloud::Datastore::Key.new "User", "heidi@example.com"
-      #   key.name #=> "heidi@example.com"
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
+      #   task_key.name #=> "sampleTask"
       #
       attr_reader :name
 
       ##
-      # @private Set the parent of the Key.
+      # Set the parent of the Key.
       #
       # @return [Key, nil]
       #
       # @example
-      #   key = Gcloud::Datastore::Key.new "List", "todos"
-      #   key.parent = Gcloud::Datastore::Key.new "User", "heidi@example.com"
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
+      #   task_key.parent = Gcloud::Datastore::Key.new "TaskList", "default"
+      #
+      # @example With multiple levels:
+      #   user_key = Gcloud::Datastore::Key.new "User", "alice"
+      #   task_list_key = Gcloud::Datastore::Key.new "TaskList", "default"
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
+      #   task_list_key.parent = user_key
+      #   task_key.parent = task_list_key
       #
       def parent= new_parent
         # store key if given an entity
@@ -180,13 +187,13 @@ module Gcloud
       #   require "gcloud"
       #
       #   gcloud = Gcloud.new
-      #   dataset = gcloud.datastore
+      #   datastore = gcloud.datastore
       #
-      #   user = dataset.find "User", "heidi@example.com"
-      #   query = dataset.query("List").
-      #     ancestor(user.key)
-      #   lists = dataset.run query
-      #   lists.first.key.parent #=> Key("User", "heidi@example.com")
+      #   task_list = datastore.find "TaskList", "default"
+      #   query = datastore.query("Task").
+      #     ancestor(task_list)
+      #   lists = datastore.run query
+      #   lists.first.key.parent #=> Key("TaskList", "default")
       #
       attr_reader :parent
 
@@ -198,9 +205,9 @@ module Gcloud
       # @return [Array<Array<(String, String)>>]
       #
       # @example
-      #   key = Gcloud::Datastore::Key.new "List", "todos"
-      #   key.parent = Gcloud::Datastore::Key.new "User", "heidi@example.com"
-      #   key.path #=> [["User", "heidi@example.com"], ["List", "todos"]]
+      #   task_key = Gcloud::Datastore::Key.new "Task", "sampleTask"
+      #   task_key.parent = Gcloud::Datastore::Key.new "TaskList", "default"
+      #   task_key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
       #
       def path
         new_path = parent ? parent.path : []
@@ -226,41 +233,43 @@ module Gcloud
       end
 
       ##
-      # @private Convert the Key to a protocol buffer object.
-      def to_proto
-        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
+      # @private Convert the Key to a Google::Datastore::V1beta3::Key object.
+      def to_grpc
+        grpc_path = path.map do |pe_kind, pe_id_or_name|
+          path_args = { kind: pe_kind }
+          if pe_id_or_name.is_a? Integer
+            path_args[:id] = pe_id_or_name
+          elsif pe_id_or_name.is_a? String
+            path_args[:name] = pe_id_or_name unless pe_id_or_name.empty?
           end
-          k.partition_id = Proto.new_partition_id dataset_id, namespace
+          Google::Datastore::V1beta3::Key::PathElement.new(path_args)
+        end
+        grpc = Google::Datastore::V1beta3::Key.new(path: grpc_path)
+        if project || namespace
+          grpc.partition_id = Google::Datastore::V1beta3::PartitionId.new(
+            project_id: project.to_s, namespace_id: namespace.to_s)
         end
+        grpc
       end
 
-      # rubocop:disable all
-
       ##
-      # @private Create a new Key from a protocol buffer object.
-      def self.from_proto proto
-        # Disable rules because the complexity here is neccessary.
-        key_proto = proto.dup
+      # @private Create a new Key from a Google::Datastore::V1beta3::Key object.
+      def self.from_grpc grpc
+        key_grpc = grpc.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
+        path_grpc = key_grpc.path.pop
+        if path_grpc
+          key = Key.new path_grpc.kind, (path_grpc.id || path_grpc.name)
         end
-        if Array(key_proto.path_element).count > 0
-          key.parent = Key.from_proto(key_proto)
+        if key_grpc.partition_id
+          key.project = key_grpc.partition_id.project_id
+          key.namespace = key_grpc.partition_id.namespace_id
         end
+        key.parent = Key.from_grpc(key_grpc) if key_grpc.path.count > 0
         # Freeze the key to make it immutable.
         key.freeze
         key
       end
-      # rubocop:enable all
     end
   end
 end