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 Details

    • DB_BEFORE

      static final Object DB_BEFORE

    • DB_AFTER

      static final Object DB_AFTER

    • TX_DATA

      static final Object TX_DATA

    • TEMPIDS

      static final Object TEMPIDS

  • Method Details

    • 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<Map> transact(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:

    • transactAsync

      ListenableFuture<Map> transactAsync(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

      BlockingQueue<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(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