class Google::Cloud::Firestore::DocumentListener
An ongoing listen operation on a document reference. This is returned by calling {DocumentReference#listen}.
@example
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a document reference nyc_ref = firestore.doc "cities/NYC" listener = nyc_ref.listen do |snapshot| puts "The population of #{snapshot[:name]} is #{snapshot[:population]}." end # When ready, stop the listen operation and close the stream. listener.stop
Public Class Methods
@private Creates the watch stream and listener object.
# File lib/google/cloud/firestore/document_listener.rb, line 48 def initialize doc_ref, &callback super() # to init MonitorMixin @doc_ref = doc_ref raise ArgumentError if @doc_ref.nil? @callback = callback raise ArgumentError if @callback.nil? @error_callbacks = [] @listener = Watch::Listener.for_doc_ref self, doc_ref do |query_snp| doc_snp = query_snp.docs.find { |doc| doc.path == @doc_ref.path } if doc_snp.nil? doc_snp = DocumentSnapshot.missing \ @doc_ref, read_at: query_snp.read_at end @callback.call doc_snp end end
Public Instance Methods
@private Pass the error to user-provided error callbacks.
# File lib/google/cloud/firestore/document_listener.rb, line 194 def error! error error_callbacks = synchronize do @last_error = error @error_callbacks.dup end error_callbacks.each { |error_callback| error_callback.call error } end
The most recent unhandled error to occur while listening for changes.
If an unhandled error has occurred the listener will attempt to recover from the error and resume listening.
@return [Exception, nil] error The most recent error raised.
@example
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a document reference nyc_ref = firestore.doc "cities/NYC" listener = nyc_ref.listen do |snapshot| puts "The population of #{snapshot[:name]} is #{snapshot[:population]}." end # If an error was raised, it can be retrieved here: listener.last_error #=> nil # When ready, stop the listen operation and close the stream. listener.stop
# File lib/google/cloud/firestore/document_listener.rb, line 189 def last_error synchronize { @last_error } end
Register to be notified of errors when raised.
If an unhandled error has occurred the listener will attempt to recover from the error and resume listening.
Multiple error handlers can be added.
@yield [callback] The block to be called when an error is raised. @yieldparam [Exception] error The error raised.
@example
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a document reference nyc_ref = firestore.doc "cities/NYC" listener = nyc_ref.listen do |snapshot| puts "The population of #{snapshot[:name]} is #{snapshot[:population]}." end # Register to be notified when unhandled errors occur. listener.on_error do |error| puts error end # When ready, stop the listen operation and close the stream. listener.stop
# File lib/google/cloud/firestore/document_listener.rb, line 158 def on_error &block raise ArgumentError, "on_error must be called with a block" unless block_given? synchronize { @error_callbacks << block } end
@private
# File lib/google/cloud/firestore/document_listener.rb, line 72 def start @listener.start self end
Stops the client listening for changes.
@example
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a document reference nyc_ref = firestore.doc "cities/NYC" listener = nyc_ref.listen do |snapshot| puts "The population of #{snapshot[:name]} is #{snapshot[:population]}." end # When ready, stop the listen operation and close the stream. listener.stop
# File lib/google/cloud/firestore/document_listener.rb, line 95 def stop @listener.stop end
Whether the client has stopped listening for changes.
@example
require "google/cloud/firestore" firestore = Google::Cloud::Firestore.new # Get a document reference nyc_ref = firestore.doc "cities/NYC" listener = nyc_ref.listen do |snapshot| puts "The population of #{snapshot[:name]} is #{snapshot[:population]}." end # Checks if the listener is stopped. listener.stopped? #=> false # When ready, stop the listen operation and close the stream. listener.stop # Checks if the listener is stopped. listener.stopped? #=> true
# File lib/google/cloud/firestore/document_listener.rb, line 123 def stopped? @listener.stopped? end