Packagecom.myflashlab.air.extensions.firebase.firestore
Classpublic class Transaction
InheritanceTransaction Inheritance flash.events.EventDispatcher

A Transaction is passed to a native detached thread to provide the methods to read and write data within the transaction context. Only one transaction can be active at any time. When working with Transactions, consider the following outline.

View the examples



Public Properties
 PropertyDefined By
  outcome : String
[write-only] Exactly before calling the keep method, you must set your transaction outcome in this property.
Transaction
Public Methods
 MethodDefined By
  
abort():void
Call this method if you want to abort your transaction.
Transaction
  
execute():void
Executes the transaction and then attempts to commit the changes applied within the transaction.
Transaction
  
keep():void
Call this method if you want to keep your transaction.
Transaction
  
omit($document:DocumentReference, $onComplete:Function):void
Deletes the document referred to by the provided DocumentReference.
Transaction
  
read($document:DocumentReference, $onComplete:Function):void
Reads the document referenced by this DocumentReference
Transaction
  
update($document:DocumentReference, $data:Object, $onComplete:Function):void
Updates fields in the document referred to by the provided DocumentReference.
Transaction
  
write($document:DocumentReference, $data:Object, $onComplete:Function, $options:SetOptions = null):void
Writes to the document referred to by the provided DocumentReference.
Transaction
Property Detail
outcomeproperty
outcome:String  [write-only]

Exactly before calling the keep method, you must set your transaction outcome in this property. this value will be returned to you with the FirestoreEvents.TRANSACTION_COMPLETE listener.


Implementation
    public function set outcome(value:String):void
Method Detail
abort()method
public function abort():void

Call this method if you want to abort your transaction.

execute()method 
public function execute():void

Executes the transaction and then attempts to commit the changes applied within the transaction. If any document read within the transaction has changed, the updateFunction will be retried. If it fails to commit after 5 attempts, the transaction will fail.

You must create new instance of Transactions by calling Firestore.createTransaction(). Only one transaction can be active at any time.

See also

keep()method 
public function keep():void

Call this method if you want to keep your transaction. Make sure you have set the transaction "outcome" property.

omit()method 
public function omit($document:DocumentReference, $onComplete:Function):void

Deletes the document referred to by the provided DocumentReference.

Parameters

$document:DocumentReference — The DocumentReference to delete.
 
$onComplete:Function — Function to be called when the process completes. This function expects "no" parameters.

read()method 
public function read($document:DocumentReference, $onComplete:Function):void

Reads the document referenced by this DocumentReference

Parameters

$document:DocumentReference — The DocumentReference to read.
 
$onComplete:Function — Function to be called when the process completes. This function expects "two" parameters as follow: function onComplete($snapshot:DocumentSnapshot, $err:String):void if $err is not null, it means the "read" has been successfull and $snapshot will be available.

update()method 
public function update($document:DocumentReference, $data:Object, $onComplete:Function):void

Updates fields in the document referred to by the provided DocumentReference. If no document exists yet, the update will fail.

Parameters

$document:DocumentReference — The DocumentReference to update.
 
$data:Object — An object to update. Fields can contain dots to reference nested fields within the document.
 
$onComplete:Function — Function to be called when the process completes. This function expects "no" parameters.

write()method 
public function write($document:DocumentReference, $data:Object, $onComplete:Function, $options:SetOptions = null):void

Writes to the document referred to by the provided DocumentReference. If the document does not yet exist, it will be created. If you pass SetOptions, the provided data can be merged into an existing document.

Parameters

$document:DocumentReference — The DocumentReference to overwrite.
 
$data:Object — An Object of the fields and values for the document.
 
$onComplete:Function — Function to be called when the process completes. This function expects "no" parameters.
 
$options:SetOptions (default = null) — An object to configure the set behavior.

Examples
The following example shows how to work with transactions.
 var trans:Transaction = Firestore.createTransaction();
 if(trans)
 {
     myTransaction = trans;
      
     myTransaction.addEventListener(FirestoreEvents.TRANSACTION_BEGIN, onTransactionBegin);
     myTransaction.addEventListener(FirestoreEvents.TRANSACTION_COMPLETE, onTransactionComplete);
     myTransaction.addEventListener(FirestoreEvents.TRANSACTION_FAILURE, onTransactionFailure);
      
     // to start working with the transaction, you must wait for the "TRANSACTION_BEGIN" event to happen
     myTransaction.execute();
 }
 else
 {
     // Every transaction will be finished when you call either of these methods:
     // myTransaction.abort();
     // myTransaction.keep();
     trace("another transaction is not released yet");
 }
  
 function onTransactionBegin(e:FirestoreEvents):void
 {
     trace(">> onTransactionBegin");
      
     // If you want to read more that one DocumentReference, you must read each inside the prior onReadComplete functions.
     myTransaction.read(myDocument, onReadComplete);
 }
  
 function onReadComplete($snapshot:DocumentSnapshot, $err:String):void
 {
     if($err)
     {
         trace("could not read the document: " + $err);
         myTransaction.abort();
     }
     else
     {
         trace("ReadSuccess, data: " + JSON.stringify($snapshot.data));
          
         // increment the current value in database
         var newValue:int = $snapshot.data.population + 1;
          
          
         if(newValue > 1000000)
         {
             trace("value is more than what our game needs.");
             myTransaction.abort();
         }
         else
         {
              
             // payload message will be delivered to the TRANSACTION_COMPLETE event.
             // you must change your UI based on this message known as the transaction outcome.
             // in our example, you must not use the "newValue" value to change your UI, instead
             // you must pass it through the "keep()" method and change your UI when TRANSACTION_COMPLETE
             // happens.
              
             myTransaction.outcome = "payload message which can be anything for example a json String";
             myTransaction.update(myDocument, {population:newValue}, onUpdateComplete);
         }
     }
 }
  
 function onUpdateComplete():void
 {
      
     // You must call the "keep" method when you are sure the "write, update or omit" commands have
     // finished their job. In this example, we are calling the "keep" method when the last "update"
     // method is finished through "onUpdateComplete"
      
     myTransaction.keep();
 }
  
 function onTransactionComplete(e:FirestoreEvents):void
 {
     trace("onTransactionComplete: " + e.transactionOutcome);
      
     myTransaction.removeEventListener(FirestoreEvents.TRANSACTION_BEGIN, onTransactionBegin);
     myTransaction.removeEventListener(FirestoreEvents.TRANSACTION_COMPLETE, onTransactionComplete);
     myTransaction.removeEventListener(FirestoreEvents.TRANSACTION_FAILURE, onTransactionFailure);
 }
  
 function onTransactionFailure(e:FirestoreEvents):void
 {
     trace("onTransactionFailure: " + e.msg);
      
     myTransaction.removeEventListener(FirestoreEvents.TRANSACTION_BEGIN, onTransactionBegin);
     myTransaction.removeEventListener(FirestoreEvents.TRANSACTION_COMPLETE, onTransactionComplete);
     myTransaction.removeEventListener(FirestoreEvents.TRANSACTION_FAILURE, onTransactionFailure);
 }