Package com.apple.foundationdb

Interface Tenant

All Superinterfaces:
AutoCloseable, ReadTransactionContext, TransactionContext
public interface Tenant extends AutoCloseable, TransactionContext
A tenant represents a named key-space within a database that can be interacted with transactionally.

The simplest correct programs using tenants will make use of the methods defined in the TransactionContext interface. When used on a Tenant these methods will call Transaction#commit() after user code has been executed. These methods will not return successfully until commit() has returned successfully.

Note: Tenant objects must be closed when no longer in use in order to free any associated resources.

  • Method Details

    • createTransaction

      default Transaction createTransaction()
      Creates a Transaction that operates on this Tenant.

      Note: Java transactions automatically set the TransactionOptions.setUsedDuringCommitProtectionDisable() option. This is because the Java bindings disallow use of Transaction objects after Transaction.onError(java.lang.Throwable) is called.
      Returns:
      a newly created Transaction that reads from and writes to this Tenant.

    • createTransaction

      Transaction createTransaction(Executor e)
      Creates a Transaction that operates on this Tenant with the given Executor for asynchronous callbacks.
      Parameters:
      e - the Executor to use when executing asynchronous callbacks.
      Returns:
      a newly created Transaction that reads from and writes to this Tenant.

    • createTransaction

      Transaction createTransaction(Executor e, EventKeeper eventKeeper)
      Creates a Transaction that operates on this Tenant with the given Executor for asynchronous callbacks.
      Parameters:
      e - the Executor to use when executing asynchronous callbacks.
      eventKeeper - the EventKeeper to use when tracking instrumented calls for the transaction.
      Returns:
      a newly created Transaction that reads from and writes to this Tenant.

    • getName

      byte[] getName()
      Returns the name of this Tenant.
      Returns:
      the name of this Tenant as a byte string.

    • read

      default <T> T read(Function<? super ReadTransaction,T> retryable)
      Runs a read-only transactional function against this Tenant with retry logic. apply(ReadTransaction) will be called on the supplied Function until a non-retryable FDBException (or any Throwable other than an FDBException) is thrown. This call is blocking -- this method will not return until the Function has been called and completed without error.
      Specified by:
      read in interface ReadTransactionContext
      Type Parameters:
      T - the return type of retryable
      Parameters:
      retryable - the block of logic to execute in a Transaction against this tenant
      Returns:
      the result of the last run of retryable

    • read

      <T> T read(Function<? super ReadTransaction,T> retryable, Executor e)
      Runs a read-only transactional function against this Tenant with retry logic. Use this formulation of read(Function) if one wants to set a custom Executor for the transaction when run.
      Type Parameters:
      T - the return type of retryable
      Parameters:
      retryable - the block of logic to execute in a Transaction against this tenant
      e - the Executor to use for asynchronous callbacks
      Returns:
      the result of the last run of retryable
      See Also:

    • readAsync

      default <T> CompletableFuture<T> readAsync(Function<? super ReadTransaction,? extends CompletableFuture<T>> retryable)
      Runs a read-only transactional function against this Tenant with retry logic. apply(ReadTransaction) will be called on the supplied Function until a non-retryable FDBException (or any Throwable other than an FDBException) is thrown. This call is non-blocking -- this method will return immediately and with a CompletableFuture that will be set when the Function has been called and completed without error.

      Any errors encountered executing retryable, or received from the database, will be set on the returned CompletableFuture.
      Specified by:
      readAsync in interface ReadTransactionContext
      Type Parameters:
      T - the return type of retryable
      Parameters:
      retryable - the block of logic to execute in a ReadTransaction against this tenant
      Returns:
      a CompletableFuture that will be set to the value returned by the last call to retryable

    • readAsync

      <T> CompletableFuture<T> readAsync(Function<? super ReadTransaction,? extends CompletableFuture<T>> retryable, Executor e)
      Runs a read-only transactional function against this Tenant with retry logic. Use this version of readAsync(Function) if one wants to set a custom Executor for the transaction when run.
      Type Parameters:
      T - the return type of retryable
      Parameters:
      retryable - the block of logic to execute in a ReadTransaction against this tenant
      e - the Executor to use for asynchronous callbacks
      Returns:
      a CompletableFuture that will be set to the value returned by the last call to retryable
      See Also:

    • run

      default <T> T run(Function<? super Transaction,T> retryable)
      Runs a transactional function against this Tenant with retry logic. apply(Transaction) will be called on the supplied Function until a non-retryable FDBException (or any Throwable other than an FDBException) is thrown or commit(), when called after apply(), returns success. This call is blocking -- this method will not return until commit() has been called and returned success.

      As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, your transaction may be executed twice. For more information about how to reason about these situations see the FounationDB Developer Guide
      Specified by:
      run in interface TransactionContext
      Type Parameters:
      T - the return type of retryable
      Parameters:
      retryable - the block of logic to execute in a Transaction against this tenant
      Returns:
      the result of the last run of retryable

    • run

      <T> T run(Function<? super Transaction,T> retryable, Executor e)
      Runs a transactional function against this Tenant with retry logic. Use this formulation of run(Function) if one would like to set a custom Executor for the transaction when run.
      Type Parameters:
      T - the return type of retryable
      Parameters:
      retryable - the block of logic to execute in a Transaction against this tenant
      e - the Executor to use for asynchronous callbacks
      Returns:
      the result of the last run of retryable

    • runAsync

      default <T> CompletableFuture<T> runAsync(Function<? super Transaction,? extends CompletableFuture<T>> retryable)
      Runs a transactional function against this Tenant with retry logic. apply(Transaction) will be called on the supplied Function until a non-retryable FDBException (or any Throwable other than an FDBException) is thrown or commit(), when called after apply(), returns success. This call is non-blocking -- this method will return immediately and with a CompletableFuture that will be set when commit() has been called and returned success.

      As with other client/server databases, in some failure scenarios a client may be unable to determine whether a transaction succeeded. In these cases, your transaction may be executed twice. For more information about how to reason about these situations see the FounationDB Developer Guide

      Any errors encountered executing retryable, or received from the database, will be set on the returned CompletableFuture.
      Specified by:
      runAsync in interface TransactionContext
      Type Parameters:
      T - the return type of retryable
      Parameters:
      retryable - the block of logic to execute in a Transaction against this tenant
      Returns:
      a CompletableFuture that will be set to the value returned by the last call to retryable

    • runAsync

      <T> CompletableFuture<T> runAsync(Function<? super Transaction,? extends CompletableFuture<T>> retryable, Executor e)
      Runs a transactional function against this Tenant with retry logic. Use this formulation of the non-blocking runAsync(Function) if one wants to set a custom Executor for the transaction when run.
      Type Parameters:
      T - the return type of retryable
      Parameters:
      retryable - the block of logic to execute in a Transaction against this tenant
      e - the Executor to use for asynchronous callbacks
      Returns:
      a CompletableFuture that will be set to the value returned by the last call to retryable
      See Also:

    • purgeBlobGranules

      default CompletableFuture<byte[]> purgeBlobGranules(byte[] beginKey, byte[] endKey, boolean force)
      Runs purgeBlobGranules(byte[] beginKey, byte[] endKey, boolean force) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      force - if true delete all data, if not keep data >= purgeVersion
      Returns:
      the key to watch for purge complete

    • purgeBlobGranules

      default CompletableFuture<byte[]> purgeBlobGranules(byte[] beginKey, byte[] endKey, long purgeVersion, boolean force)
      Runs purgeBlobGranules(byte[] beginKey, byte[] endKey, long purgeVersion, boolean force) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      purgeVersion - version to purge at
      force - if true delete all data, if not keep data >= purgeVersion
      Returns:
      the key to watch for purge complete

    • purgeBlobGranules

      CompletableFuture<byte[]> purgeBlobGranules(byte[] beginKey, byte[] endKey, long purgeVersion, boolean force, Executor e)
      Queues a purge of blob granules for specified key range of this tenant, at the specified version.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      purgeVersion - version to purge at
      force - if true delete all data, if not keep data >= purgeVersion
      e - the Executor to use for asynchronous callbacks
      Returns:
      the key to watch for purge complete

    • waitPurgeGranulesComplete

      default CompletableFuture<Void> waitPurgeGranulesComplete(byte[] purgeKey)
      Runs waitPurgeGranulesComplete(byte[] purgeKey) on the default executor.
      Parameters:
      purgeKey - key to watch
      Returns:
      void

    • waitPurgeGranulesComplete

      CompletableFuture<Void> waitPurgeGranulesComplete(byte[] purgeKey, Executor e)
      Wait for a previous call to purgeBlobGranules to complete.
      Parameters:
      purgeKey - key to watch
      e - the Executor to use for asynchronous callbacks
      Returns:
      void

    • blobbifyRange

      default CompletableFuture<Boolean> blobbifyRange(byte[] beginKey, byte[] endKey)
      Runs blobbifyRange(byte[] beginKey, byte[] endKey) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      Returns:
      if the recording of the range was successful

    • blobbifyRange

      CompletableFuture<Boolean> blobbifyRange(byte[] beginKey, byte[] endKey, Executor e)
      Sets a range to be blobbified in this tenant. Must be a completely unblobbified range.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      e - the Executor to use for asynchronous callbacks
      Returns:
      if the recording of the range was successful

    • blobbifyRangeBlocking

      default CompletableFuture<Boolean> blobbifyRangeBlocking(byte[] beginKey, byte[] endKey)
      Runs blobbifyRangeBlocking(byte[] beginKey, byte[] endKey, Executor e) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      Returns:
      if the recording of the range was successful

    • blobbifyRangeBlocking

      CompletableFuture<Boolean> blobbifyRangeBlocking(byte[] beginKey, byte[] endKey, Executor e)
      Sets a range to be blobbified in this tenant. Must be a completely unblobbified range.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      e - the Executor to use for asynchronous callbacks
      Returns:
      if the recording of the range was successful

    • unblobbifyRange

      default CompletableFuture<Boolean> unblobbifyRange(byte[] beginKey, byte[] endKey)
      Runs unblobbifyRange(byte[] beginKey, byte[] endKey) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      Returns:
      if the recording of the range was successful

    • unblobbifyRange

      CompletableFuture<Boolean> unblobbifyRange(byte[] beginKey, byte[] endKey, Executor e)
      Unsets a blobbified range in this tenant. The range must be aligned to known blob ranges.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      e - the Executor to use for asynchronous callbacks
      Returns:
      if the recording of the range was successful

    • listBlobbifiedRanges

      default CompletableFuture<KeyRangeArrayResult> listBlobbifiedRanges(byte[] beginKey, byte[] endKey, int rangeLimit)
      Runs listBlobbifiedRanges(byte[] beginKey, byte[] endKey, int rangeLimit) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      rangeLimit - batch size
      Returns:
      a future with the list of blobbified ranges: [lastLessThan(beginKey), firstGreaterThanOrEqual(endKey)]

    • listBlobbifiedRanges

      CompletableFuture<KeyRangeArrayResult> listBlobbifiedRanges(byte[] beginKey, byte[] endKey, int rangeLimit, Executor e)
      Lists blobbified ranges in this tenant. There may be more if result.size() == rangeLimit.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      rangeLimit - batch size
      e - the Executor to use for asynchronous callbacks
      Returns:
      a future with the list of blobbified ranges: [lastLessThan(beginKey), firstGreaterThanOrEqual(endKey)]

    • verifyBlobRange

      default CompletableFuture<Long> verifyBlobRange(byte[] beginKey, byte[] endKey)
      Runs verifyBlobRange(byte[] beginKey, byte[] endKey) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      Returns:
      a future with the version of the last blob granule.

    • verifyBlobRange

      default CompletableFuture<Long> verifyBlobRange(byte[] beginKey, byte[] endKey, long version)
      Runs verifyBlobRange(byte[] beginKey, byte[] endKey, long version) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      version - version to read at
      Returns:
      a future with the version of the last blob granule.

    • verifyBlobRange

      CompletableFuture<Long> verifyBlobRange(byte[] beginKey, byte[] endKey, long version, Executor e)
      Checks if a blob range is blobbified in this tenant.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      version - version to read at
      e - the executor
      Returns:
      a future with the version of the last blob granule.

    • flushBlobRange

      default CompletableFuture<Boolean> flushBlobRange(byte[] beginKey, byte[] endKey, boolean compact)
      Runs flushBlobRange(byte[] beginKey, byte[] endKey, boolean compact, long version, Executor e) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      compact - force compact or just flush
      Returns:
      a future with a boolean for success or failure

    • flushBlobRange

      default CompletableFuture<Boolean> flushBlobRange(byte[] beginKey, byte[] endKey, boolean compact, long version)
      Runs flushBlobRange(byte[] beginKey, byte[] endKey, boolean compact, long version, Executor e) on the default executor.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      compact - force compact or just flush
      version - version to flush at
      Returns:
      a future with a boolean for success or failure

    • flushBlobRange

      CompletableFuture<Boolean> flushBlobRange(byte[] beginKey, byte[] endKey, boolean compact, long version, Executor e)
      Checks if a blob range is blobbified.
      Parameters:
      beginKey - start of the key range
      endKey - end of the key range
      compact - force compact or just flush
      version - version to flush at
      e - the Executor to use for asynchronous callbacks
      Returns:
      a future with a boolean for success or failure

    • getId

      default CompletableFuture<Long> getId()
      Runs getId() on the default executor.
      Returns:
      a future with the tenant ID

    • getId

      CompletableFuture<Long> getId(Executor e)
      Returns the tenant ID of this tenant.
      Parameters:
      e - the Executor to use for asynchronous callbacks
      Returns:
      a future with the tenant ID

    • close

      void close()
      Close the Tenant object and release any associated resources. This must be called at least once after the Tenant object is no longer in use. This can be called multiple times, but care should be taken that it is not in use in another thread at the time of the call.
      Specified by:
      close in interface AutoCloseable