public interface Connection
Modifier and Type | Field and Description |
---|---|
static java.lang.Object |
DB_AFTER |
static java.lang.Object |
DB_BEFORE |
static java.lang.Object |
TEMPIDS |
static java.lang.Object |
TX_DATA |
Modifier and Type | Method and Description |
---|---|
Database |
db()
Retrieves the current database value.
|
void |
gcStorage(java.util.Date olderThan)
Reclaim storage garbage older than a certain age.
|
Log |
log()
Retrieves the current value of the log.
|
void |
release()
Request the release of resources associated with this connection.
|
void |
removeTxReportQueue()
Removes the queue associated with this connection.
|
boolean |
requestIndex()
Request that a background indexing job begin immediately.
|
ListenableFuture<Database> |
sync()
Retrieve a database value that includes all transactions completed
at the time
sync was called. |
ListenableFuture<Database> |
sync(long t)
Retrieve a database value that includes all transactions completed
up to and including time t.
|
ListenableFuture<Database> |
syncExcise(long t)
Retrieve a database value that is aware of all
excisions up to
a database t.
|
ListenableFuture<Database> |
syncIndex(long t)
Retrieve a database value that is indexed
through the database t passed in.
|
ListenableFuture<Database> |
syncSchema(long t)
Retrieve a database value that is aware of
all schema changes
up to a database t.
|
ListenableFuture<java.util.Map> |
transact(java.util.List txData)
Submits a transaction,
blocking until a result is available.
|
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. |
java.util.concurrent.BlockingQueue<java.util.Map> |
txReportQueue()
Gets the single transaction report queue associated with this connection, creating it if necessary.
|
static final java.lang.Object DB_BEFORE
static final java.lang.Object DB_AFTER
static final java.lang.Object TX_DATA
static final java.lang.Object TEMPIDS
boolean requestIndex()
Request that a background indexing job begin immediately.
Background indexing will happen asynchronously. You can track indexing completion withsyncIndex(long)
.Database db()
Log log()
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
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.
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.
t
- a database t.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.t
- a database t.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.t
- a database t.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.t
- a database t.ListenableFuture<java.util.Map> transact(java.util.List txData)
Submits a transaction, blocking until a result is available.
txData
- a list of data to be added, containing any combination
of assertions,
retractions,
transaction functions,
or entity maps:
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 ...} |
DB_BEFORE |
Database value before the transaction |
DB_AFTER |
Database value after the transaction |
TX_DATA |
Collection of Datom s produced by the transaction |
TEMPIDS |
Use with Peer.resolveTempid(datomic.Database, java.lang.Object, java.lang.Object) to resolve temporary ids. |
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).ListenableFuture
ListenableFuture<java.util.Map> transactAsync(java.util.List txData)
transact(java.util.List)
, but returns immediately, with
timeout logic left up to the caller.txData
- see transact
transact
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 bytransact(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.void removeTxReportQueue()
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 togcStorage
.olderThan
- limits how recent garbage may be collectedvoid 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.