com.google.firebase.database.Transaction Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of firebase-admin Show documentation
This is the official Firebase Admin Java SDK. Build extraordinary native JVM apps in minutes with Firebase. The Firebase platform can power your app’s backend, user authentication, static hosting, and more.
There is a newer version: 9.2.0
Show newest version
/*
 * Copyright 2017 Google Inc.
 *
 * 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.
 */

package com.google.firebase.database;

import com.google.firebase.database.snapshot.Node;

/**
 * The Transaction class encapsulates the functionality needed to perform a transaction on the data
 * at a location. 

 * 

 * To run a transaction, provide a {@link Handler} to {@link
 * DatabaseReference#runTransaction(com.google.firebase.database.Transaction.Handler)}. That handler
 * will be passed the current data at the location, and must return a {@link Result}. A {@link
 * Result} can be created using either {@link Transaction#success(MutableData)} or {@link
 * com.google.firebase.database.Transaction#abort()}.
 */
public class Transaction {

  /** 
   * @return A {@link Result} that aborts the transaction
   */
  public static Result abort() {
    return new Result(false, null);
  }

  /**
   * @param resultData The desired data at the location
   * @return A {@link Result} indicating the new data to be stored at the location
   */
  public static Result success(MutableData resultData) {
    return new Result(true, resultData.getNode());
  }

  /**
   * An object implementing this interface is used to run a transaction, and will be notified of the
   * results of the transaction.
   */
  public interface Handler {

    /**
     * This method will be called, possibly multiple times, with the current data at this
     * location. It is responsible for inspecting that data and returning a {@link Result}
     * specifying either the desired new data at the location or that the transaction should be
     * aborted. 

     * 

     * Since this method may be called repeatedly for the same transaction, be extremely careful of
     * any side effects that may be triggered by this method. In addition, this method is called
     * from within the Firebase Database library's run loop, so care is also required when accessing
     * data that may be in use by other threads in your application. 

     * 

     * Best practices for this method are to rely only on the data that is passed in.
     *
     * @param currentData The current data at the location. Update this to the desired data at the
     *     location
     * @return Either the new data, or an indication to abort the transaction
     */
    Result doTransaction(MutableData currentData);

    /**
     * This method will be called once with the results of the transaction.
     *
     * @param error null if no errors occurred, otherwise it contains a description of the error
     * @param committed True if the transaction successfully completed, false if it was aborted or
     *     an error occurred
     * @param currentData The current data at the location
     */
    void onComplete(DatabaseError error, boolean committed, DataSnapshot currentData);
  }

  /**
   * Instances of this class represent the desired outcome of a single run of a {@link Handler}'s
   * doTransaction method. The options are:
   *
   * 
   *   Set the data to the new value (success)
   *   
abort the transaction
   * 
   *
   * Instances are created using {@link Transaction#success(MutableData)} or {@link
   * com.google.firebase.database.Transaction#abort()}.
   */
  public static class Result {

    private boolean success;
    private Node data;

    private Result(boolean success, Node data) {
      this.success = success;
      this.data = data;
    }

    /** 
     * @return Whether or not this result is a success
     */
    public boolean isSuccess() {
      return success;
    }

    /**
     * For internal use
     *
     * @hide
     * @return The data
     */
    public Node getNode() {
      return data;
    }
  }
}