Package google.registry.persistence.transaction

Interface TransactionManager

All Known Subinterfaces:
JpaTransactionManager
All Known Implementing Classes:
JpaTransactionManagerImpl
public interface TransactionManager
This interface defines the methods to execute database operations with or without a transaction.

  • Method Details

    • inTransaction

      boolean inTransaction()
      Returns true if the caller is in a transaction.

      Note that in the current implementation the entity manager is obtained from a static ThreadLocal object that is set up by the outermost transact(java.util.concurrent.Callable<T>) call. Nested call sites have no control over which database instance to use.

    • assertInTransaction

      void assertInTransaction()
      Throws IllegalStateException if the caller is not in a transaction.

      Note that this function is kept for backward compatibility. We will review the use case later when adding the cloud sql implementation.

    • allocateId

      long allocateId()
      Returns a
      invalid reference 
      long
      value that can be used as id by a JPA model entity.

      The returned value must be project-wide unique when transacting on the primary database instance, but only needs to be unique within a JVM instance when transacting on the replica instance.

    • transact

      <T> T transact(Callable<T> work)
      Executes the work in a transaction and returns the result.

    • transact

      <T> T transact(PersistenceModule.TransactionIsolationLevel isolationLevel, Callable<T> work)
      Executes the work in a transaction at the given PersistenceModule.TransactionIsolationLevel and returns the result.

    • transactNoRetry

      <T> T transactNoRetry(Callable<T> work)
      Executes the work in a transaction and returns the result, without retrying upon retryable exceptions.

      This method should only be used when the transaction contains side effects that are not rolled back by the transaction manager, for example in RegistryJpaIO where the results from a query are streamed to the next transformation inside a transaction, as the result stream has to materialize to a list outside a transaction and doing so would greatly affect the parallelism of the pipeline.

    • transactNoRetry

      <T> T transactNoRetry(PersistenceModule.TransactionIsolationLevel isolationLevel, Callable<T> work)
      Executes the work in a transaction at the given PersistenceModule.TransactionIsolationLevel and returns the result, without retrying upon retryable exceptions.

      This method should only be used when the transaction contains side effects that are not rolled back by the transaction manager, for example in RegistryJpaIO where the results from a query are streamed to the next transformation inside a transaction, as the result stream has to materialize to a list outside a transaction and doing so would greatly affect the parallelism of the pipeline.

    • reTransact

      <T> T reTransact(Callable<T> work)
      Executes the work in a (potentially wrapped) transaction and returns the result.

      Calls to this method are typically going to be in inner functions, that are called either as top-level transactions themselves or are nested inside larger transactions (e.g. a transactional flow). Invocations of reTransact must be vetted to occur in both situations and with such complexity that it is not trivial to refactor out the nested transaction calls. New code should be written in such a way as to avoid requiring reTransact in the first place.

      In the future we will be enforcing that transact(Callable) calls be top-level only, with reTransact calls being the only ones that can potentially be an inner nested transaction (which is a noop). Note that, as this can be a nested inner exception, there is no overload provided to specify a (potentially conflicting) transaction isolation level.

    • transact

      void transact(TransactionManager.ThrowingRunnable work)
      Executes the work in a transaction.

    • transact

      void transact(PersistenceModule.TransactionIsolationLevel isolationLevel, TransactionManager.ThrowingRunnable work)
      Executes the work in a transaction at the given PersistenceModule.TransactionIsolationLevel.

    • reTransact

      void reTransact(TransactionManager.ThrowingRunnable work)
      Executes the work in a (potentially wrapped) transaction and returns the result.

      Calls to this method are typically going to be in inner functions, that are called either as top-level transactions themselves or are nested inside larger transactions (e.g. a transactional flow). Invocations of reTransact must be vetted to occur in both situations and with such complexity that it is not trivial to refactor out the nested transaction calls. New code should be written in such a way as to avoid requiring reTransact in the first place.

      In the future we will be enforcing that transact(ThrowingRunnable) calls be top-level only, with reTransact calls being the only ones that can potentially be an inner nested transaction (which is a noop). Note that, as this can be a nested inner exception, there is no overload provided to specify a (potentially conflicting) transaction isolation level.

    • getTransactionTime

      org.joda.time.DateTime getTransactionTime()
      Returns the time associated with the start of this particular transaction attempt.

    • insert

      void insert(Object entity)
      Persists a new entity in the database, throws exception if the entity already exists.

    • insertAll

      void insertAll(com.google.common.collect.ImmutableCollection<?> entities)
      Persists all new entities in the database, throws exception if any entity already exists.

    • insertAll

      void insertAll(ImmutableObject... entities)
      Persists all new entities in the database, throws exception if any entity already exists.

    • put

      void put(Object entity)
      Persists a new entity or update the existing entity in the database.

    • putAll

      void putAll(ImmutableObject... entities)
      Persists all new entities or updates the existing entities in the database.

    • putAll

      void putAll(com.google.common.collect.ImmutableCollection<?> entities)
      Persists all new entities or updates the existing entities in the database.

    • update

      void update(Object entity)
      Updates an entity in the database, throws exception if the entity does not exist.

    • updateAll

      void updateAll(com.google.common.collect.ImmutableCollection<?> entities)
      Updates all entities in the database, throws exception if any entity does not exist.

    • updateAll

      void updateAll(ImmutableObject... entities)
      Updates all entities in the database, throws exception if any entity does not exist.

    • exists

      boolean exists(Object entity)
      Returns whether the given entity with same ID exists.

    • exists

      <T> boolean exists(VKey<T> key)
      Returns whether the entity of given key exists.

    • loadByKeyIfPresent

      <T> Optional<T> loadByKeyIfPresent(VKey<T> key)
      Loads the entity by its key, returns empty if the entity doesn't exist.

    • loadByKeysIfPresent

      <T> com.google.common.collect.ImmutableMap<VKey<? extends T>,T> loadByKeysIfPresent(Iterable<? extends VKey<? extends T>> keys)
      Loads the set of entities by their keys.

      Nonexistent keys / entities are absent from the resulting map, but no NoSuchElementException will be thrown.

    • loadByEntitiesIfPresent

      <T> com.google.common.collect.ImmutableList<T> loadByEntitiesIfPresent(Iterable<T> entities)
      Loads all given entities from the database if possible.

      Nonexistent entities are absent from the resulting list, but no NoSuchElementException will be thrown.

    • loadByKey

      <T> T loadByKey(VKey<T> key)
      Loads the entity by its key.
      Throws:
      NoSuchElementException - if this key does not correspond to an existing entity.

    • loadByKeys

      <T> com.google.common.collect.ImmutableMap<VKey<? extends T>,T> loadByKeys(Iterable<? extends VKey<? extends T>> keys)
      Loads the set of entities by their keys.
      Throws:
      NoSuchElementException - if any of the keys do not correspond to an existing entity.

    • loadByEntity

      <T> T loadByEntity(T entity)
      Loads the given entity from the database.
      Throws:
      NoSuchElementException - if the entity does not exist in the database.

    • loadByEntities

      <T> com.google.common.collect.ImmutableList<T> loadByEntities(Iterable<T> entities)
      Loads all given entities from the database.
      Throws:
      NoSuchElementException - if any of the entities do not exist in the database.

    • loadAllOf

      <T> com.google.common.collect.ImmutableList<T> loadAllOf(Class<T> clazz)
      Returns a list of all entities of the given type that exist in the database.

      The resulting list is empty if there are no entities of this type.

    • loadAllOfStream

      <T> Stream<T> loadAllOfStream(Class<T> clazz)
      Returns a stream of all entities of the given type that exist in the database.

      The resulting stream is empty if there are no entities of this type.

    • loadSingleton

      <T> Optional<T> loadSingleton(Class<T> clazz)
      Loads the only instance of this particular class, or empty if none exists.

      Throws an exception if there is more than one element in the table.

    • delete

      void delete(VKey<?> key)
      Deletes the entity by its id.

    • delete

      void delete(Iterable<? extends VKey<?>> keys)
      Deletes the set of entities by their key id.

    • delete

      <T> T delete(T entity)
      Deletes the given entity from the database.

      This returns the deleted entity, which may not necessarily be the same as the original entity passed in, as it may be a) converted to a different type of object more appropriate to the database type or b) merged with an object managed by the database entity manager.

    • createQueryComposer

      <T> QueryComposer<T> createQueryComposer(Class<T> entity)
      Returns a QueryComposer which can be used to perform queries against the current database.