- All Known Subinterfaces:
Dataset
,DatasetGraph
,DatasetGraphBuffering
,DatasetGraphWrapperView
,TransactionalNotSupportedMixin
,TransactionalTrait
- All Known Implementing Classes:
BufferingDatasetGraph
,DatasetGraphBase
,DatasetGraphBaseFind
,DatasetGraphCollection
,DatasetGraphFilteredView
,DatasetGraphInMemory
,DatasetGraphMap
,DatasetGraphMapLink
,DatasetGraphNull
,DatasetGraphOne
,DatasetGraphQuads
,DatasetGraphRDFS
,DatasetGraphReadOnly
,DatasetGraphSink
,DatasetGraphTriplesQuads
,DatasetGraphWrapper
,DatasetGraphZero
,DatasetImpl
,DifferenceDatasetGraph
,DyadicDatasetGraph
,DynamicDatasets.DynamicDatasetGraph
,GraphTxn
,IntersectionDatasetGraph
,TransactionalLock
,TransactionalNotSupported
,TransactionalNull
,TxnCounter
,TxnDataset2Graph
,UnionDatasetGraph
The read lifecycle is:
begin(READ) ... end()
commit
and abort
are allowed.
The write lifecycle is:
begin(WRITE) ... abort() or commit() end()
end()
is optional for "write" but is preferred.
Application use
Applications can conveniently execute the lifecycle with methods to read or write:dataset.executeRead(()-> { ... sparql query ... });
dataset.executeWrite(()-> { ... sparql update ... });
Use one of calculateRead
or calculateWrite
to return a value for the transaction block.
Core Functionality
Directly called, code might look like:Transactional object = ... object.begin(TxnMode.READ) ; try { ... actions inside a read transaction ... } finally { object.end() ; }
or
Transactional object = ...
object.begin(TxnMode.WRITE) ;
try {
... actions inside a write transaction ...
object.commit() ;
} finally {
// This causes an abort if commit
has not been called.
object.end() ;
}
- See Also:
-
Nested Class Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
abort()
Abort a transaction - finish the transaction and undo any changes (if a "write" transaction)default void
begin()
Start a transaction which is READ mode and which will switch to WRITE if an update is attempted but only if no intermediate transaction has performed an update.default void
Start either a READ or WRITE transaction.void
Start a transaction.
READ or WRITE transactions start in that state and do not change for the lifetime of the transaction.default <T> T
Execute and return a value in a transaction with the giventransaction type
.default <X> X
Execute in a "read" transaction that can promote to "write" and return some calculated value.default <X> X
calculateRead
(Supplier<X> r) Execute and return a value in a read transactiondefault <X> X
calculateWrite
(Supplier<X> r) Execute and return a value in a write transaction.void
commit()
Commit a transaction - finish the transaction and make any changes permanent (if a "write" transaction)void
end()
Finish the transaction - if a write transaction and commit() has not been called, then abortdefault void
Execute application code in a transaction with the giventransaction type
.default void
Execute in a "read" transaction that can promote to "write".default <T extends Transactional>
voidExecute in a read transactiondefault void
Execute the Runnable in a write transactionboolean
Say whether inside a transaction.default boolean
promote()
Attempt to promote a transaction from "read" to "write" when the transaction started with a "promote" mode (READ_PROMOTE
orREAD_COMMITTED_PROMOTE
).boolean
promote
(Transactional.Promote mode) Attempt to promote a transaction from "read" mode to "write" and the transaction.Return the current mode of the transaction - "read" or "write".Return the transaction type used inbegin(TxnType)
.
-
Method Details
-
begin
default void begin()Start a transaction which is READ mode and which will switch to WRITE if an update is attempted but only if no intermediate transaction has performed an update.See
begin(TxnType)
for more details an options.May not be implemented. See
begin(ReadWrite)
is guaranteed to be provided. -
begin
Start a transaction.
READ or WRITE transactions start in that state and do not change for the lifetime of the transaction.WRITE
: this guarantees a WRITE will complete ifcommit()
is called. The same asbegin(ReadWrite.WRITE)
.READ
: the transaction can not promote to WRITE,ensuring read-only access to the data. The same asbegin(ReadWrite.READ)
.READ_PROMOTE
: the transaction will go from "read" to "write" if an update is attempted and if the dataset has not been changed by another write transaction. See alsopromote()
.READ_COMMITTED_PROMOTE
: Use this with care. The promotion will succeed but changes from other transactions become visible.
begin
). IfREAD_PROMOTE
, the dataset must not have changed; ifREAD_COMMITTED_PROMOTE
any intermediate changes are visible but the application can not assume any data it has read in the transaction is the same as it was at the point the transaction started.This operation is optional and some implementations may throw a
JenaTransactionException
exception for some or allTxnType
values.See
begin(ReadWrite)
for a form that is required of implementations. -
begin
Start either a READ or WRITE transaction. -
promote
default boolean promote()Attempt to promote a transaction from "read" to "write" when the transaction started with a "promote" mode (READ_PROMOTE
orREAD_COMMITTED_PROMOTE
).Returns "true" if the transaction is in write mode after the call. The method always succeeds of the transaction is already "write".
A
READ_COMMITTED_PROMOTE
can always be promoted, but the call may need to wait.This method returns true if a
READ_PROMOTE
orREAD_COMMITTED_PROMOTE
is promoted.This method returns false if a
READ_PROMOTE
can't be promoted - the transaction is still valid and in "read" mode. Any further calls topromote()
will also return false.This method returns false if there is an attempt to promote a "READ" transaction.
-
promote
Attempt to promote a transaction from "read" mode to "write" and the transaction. This method allows the form of promotion to be specified. The transaction must not have been started withREAD
, which is read-only.An argument of
READ_PROMOTE
treats the promotion as if the transaction was started withREAD_PROMOTE
(any other writer commiting since the transaction started blocks promotion) andREAD_COMMITTED_PROMOTE
treats the promotion as if the transaction was started withREAD_COMMITTED_PROMOTE
(intemediate writer commits become visible).Returns "true" if the transaction is in write mode after the call. The method always succeeds of the transaction is already "write".
This method returns true if a
READ_PROMOTE
orREAD_COMMITTED_PROMOTE
is promoted.This method returns false if a
READ_PROMOTE
can't be promoted - the transaction is still valid and in "read" mode.This method throws an exception if there is an attempt to promote a
READ
transaction. -
commit
void commit()Commit a transaction - finish the transaction and make any changes permanent (if a "write" transaction) -
abort
void abort()Abort a transaction - finish the transaction and undo any changes (if a "write" transaction) -
end
void end()Finish the transaction - if a write transaction and commit() has not been called, then abort -
transactionMode
ReadWrite transactionMode()Return the current mode of the transaction - "read" or "write". If the caller is not in a transaction, this method returns null. -
transactionType
TxnType transactionType()Return the transaction type used inbegin(TxnType)
. If the caller is not in a transaction, this method returns null. -
isInTransaction
boolean isInTransaction()Say whether inside a transaction. -
exec
Execute application code in a transaction with the giventransaction type
. SeeTxn.exec(T, org.apache.jena.query.TxnType, java.lang.Runnable)
. -
calc
Execute and return a value in a transaction with the giventransaction type
. SeeTxn.calc(T, org.apache.jena.query.TxnType, java.util.function.Supplier<X>)
. -
execute
Execute in a "read" transaction that can promote to "write".Such a transaction may abort if an update is executed by another thread before this one is promoted to "write" mode. If so, the data protected by
txn
is unchanged.If the application knows updates will be needed, consider using
executeWrite(java.lang.Runnable)
which starts in "write" mode.The application code can call
promote()
to attempt to change from "read" to "write"; thepromote
method returns a boolean indicating whether the promotion was possible or not. -
calculate
Execute in a "read" transaction that can promote to "write" and return some calculated value.Such a transaction may abort if an update is executed by another thread before this one is promoted to "write" mode. If so, the data protected by
txn
is unchanged.If the application knows updates will be needed, consider using
executeWrite(java.lang.Runnable)
which starts in "write" mode.The application code can call
promote()
to attempt to change from "read" to "write"; thepromote
method returns a boolean indicating whether the promotion was possible or not. -
executeRead
Execute in a read transaction -
calculateRead
Execute and return a value in a read transaction -
executeWrite
Execute the Runnable in a write transaction -
calculateWrite
Execute and return a value in a write transaction.
-