Package com.apple.foundationdb.record.provider.foundationdb

Class FDBDatabaseFactory

  • @API(STABLE)
public class FDBDatabaseFactory
extends Object
    A singleton maintaining a list of FDBDatabase instances, indexed by their cluster file location.

    • Constructor Detail

      • FDBDatabaseFactory

        public FDBDatabaseFactory()

    • Method Detail

      • initFDB

        protected FDB initFDB()

      • setNetworkExecutor

        public void setNetworkExecutor​(@Nonnull
                               Executor networkExecutor)

      • setExecutor

        public void setExecutor​(@Nonnull
                        Executor executor)
        Sets the executor that will be used for all asynchronous tasks that are produced from operations initiated from databases produced from this factory.
        Parameters:
        executor - the executor to be used for asynchronous task completion

      • setContextExecutor

        public void setContextExecutor​(@Nonnull
                               Function<Executor,​Executor> contextExecutor)
        Provides a function that will be invoked when a FDBRecordContext is created, taking as input the Executor that is configured for the database, returning the Executor that will be used to execute all asynchronous completions produced from the FDBRecordContext. An example use case for this function is to ensure that ThreadLocal variables that are present in the thread that creates the FDBRecordContext will be made present in the executor threads that are executing tasks.
        Parameters:
        contextExecutor - function to produce an executor to be used for all tasks executed on behalf of a specific record context

      • newContextExecutor

        @Nonnull
protected Executor newContextExecutor​(@Nullable
                                      Map<String,​String> mdcContext)
        Creates a new Executor for use by a specific FDBRecordContext. If mdcContext is not null, the executor will ensure that the provided MDC present within the context of the executor thread.
        Parameters:
        mdcContext - if present, the MDC context to be made available within the executors threads
        Returns:
        a new executor to be used by a FDBRecordContext

      • shutdown

        public void shutdown()

      • clear

        public void clear()

      • isUnclosedWarning

        public boolean isUnclosedWarning()

      • setUnclosedWarning

        public void setUnclosedWarning​(boolean unclosedWarning)

      • setTrace

        public void setTrace​(@Nullable
                     String traceDirectory,
                     @Nullable
                     String traceLogGroup)
        Configure the client trace directory and log group. If set, this will configure the native client to emit trace logs with important metrics and instrumentation. As this information is useful for monitoring FoundationDB client behavior, it is generally recommended that the user set this option in production environments.

        The logs will be placed in the directory on the local filesystem specified by the traceDirectory parameter. If the traceLogGroup is set to a non-null value, each log message will have a LogGroup field associated with it that is set to the parameter's value. This can be used to associate log messages from related processes together.

        This method should be called prior to the first time this factory is used to produce an FDBDatabase. The factory will configure the client in a manner consistent with the passed parameters the first time a database is needed, and subsequent calls to this method will have no effect.

        Parameters:
        traceDirectory - the directory in which to write trace log files or null to disable writing logs
        traceLogGroup - the value to set the log group field to in each message of null to set no group

      • setTraceFormat

        public void setTraceFormat​(@Nonnull
                           FDBTraceFormat traceFormat)
        Set the output format for the client trace logs. This only will have any effect if setTrace(String, String) is also called. If that method is called (i.e., if trace logs are enabled), then this will be used to configure what the output format of trace log files should be. See FDBTraceFormat for more details on what options are available.

        This method should be called prior to the first time this factory is used to produce an FDBDatabase. The factory will configure the client in a manner consistent with the passed parameters the first time a database is needed, and subsequent calls to this method will have no effect.

        Parameters:
        traceFormat - the output format for client trace logs
        See Also:
        setTrace(String, String), FDBTraceFormat

      • getDirectoryCacheSize

        public int getDirectoryCacheSize()

      • getTrackLastSeenVersion

        public boolean getTrackLastSeenVersion()

      • getDatacenterId

        public String getDatacenterId()

      • setDirectoryCacheSize

        public void setDirectoryCacheSize​(int directoryCacheSize)
        Sets the number of directory layer entries that will be cached for each database that is produced by the factory. Changing this value after databases have been created will result in each database having its existing entries discarded and the cache size adjusted to the provided value.

        Each FDBDatabase maintains a cache of entries that have been retrieved by any instance of a LocatableResolver using that database. Thus, this cache is shared across all resolvers (it should be noted entries in this cache are segregated by resolver and treated as distinct, ensuring that the value for a directory entry from one resolver will not be returned to another resolver even if they share the same key).

        Parameters:
        directoryCacheSize - the new directory cache size

      • setTrackLastSeenVersion

        public void setTrackLastSeenVersion​(boolean trackLastSeenVersion)

      • setDatacenterId

        public void setDatacenterId​(String datacenterId)

      • setRunLoopProfilingEnabled

        public void setRunLoopProfilingEnabled​(boolean runLoopProfilingEnabled)
        Set whether additional run-loop profiling of the FDB client is enabled. This can be useful for debugging certain performance problems, but the profiling is also fairly heavy-weight, and so it is not generally recommended when performance is critical. This method should be set prior to the first FDBDatabase is returned by this factory, as otherwise, it will have no effect (i.e., run-loop profiling will not actually be enabled). Enabling run-loop profiling also places its output in the FDB client trace logs, so it only makes sense to call this method if one also calls setTrace(String, String).
        Parameters:
        runLoopProfilingEnabled - whether run-loop profiling should be enabled
        See Also:
        NetworkOptions.setEnableSlowTaskProfiling()

      • isRunLoopProfilingEnabled

        public boolean isRunLoopProfilingEnabled()
        Get whether additional run-loop profiling has been been enabled.
        Returns:
        whether additional run-loop profiling has been enabled
        See Also:
        setRunLoopProfilingEnabled(boolean)

      • getMaxAttempts

        public int getMaxAttempts()
        Gets the maximum number of attempts for a database to make when running a retriable transactional operation. This is used by FDBDatabase.run() and FDBDatabase.runAsync() to limit the number of attempts that an operation is retried. The default value is 10.
        Returns:
        the maximum number of times to run a transactional database operation

      • setMaxAttempts

        public void setMaxAttempts​(int maxAttempts)
        Sets the maximum number of attempts for a database to make when running a retriable transactional operation. This is used by FDBDatabase.run() and FDBDatabase.runAsync() to limit the number of attempts that an operation is retried. The default value is 10.
        Parameters:
        maxAttempts - the maximum number of times to run a transactional database operation
        Throws:
        IllegalArgumentException - if a non-positive number is given

      • getMaxDelayMillis

        public long getMaxDelayMillis()
        Gets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabase.run() and FDBDatabase.runAsync() to limit the time spent between successive attempts at completing a database operation. The default value is 1000 so that there will not be more than 1 second between attempts.
        Returns:
        the maximum delay between attempts when retrying operations

      • setMaxDelayMillis

        public void setMaxDelayMillis​(long maxDelayMillis)
        Sets the maximum delay (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabase.run() and FDBDatabase.runAsync() to limit the time spent between successive attempts at completing a database operation. The default is 1000 so that there will not be more than 1 second between attempts.
        Parameters:
        maxDelayMillis - the maximum delay between attempts when retrying operations
        Throws:
        IllegalArgumentException - if the value is negative or less than the minimum delay

      • getInitialDelayMillis

        public long getInitialDelayMillis()
        Gets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabase.run() and FDBDatabase.runAsync() to determine how long to wait between the first and second attempts at running a database operation. The exponential backoff algorithm will choose an amount of time to wait between zero and the initial delay, and will use that value each successive iteration to determine how long that wait should be. The default value is 10 milliseconds.
        Returns:
        the delay ceiling between the first and second attempts at running a database operation

      • setInitialDelayMillis

        public void setInitialDelayMillis​(long initialDelayMillis)
        Sets the delay ceiling (in milliseconds) that will be applied between attempts to run a transactional database operation. This is used within FDBDatabase.run() and FDBDatabase.runAsync() to determine how long to wait between the first and second attempts at running a database operation. The exponential backoff algorithm will choose an amount of time to wait between zero and the initial delay, and will use that value each successive iteration to determine how long that wait should be. The default value is 10 milliseconds.
        Parameters:
        initialDelayMillis - the delay ceiling between the first and second attempts at running a database operation
        Throws:
        IllegalArgumentException - if the value is negative or greater than the maximum delay

      • setReverseDirectoryRowsPerTransaction

        public void setReverseDirectoryRowsPerTransaction​(int rowsPerTransaction)
        When a reverse directory lookup is performed from a FDBReverseDirectoryCache and an entry is not found in the cache and, thus, the directory layer must be scanned to find it, this property determines how many rows will be scanned within the context of a single transaction, before the transaction is closed and re-opened in order to avoid a past_version.
        Parameters:
        rowsPerTransaction - the number of rows to scan within the context of a single transaction

      • getReverseDirectoryRowsPerTransaction

        public int getReverseDirectoryRowsPerTransaction()

      • setReverseDirectoryMaxMillisPerTransaction

        public void setReverseDirectoryMaxMillisPerTransaction​(long millisPerTransaction)
        When a reverse directory lookup is performed from a FDBReverseDirectoryCache and an entry is not found in the cache and, thus, the directory layer must be scanned to find it, this property determines how many milliseconds may be spent scanning the cache within the context of a single transaction, before the transaction is closed and re-opened in order to avoid a past_version.
        Parameters:
        millisPerTransaction - the number of miliseconds to spend scanning

      • getReverseDirectoryMaxMillisPerTransaction

        public long getReverseDirectoryMaxMillisPerTransaction()

      • setTransactionIsTracedSupplier

        public void setTransactionIsTracedSupplier​(Supplier<Boolean> transactionIsTracedSupplier)
        Use transactionIsTracedSupplier to control whether a newly created transaction should be traced or not. Traced transactions are used to identify and profile unclosed transactions. In order to trace the source of a leaked transaction, it is necessary to capture a stack trace at the point the transaction is created which is a rather expensive operation, so this should either be disabled in a production environment or the supplier to return true for only a very small subset of transactions.
        Parameters:
        transactionIsTracedSupplier - a supplier which should return true for creating traced transactions

      • getTransactionIsTracedSupplier

        public Supplier<Boolean> getTransactionIsTracedSupplier()

      • getWarnAndCloseOpenContextsAfterSeconds

        public long getWarnAndCloseOpenContextsAfterSeconds()
        Get whether to warn and close record contexts open for too long.
        Returns:
        number of seconds after which a context and be closed and a warning logged

      • setWarnAndCloseOpenContextsAfterSeconds

        public void setWarnAndCloseOpenContextsAfterSeconds​(long warnAndCloseOpenContextsAfterSeconds)
        Set whether to warn and close record contexts open for too long.
        Parameters:
        warnAndCloseOpenContextsAfterSeconds - number of seconds after which a context and be closed and a warning logged

      • setBlockingInAsyncDetection

        public void setBlockingInAsyncDetection​(@Nonnull
                                        BlockingInAsyncDetection behavior)
        Controls if calls to FDBDatabase#asyncToSync(FDBStoreTimer, FDBStoreTimer.Wait, CompletableFuture) or FDBRecordContext#asyncToSync(FDBStoreTimer.Wait, CompletableFuture) will attempt to detect when they are being called from within an asynchronous context and how they should react to this fact when they are. Note that the process of performing this detection is quite expensive, so running with detection enabled in not recommended for environments other than testing.
        Parameters:
        behavior - the blocking desired blocking detection behavior (see BlockingInAsyncDetection)

      • setBlockingInAsyncDetection

        public void setBlockingInAsyncDetection​(@Nonnull
                                        Supplier<BlockingInAsyncDetection> supplier)
        Provides a supplier that controls if calls to FDBDatabase#asyncToSync(FDBStoreTimer, FDBStoreTimer.Wait, CompletableFuture) or FDBRecordContext#asyncToSync(FDBStoreTimer.Wait, CompletableFuture) will attempt to detect when they are being called from within an asynchronous context and how they should react to this fact when they are. Because such detection is quite expensive, it is suggested that it is either BlockingInAsyncDetection.DISABLED for anything other than testing environments or that the supplier randomly chooses a small sample rate in which detection should be enabled.
        Parameters:
        supplier - a supplier that produces the blocking desired blocking detection behavior (see BlockingInAsyncDetection)

      • setLatencyInjector

        public void setLatencyInjector​(@Nonnull
                               Function<FDBLatencySource,​Long> latencyInjector)
        Provides a function that computes a latency that should be injected into a specific FDB operation. The provided function takes a FDBLatencySource as input and returns the number of milliseconds delay that should be injected before the operation completes. Returning a value of zero or less indicates that no delay should be injected.

        Latency injection can be useful for simulating environments in which FDB is under stress or in a configuration in which latency is inherent in its operation.

        Parameters:
        latencyInjector - a function computing the latency to be injected into an operation

      • getLatencyInjector

        public Function<FDBLatencySource,​Long> getLatencyInjector()
        Returns the current latency injector.
        Returns:
        the current latency injector

      • clearLatencyInjector

        public void clearLatencyInjector()
        Removes any previously installed latency injector.

      • getStateRefreshTimeMillis

        public long getStateRefreshTimeMillis()

      • setStateRefreshTimeMillis

        public void setStateRefreshTimeMillis​(long stateRefreshTimeMillis)
        Set the refresh time for the cached LocatableResolver state. Defaults to 30 seconds.
        Parameters:
        stateRefreshTimeMillis - time to set, in milliseconds

      • setTransactionTimeoutMillis

        public void setTransactionTimeoutMillis​(long transactionTimeoutMillis)
        Set the transaction timeout time in milliseconds. Databases created by this factory will use this value when they create transactions. If the timeout is reached, the transaction will fail with an FDBExceptions.FDBStoreTransactionTimeoutException and will not be retried. Any outstanding work from the transaction will be cancelled, though the user should still close the FDBRecordContext to free any native memory used by the transaction.

        If set to DEFAULT_TR_TIMEOUT_MILLIS, then the transaction's timeout will default to the system default, which is the value set by DatabaseOptions.setTransactionTimeout(long). If that option is not set, then no timeout will be imposed on the transaction. Note also that this is the default value

        If set to UNLIMITED_TR_TIMEOUT_MILLIS, then the no timeout will be imposed on the transaction. This will override the system default if one is set.

        Parameters:
        transactionTimeoutMillis - the amount of time in milliseconds before a transaction should timeout

      • getLocalityProvider

        @Nonnull
public FDBLocalityProvider getLocalityProvider()
        Get the locality provider that is used to discover the server location of the keys.
        Returns:
        the installed locality provider

      • setLocalityProvider

        public void setLocalityProvider​(@Nonnull
                                FDBLocalityProvider localityProvider)
        Set the locality provider that is used to discover the server location of the keys.
        Parameters:
        localityProvider - the locality provider
        See Also:
        FDBLocalityUtil