Package datomic

Interface Connection


  • public interface Connection
    A connection to a database for submitting and monitoring transactions, and retrieving the current value of the database.
    • Field Detail

      • DB_BEFORE

        static final java.lang.Object DB_BEFORE
      • DB_AFTER

        static final java.lang.Object DB_AFTER
      • TX_DATA

        static final java.lang.Object TX_DATA
      • TEMPIDS

        static final java.lang.Object TEMPIDS
    • Method Detail

      • requestIndex

        boolean requestIndex()

        Request that a background indexing job begin immediately.

        Background indexing will happen asynchronously. You can track indexing completion with syncIndex(long).
        Returns:
        true if indexing job successfully scheduled.
      • db

        Database db()
        Retrieves the current database value. Does not communicate with the transactor, nor block.
        Returns:
        an immutable database value.
      • log

        Log log()
        Retrieves the current value of the log. Does not communicate with the transactor, nor block.
        Returns:
        an immutable log value
        Since:
        0.8.4122
      • sync

        ListenableFuture<Database> sync()

        Retrieve a database value that includes all transactions completed at the time sync was called.

        sync is a primitive for coordinating activity across peer processes. sync always communicates with the transactor, and should only be used when the following two conditions hold
        1. coordination is required
        2. peers have no way to agree on a basis t for coordination
        If you do not require coordination, prefer db(). If peers can share a known basis t, prefer sync(long).

        The future returned by sync can take arbitrarily long to complete. Waiters should specify a timeout.

        Returns:
        a database future.
        Since:
        0.8.3993
      • sync

        ListenableFuture<Database> sync​(long t)

        Retrieve a database value that includes all transactions completed up to and including time t.

        sync is a primitive for coordinating activity across peer processes. sync does not communicate with the transactor, but it can block if the peer has not yet been notified of transactions up to time t. If you do not require coordination, prefer db(). If peers do not share a basis t, prefer sync().

        The future returned by sync can take arbitrarily long to complete. Waiters should specify a timeout.

        Parameters:
        t - a database t.
        Returns:
        a database future.
        Since:
        0.8.3993
      • syncIndex

        ListenableFuture<Database> syncIndex​(long t)

        Retrieve a database value that is indexed through the database t passed in.

        Does not communicate with the transactor, so the future may be available immediately. The future can take arbitrarily long to complete. Waiters should specify a timeout.
        Parameters:
        t - a database t.
        Returns:
        a database future.
        Since:
        0.9.4470
      • syncSchema

        ListenableFuture<Database> syncSchema​(long t)

        Retrieve a database value that is aware of all schema changes up to a database t.

        Does not communicate with the transactor, so the future may be available immediately. The future can take arbitrarily long to complete. Waiters should specify a timeout.
        Parameters:
        t - a database t.
        Returns:
        a database future.
        Since:
        0.9.4470
      • syncExcise

        ListenableFuture<Database> syncExcise​(long t)

        Retrieve a database value that is aware of all excisions up to a database t.

        Does not communicate with the transactor, so the future may be available immediately. The future can take arbitrarily long to complete. Waiters should specify a timeout.
        Parameters:
        t - a database t.
        Returns:
        a database future.
        Since:
        0.9.4470
      • transact

        ListenableFuture<java.util.Map> transact​(java.util.List txData)

        Submits a transaction, blocking until a result is available.

        Parameters:
        txData - a list of data to be added, containing any combination of assertions, retractions, transaction functions, or entity maps:
        Transaction data items
        Type Example
        assertion [:db/add some-id :some-attr/name "Some attr value"]
        retraction [:db/retract some-id :some-attr/name "Some attr value"]
        transaction function [:some/fn-name args-for-fn ...]
        entity map {:db/id some-id :some-attr/name "some value" :another-attr/name 42 ...}
        Returns:

        a future that can be used to monitor the completion of the transaction. If the transaction commits, the future's value is a map, with the following keys:

        Transaction return keys
        DB_BEFORE Database value before the transaction
        DB_AFTER Database value after the transaction
        TX_DATA Collection of Datoms produced by the transaction
        TEMPID Use with Peer.resolveTempid(datomic.Database, java.lang.Object, java.lang.Object) to resolve temporary ids.

        If the transaction aborts, attempts to get the future's value throw an ExecutionException, wrapping a Error containing error information. If the transaction times out, the call to transact itself will throw a RuntimeException. The transaction timeout can be set via the system property datomic.txTimeoutMsec, and defaults to 10000 (10 seconds).

        See Also:
        ListenableFuture
      • transactAsync

        ListenableFuture<java.util.Map> transactAsync​(java.util.List txData)
        Like transact(java.util.List), but returns immediately, with timeout logic left up to the caller.
        Parameters:
        txData - see transact
        Returns:
        see transact
      • txReportQueue

        java.util.concurrent.BlockingQueue<java.util.Map> txReportQueue()

        Gets the single transaction report queue associated with this connection, creating it if necessary.

        The transaction report queue receives reports from all transactions in the system. Objects on the queue have the same keys as returned by transact(java.util.List). The returned queue may be consumed from more than one thread. Note that the returned queue does not block producers, and will consume memory until you consume the elements from it. Reports will be added to the queue at some point after the db has been updated If this connection originated the transaction, the transaction future will be notified first, before a report is placed on the queue.
        Returns:
        a queue
      • removeTxReportQueue

        void removeTxReportQueue()
        Removes the queue associated with this connection.
      • gcStorage

        void gcStorage​(java.util.Date olderThan)

        Reclaim storage garbage older than a certain age.

        As part of capacity planning for a Datomic system, you should schedule regular (e.g daily, weekly) calls to gcStorage.
        Parameters:
        olderThan - limits how recent garbage may be collected
      • release

        void release()

        Request the release of resources associated with this connection.

        Method returns immediately, resources will be released asynchronously. This method should only be called when the entire process is no longer interested in the connection. Note that Datomic connections do not adhere to an acquire/use/release pattern. They are thread-safe, cached, and long lived. Many processes (e.g. application servers) will never call release.
        Since:
        0.8.3861