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 Summary

Fields

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

Method Summary

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.

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:

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

DB_BEFORE	Database value before the transaction
DB_AFTER	Database value after the transaction
TX_DATA	Collection of Datoms produced by the transaction
TEMPIDS	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