google-cloud-spanner 1.15.0 → 2.1.0

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

@@ -0,0 +1,274 @@
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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/status"
+require "google/cloud/spanner/backup/job/list"
+
+module Google
+  module Cloud
+    module Spanner
+      class Backup
+        ##
+        # # Job
+        #
+        # A resource representing the long-running, asynchronous processing of
+        # backup creation. The job can be refreshed to retrieve the backup
+        # object once the operation has been completed.
+        #
+        # See {Google::Cloud::Spanner::Database#create_backup}
+        #
+        # @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
+        #
+        #   database = spanner.database "my-instance", "my-database"
+        #   expire_time = Time.now + 36000
+        #   job = database.create_backup "my-backup", expire_time: expire_time
+        #
+        #   job.done? #=> false
+        #   job.reload! # API call
+        #   job.done? #=> true
+        #
+        #   if job.error?
+        #     status = job.error
+        #   else
+        #     backup = job.backup
+        #   end
+        #
+        class Job
+          ##
+          # @private The `Gapic::Operation` gRPC object.
+          attr_accessor :grpc
+
+          ##
+          # @private The gRPC Service object.
+          attr_accessor :service
+
+          ##
+          # @private Creates a new Backup::Job instance.
+          def initialize
+            @grpc = nil
+            @service = nil
+          end
+
+          ##
+          # The backup is the object of the operation.
+          #
+          # @return [Backup, nil] The backup, or
+          #   `nil` if the operation is not complete.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #   job.reload!
+          #   job.done? #=> true
+          #   backup = job.backup
+          #
+          def backup
+            return nil unless done?
+            return nil unless @grpc.grpc_op.result == :response
+            Backup.from_grpc @grpc.results, service
+          end
+
+          ##
+          # Checks if the processing of the backup operation is complete.
+          #
+          # @return [boolean] `true` when complete, `false` otherwise.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #
+          def done?
+            @grpc.done?
+          end
+
+          ##
+          # Checks if the processing of the backup operation has errored.
+          #
+          # @return [boolean] `true` when errored, `false` otherwise.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.error? #=> false
+          #
+          def error?
+            @grpc.error?
+          end
+
+          ##
+          # The status if the operation associated with this job produced an
+          # error.
+          #
+          # @return [Google::Cloud::Spanner::Status, nil] A status object with
+          #   the status code and message, or `nil` if no error occurred.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.error? # true
+          #
+          #   error = job.error
+          #
+          def error
+            return nil unless error?
+            Google::Cloud::Spanner::Status.from_grpc @grpc.error
+          end
+
+          ##
+          # Reloads the job with current data from the long-running,
+          # asynchronous processing of a backup operation.
+          #
+          # @return [Google::Cloud::Spanner::Backup::Job] The same job
+          #   instance.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #   job.reload! # API call
+          #   job.done? #=> true
+          #
+          def reload!
+            @grpc.reload!
+            self
+          end
+          alias 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
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #   job.wait_until_done!
+          #   job.done? #=> true
+          #
+          def wait_until_done!
+            @grpc.wait_until_done!
+          end
+
+          ##
+          # Cancel the backup job.
+          #
+          # @example
+          #   require "google/cloud/spanner"
+          #
+          #   spanner = Google::Cloud::Spanner.new
+          #
+          #   database = spanner.database "my-instance", "my-database"
+          #   expire_time = Time.now + 36000
+          #   job = database.create_backup "my-backup", expire_time: expire_time
+          #
+          #   job.done? #=> false
+          #   job.cancel
+          #
+          def cancel
+            @grpc.cancel
+          end
+
+          ##
+          # The operation progress in percentage.
+          #
+          # @return [Integer]
+          def progress_percent
+            @grpc.metadata.progress.progress_percent
+          end
+
+          ##
+          # The operation start time.
+          #
+          # @return [Time, nil]
+          def start_time
+            return nil unless @grpc.metadata.progress.start_time
+            Convert.timestamp_to_time @grpc.metadata.progress.start_time
+          end
+
+          ##
+          # The operation end time.
+          #
+          # @return [Time, nil]
+          def end_time
+            return nil unless @grpc.metadata.progress.end_time
+            Convert.timestamp_to_time @grpc.metadata.progress.end_time
+          end
+
+          ##
+          # The operation canceled time.
+          #
+          # @return [Time, nil]
+          def cancel_time
+            return nil unless @grpc.metadata.cancel_time
+            Convert.timestamp_to_time @grpc.metadata.cancel_time
+          end
+
+          ##
+          # @private New Backup::Job from a `Gapic::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

data/lib/google/cloud/spanner/backup/job/list.rb

@@ -0,0 +1,177 @@
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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 Backup
+        class Job
+          ##
+          # # List
+          #
+          # List is a special case Array with additional values for backup
+          # operations.
+          #
+          class List < DelegateClass(::Array)
+            # @private
+            # The gRPC Service object.
+            attr_accessor :service
+
+            # @private
+            # The gRPC page enumerable object.
+            attr_accessor :grpc
+
+            ##
+            # @private Create a new Backup::Job::List with an array of
+            # Google::Lognrunning::Operation instances.
+            def initialize arr = []
+              super arr
+            end
+
+            ##
+            # Whether there is a next page of backup jobs.
+            #
+            # @return [Boolean]
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #
+            #   jobs = instance.backup_operations
+            #   if jobs.next?
+            #     next_jobs = jobs.next
+            #   end
+            #
+            def next?
+              grpc.next_page?
+            end
+
+            ##
+            # Retrieve the next page of backup jobs.
+            #
+            # @return [Backup::Job::List]
+            #
+            # @example
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #
+            #   jobs = instance.backup_operations
+            #   if jobs.next?
+            #     next_jobs = jobs.next
+            #   end
+            #
+            def next
+              ensure_service!
+
+              return nil unless next?
+              grpc.next_page
+              self.class.from_grpc grpc, service
+            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.
+            #
+            # @yield [job] The block for accessing each backup job.
+            # @yieldparam [Google::Cloud::Spanner::Backup::Job] job The backup
+            #   job object.
+            #
+            # @return [Enumerator]
+            #
+            # @example Iterating each backup job by passing a block:
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #
+            #   jobs = instance.backup_operations
+            #   jobs.all do |job|
+            #     puts job.backup.backup_id
+            #   end
+            #
+            # @example Using the enumerator by not passing a block:
+            #   require "google/cloud/spanner"
+            #
+            #   spanner = Google::Cloud::Spanner.new
+            #
+            #   instance = spanner.instance "my-instance"
+            #
+            #   jobs = instance.backup_operations
+            #   all_backup_ids = jobs.all.map do |job|
+            #     job.backup.backup_id
+            #   end
+            #
+            def all
+              return enum_for :all unless block_given?
+
+              results = self
+              loop do
+                results.each { |r| yield r }
+                break unless next?
+                grpc.next_page
+                results = self.class.from_grpc grpc, service
+              end
+            end
+
+            ##
+            # @private
+            #
+            # New Backup::Job::List from a
+            # `Gapic::PagedEnumerable<Google::Longrunning::Operation>`
+            # object. Operation object is a backup operation.
+            #
+            def self.from_grpc grpc, service
+              operations_client = \
+                service.databases.instance_variable_get "@operations_client"
+              jobs = new(Array(grpc.response.operations).map do |job_grpc|
+                Job.from_grpc \
+                  Gapic::Operation.new(job_grpc, operations_client),
+                  service
+              end)
+              jobs.grpc = grpc
+              jobs.service = service
+              jobs
+            end
+
+            protected
+
+            ##
+            # Raise an error unless an active service is available.
+            def ensure_service!
+              raise "Must have active connection" unless @service
+            end
+          end
+        end
+      end
+    end
+  end
+end