com.google.appengine.api.datastore.BaseDatastoreService Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of appengine-api-1.0-sdk
API for Google App Engine standard environment with some of the dependencies shaded (repackaged)
There is a newer version: 2.0.27
/*
 * Copyright 2021 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.
 */

package com.google.appengine.api.datastore;

import java.util.Collection;

/**
 * Methods that are common between {@link DatastoreService} and {@link AsyncDatastoreService}.
 *
 */
public interface BaseDatastoreService {

  /**
   * Prepares a query for execution.
   *
   * This method returns a {@link PreparedQuery} which can be used to execute and retrieve
   * results from the datastore for {@code query}.
   *
   * 
This operation will not execute in a transaction even if there is a current transaction and
   * the provided query is an ancestor query. This operation also ignores the {@link
   * ImplicitTransactionManagementPolicy}. If you are preparing an ancestory query and you want it
   * to execute in a transaction, use {@link #prepare(Transaction, Query)}.
   *
   * @param query a not {@code null Query}.
   * @return a not {@code null PreparedQuery}.
   */
  PreparedQuery prepare(Query query);

  /**
   * Exhibits the same behavior as {@link #prepare(Query)}, but executes within the provided
   * transaction. It is up to the caller to commit or rollback. Transaction can be null.
   *
   * @throws IllegalArgumentException If txn is not null and query is not an ancestor query
   * @throws IllegalStateException If txn is not null and the txn is not active
   */
  PreparedQuery prepare(Transaction txn, Query query);

  /**
   * Returns the current transaction for this thread, or throws an exception if there is no current
   * transaction. The current transaction is defined as the result of the most recent, same-thread
   * invocation of beginTransaction() that has not been committed or rolled back.
   *
   * 
Use this method for when you expect there to be a current transaction and consider it an
   * error if there isn't.
   *
   * @return The current transaction.
   * @throws java.util.NoSuchElementException If there is no current transaction.
   */
  Transaction getCurrentTransaction();

  /**
   * Returns the current transaction for this thread, or returns the parameter if there is no
   * current transaction. You can use {@code null} or provide your own object to represent null. See
   * {@link #getCurrentTransaction()} for a definition of "current transaction."
   *
   * Use this method when you're not sure if there is a current transaction.
   *
   * @param returnedIfNoTxn The return value of this method if there is no current transaction. Can
   *     be null.
   * @return The current transaction, or the parameter that was passed in if there is no current
   *     transaction.
   */
  Transaction getCurrentTransaction(Transaction returnedIfNoTxn);

  /**
   * Returns all {@link Transaction}s started by this thread upon which no attempt to commit or
   * rollback has been made.
   */
  Collection getActiveTransactions();
}