google-cloud-spanner 0.21.0

data/lib/google/cloud/spanner/instance/config.rb

@@ -0,0 +1,99 @@
+# 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 "google/cloud/spanner/instance/config/list"
+
+module Google
+  module Cloud
+    module Spanner
+      class Instance
+        ##
+        # # Instance Config
+        #
+        # Represents a Cloud Spanner instance configuration. Instance
+        # configurations define the geographic placement of nodes and their
+        # replication.
+        #
+        # See {Google::Cloud::Spanner::Project#instance_configs} and
+        # {Google::Cloud::Spanner::Project#instance_config}.
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   instance_configs = spanner.instance_configs
+        #   instance_configs.each do |config|
+        #     puts config.instance_config_id
+        #   end
+        #
+        class Config
+          ##
+          # @private Creates a new Instance::Config instance.
+          def initialize grpc
+            @grpc = grpc
+          end
+
+          # The unique identifier for the project.
+          # @return [String]
+          def project_id
+            Admin::Instance::V1::InstanceAdminClient
+              .match_project_from_instance_config_name @grpc.name
+          end
+
+          ##
+          # A unique identifier for the instance configuration.
+          # @return [String]
+          def instance_config_id
+            Admin::Instance::V1::InstanceAdminClient
+              .match_instance_config_from_instance_config_name @grpc.name
+          end
+
+          ##
+          # The full path for the instance config resource. Values are of the
+          # form `projects/<project_id>/instanceConfigs/<instance_config_id>`.
+          # @return [String]
+          def path
+            @grpc.name
+          end
+
+          ##
+          # The name of this instance configuration as it appears in UIs.
+          # @return [String]
+          def name
+            @grpc.display_name
+          end
+          alias_method :display_name, :name
+
+          ##
+          # @private Creates a new Instance::Config instance from a
+          # Google::Spanner::Admin::Instance::V1::InstanceConfig.
+          def self.from_grpc grpc
+            new grpc
+          end
+
+          protected
+
+          ##
+          # @private Raise an error unless an active connection to the service
+          # is available.
+          def ensure_service!
+            fail "Must have active connection to service" unless service
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/spanner/instance/config/list.rb

@@ -0,0 +1,171 @@
+# 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 "delegate"
+
+module Google
+  module Cloud
+    module Spanner
+      class Instance
+        class Config
+          ##
+          # Instance::Config::List is a special case Array with additional
+          # values.
+          class List < DelegateClass(::Array)
+            ##
+            # If not empty, indicates that there are more records that match
+            # the request and this value should be passed to continue.
+            attr_accessor :token
+
+            ##
+            # @private Create a new Instance::Config::List with an array of
+            # Instance::Config instances.
+            def initialize arr = []
+              super arr
+            end
+
+            ##
+            # Whether there is a next page of instance configs.
+            #
+            # @return [Boolean]
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   configs = spanner.instance_configs
+            #   if configs.next?
+            #     next_configs = configs.next
+            #   end
+            def next?
+              !token.nil?
+            end
+
+            ##
+            # Retrieve the next page of instance configurations.
+            #
+            # @return [Instance::Config::List] The list of instance
+            #   configurations.
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   configs = spanner.instance_configs
+            #   if configs.next?
+            #     next_configs = configs.next
+            #   end
+            def next
+              return nil unless next?
+              ensure_service!
+              options = { token: token, max: @max }
+              grpc = @service.list_instance_configs options
+              self.class.from_grpc grpc, @service, @max
+            end
+
+            ##
+            # Retrieves remaining results by repeatedly invoking {#next} until
+            # {#next?} returns `false`. Calls the given block once for each
+            # result, which is passed as the argument to the block.
+            #
+            # An Enumerator is returned if no block is given.
+            #
+            # This method will make repeated API calls until all remaining
+            # results are retrieved. (Unlike `#each`, for example, which merely
+            # iterates over the results returned by a single API call.) Use with
+            # caution.
+            #
+            # @param [Integer] request_limit The upper limit of API requests to
+            #   make to load all configs. Default is no limit.
+            # @yield [config] The block for accessing each instance config.
+            # @yieldparam [Instance::Config] config The instance config object.
+            #
+            # @return [Enumerator]
+            #
+            # @example Iterating each instance config by passing a block:
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   spanner.instance_configs.all do |config|
+            #     puts config.instance_config_id
+            #   end
+            #
+            # @example Using the enumerator by not passing a block:
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   all_config_ids = spanner.instance_configs.all.map do |config|
+            #     config.instance_config_id
+            #   end
+            #
+            # @example Limit the number of API calls made:
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   spanner.instance_configs.all(request_limit: 10) do |config|
+            #     puts config.instance_config_id
+            #   end
+            #
+            def all request_limit: nil
+              request_limit = request_limit.to_i if request_limit
+              unless block_given?
+                return enum_for(:all, request_limit: request_limit)
+              end
+              results = self
+              loop do
+                results.each { |r| yield r }
+                if request_limit
+                  request_limit -= 1
+                  break if request_limit < 0
+                end
+                break unless results.next?
+                results = results.next
+              end
+            end
+
+            ##
+            # @private New Instance::Config::List from a
+            # Google::Spanner::Admin::Instance::V1::ListInstanceConfigsResponse
+            # object.
+            def self.from_grpc grpc, service, max = nil
+              configs = List.new(Array(grpc.instance_configs).map do |config|
+                Instance::Config.from_grpc config
+              end)
+              token = grpc.next_page_token
+              token = nil if token == ""
+              configs.instance_variable_set :@token,   token
+              configs.instance_variable_set :@service, service
+              configs.instance_variable_set :@max,     max
+              configs
+            end
+
+            protected
+
+            ##
+            # Raise an error unless an active service is available.
+            def ensure_service!
+              fail "Must have active connection" unless @service
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/spanner/instance/job.rb

@@ -0,0 +1,197 @@
+# 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.
+
+
+module Google
+  module Cloud
+    module Spanner
+      class Instance
+        ##
+        # # Job
+        #
+        # A resource representing the long-running, asynchronous processing of
+        # an instance create or update operation. The job can be refreshed to
+        # retrieve the instance object once the operation has been completed.
+        #
+        # See {Project#create_instance} and {Instance#update}.
+        #
+        # @see https://cloud.google.com/spanner/reference/rpc/google.longrunning#google.longrunning.Operation
+        #   Long-running Operation
+        #
+        # @example
+        #   require "google/cloud/spanner"
+        #
+        #   spanner = Google::Cloud::Spanner.new
+        #
+        #   job = spanner.create_instance "my-new-instance",
+        #                                 name: "My New Instance",
+        #                                 config: "regional-us-central1",
+        #                                 nodes: 5,
+        #                                 labels: { production: :env }
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #   instance = job.instance
+        #
+        class Job
+          ##
+          # @private The Google::Gax::Operation gRPC object.
+          attr_accessor :grpc
+
+          ##
+          # @private The gRPC Service object.
+          attr_accessor :service
+
+          ##
+          # @private Creates a new Instance::Job instance.
+          def initialize
+            @grpc = nil
+            @service = nil
+          end
+
+          ##
+          # The instance that is the object of the operation.
+          #
+          # @return [Google::Cloud::Spanner::Instance, nil] The instance, or
+          #   `nil` if the operation is not complete.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_instance "my-new-instance",
+          #                                 name: "My New Instance",
+          #                                 config: "regional-us-central1",
+          #                                 nodes: 5,
+          #                                 labels: { production: :env }
+          #
+          #   job.done? #=> true
+          #   instance = job.instance
+          #
+          def instance
+            return nil unless done?
+            return nil unless @grpc.grpc_op.result == :response
+            Instance.from_grpc @grpc.results, service
+          end
+
+          ##
+          # Checks if the processing of the instance operation is complete.
+          #
+          # @return [boolean] `true` when complete, `false` otherwise.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_instance "my-new-instance",
+          #                                 name: "My New Instance",
+          #                                 config: "regional-us-central1",
+          #                                 nodes: 5,
+          #                                 labels: { production: :env }
+          #
+          #   job.done? #=> false
+          #
+          def done?
+            @grpc.done?
+          end
+
+          ##
+          # Checks if the processing of the instance operation has errored.
+          #
+          # @return [boolean] `true` when errored, `false` otherwise.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_instance "my-new-instance",
+          #                                 name: "My New Instance",
+          #                                 config: "regional-us-central1",
+          #                                 nodes: 5,
+          #                                 labels: { production: :env }
+          #
+          #   job.error? #=> false
+          #
+          def error?
+            @grpc.error?
+          end
+
+          ##
+          # Reloads the job with current data from the long-running,
+          # asynchronous processing of an instance operation.
+          #
+          # @return [Google::Cloud::Spanner::Instance::Job] The same job
+          #   instance.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_instance "my-new-instance",
+          #                                 name: "My New Instance",
+          #                                 config: "regional-us-central1",
+          #                                 nodes: 5,
+          #                                 labels: { production: :env }
+          #
+          #   job.done? #=> false
+          #   job.reload! # API call
+          #   job.done? #=> true
+          #
+          def reload!
+            @grpc.reload!
+            self
+          end
+          alias_method :refresh!, :reload!
+
+          ##
+          # Reloads the job until the operation is complete. The delay between
+          # reloads will incrementally increase.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   job = spanner.create_instance "my-new-instance",
+          #                                 name: "My New Instance",
+          #                                 config: "regional-us-central1",
+          #                                 nodes: 5,
+          #                                 labels: { production: :env }
+          #
+          #   job.done? #=> false
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          def wait_until_done!
+            @grpc.wait_until_done!
+          end
+
+          ##
+          # @private New Instance::Job from a Google::Gax::Operation object.
+          def self.from_grpc grpc, service
+            new.tap do |job|
+              job.instance_variable_set :@grpc, grpc
+              job.instance_variable_set :@service, service
+            end
+          end
+        end
+      end
+    end
+  end
+end