jetbrains.exodus.entitystore

Interface StoreTransaction

public interface StoreTransaction

StoreTransaction is a transaction started against EntityStore using EntityStore.beginTransaction() or EntityStore.beginReadonlyTransaction() methods. It's being implicitly created in PersistentEntityStore.executeInTransaction(StoreTransactionalExecutable), PersistentEntityStore.executeInReadonlyTransaction(StoreTransactionalExecutable), PersistentEntityStore.computeInTransaction(StoreTransactionalComputable) and PersistentEntityStore.computeInReadonlyTransaction(StoreTransactionalComputable) methods, and it's being passed as a parameter to StoreTransactionalExecutable and StoreTransactionalComputable functions.

StoreTransaction is used to create new entities and query entity iterables.

See Also:

EntityStore.beginTransaction(), EntityStore.beginReadonlyTransaction(), StoreTransactionalExecutable, StoreTransactionalComputable, PersistentEntityStore.executeInTransaction(StoreTransactionalExecutable), PersistentEntityStore.executeInReadonlyTransaction(StoreTransactionalExecutable), PersistentEntityStore.computeInTransaction(StoreTransactionalComputable), PersistentEntityStore.computeInReadonlyTransaction(StoreTransactionalComputable), Entity, EntityIterable

Method Summary

Modifier and Type	Method and Description
void	abort() Ignores all changes and finishes the StoreTransaction.
boolean	commit() Tries to commits all changes and finish the StoreTransaction.
@NotNull EntityIterable	find(@NotNull java.lang.String entityType, @NotNull java.lang.String propertyName, @NotNull java.lang.Comparable value) Returns EntityIterable with entities of specified type with specified property equal to specified value.
@NotNull EntityIterable	find(@NotNull java.lang.String entityType, @NotNull java.lang.String propertyName, @NotNull java.lang.Comparable minValue, @NotNull java.lang.Comparable maxValue) Returns EntityIterable with entities of specified type with specified property equal to a value in specified range [minValue, maxValue].
@NotNull EntityIterable	findIds(@NotNull java.lang.String entityType, long minValue, long maxValue) Returns EntityIterable with entities of specified type with ids having their local ids in specified range [minValue, maxValue].
@NotNull EntityIterable	findLinks(@NotNull java.lang.String entityType, @NotNull EntityIterable entities, @NotNull java.lang.String linkName) Returns EntityIterable with entities of specified type which are linked to an entity in the specified entity set by specified link.
@NotNull EntityIterable	findLinks(@NotNull java.lang.String entityType, @NotNull Entity entity, @NotNull java.lang.String linkName) Returns EntityIterable with entities of specified type which are linked to specified entity by specified link.
@NotNull EntityIterable	findStartingWith(@NotNull java.lang.String entityType, @NotNull java.lang.String propertyName, @NotNull java.lang.String value) Returns EntityIterable with entities of specified type which have String values of specified property starting with specified value.
@NotNull EntityIterable	findWithBlob(@NotNull java.lang.String entityType, @NotNull java.lang.String blobName) Returns EntityIterable with entities of specified type which have not-null blob values with specified name.
@NotNull EntityIterable	findWithLinks(@NotNull java.lang.String entityType, @NotNull java.lang.String linkName) Returns EntityIterable with entities of specified type which have links with specified name.
@NotNull EntityIterable	findWithLinks(@NotNull java.lang.String entityType, @NotNull java.lang.String linkName, @NotNull java.lang.String oppositeEntityType, @NotNull java.lang.String oppositeLinkName) Returns the same EntityIterable as findWithLinks(String, String) does, but faster if extra indices are available in the database.
@NotNull EntityIterable	findWithProp(@NotNull java.lang.String entityType, @NotNull java.lang.String propertyName) Returns EntityIterable with entities of specified type which have not-null property values with specified name.
boolean	flush() Tries to flush all changes without finishing the StoreTransaction.
@NotNull EntityIterable	getAll(@NotNull java.lang.String entityType) Gets all entities of specified type.
@NotNull Entity	getEntity(@NotNull EntityId id) Loads up-to-date version of entity by its EntityId if it exists in the database.
@NotNull java.util.List<java.lang.String>	getEntityTypes() Returns all entity types available in the EntityStore.
@Nullable QueryCancellingPolicy	getQueryCancellingPolicy()
@NotNull Sequence	getSequence(@NotNull java.lang.String sequenceName) Returns existing or creates the new named Sequence.
@NotNull EntityIterable	getSingletonIterable(@NotNull Entity entity) Returns singleton EntityIterable with the single specified Entity.
StoreTransaction	getSnapshot() Gets read-only StoreTransaction that holds snapshot of this StoreTransaction.
@NotNull EntityStore	getStore() Returns the EntityStore instance which the StoreTransaction is started against.
boolean	isFinished()
boolean	isIdempotent() Idempotent transaction changes nothing in database.
boolean	isReadonly()
@NotNull EntityIterable	mergeSorted(@NotNull java.util.List<EntityIterable> sorted, @NotNull java.util.Comparator<Entity> comparator) Deprecated.
@NotNull Entity	newEntity(@NotNull java.lang.String entityType) Creates new Entity of specified type.
void	revert() Reverts all changes without finishing the StoreTransaction.
void	saveEntity(@NotNull Entity entity) Saves new Entity which earlier was created by newEntity(String) but StoreTransaction failed to flush() or commit().
void	setQueryCancellingPolicy(QueryCancellingPolicy policy) Sets a query cancelling policy for the StoreTransaction.
@NotNull EntityIterable	sort(@NotNull java.lang.String entityType, @NotNull java.lang.String propertyName, boolean ascending) Returns EntityIterable with entities of specified type sorted by values of specified property.
@NotNull EntityIterable	sort(@NotNull java.lang.String entityType, @NotNull java.lang.String propertyName, @NotNull EntityIterable rightOrder, boolean ascending) Returns EntityIterable with entities of specified type from rightOrder sorted by values of specified property.
@NotNull EntityIterable	sortLinks(@NotNull java.lang.String entityType, @NotNull EntityIterable sortedLinks, boolean isMultiple, @NotNull java.lang.String linkName, @NotNull EntityIterable rightOrder) Returns EntityIterable with entities of specified type from rightOrder sorted by links with specified name.
@NotNull EntityIterable	sortLinks(@NotNull java.lang.String entityType, @NotNull EntityIterable sortedLinks, boolean isMultiple, @NotNull java.lang.String linkName, @NotNull EntityIterable rightOrder, @NotNull java.lang.String oppositeEntityType, @NotNull java.lang.String oppositeLinkName) Returns the same EntityIterable as sortLinks(String, EntityIterable, boolean, String, EntityIterable) does, but faster if extra indices are available in the database.
@NotNull EntityId	toEntityId(@NotNull java.lang.String representation) Parses string representation of an entity id and returns corresponding EntityId instance.

Method Detail

getStore

@NotNull
@NotNull EntityStore getStore()

Returns the EntityStore instance which the StoreTransaction is started against. For out-of-the-box implementations of StoreTransaction, it always returns the PersistentEntityStore instance.

Returns:

EntityStore instance

isIdempotent

boolean isIdempotent()

Idempotent transaction changes nothing in database. It doesn't matter whether you flush it or revert, commit or abort. Result will be the same - nothing will be added, modified or deleted. Flushing idempotent transaction is trivial, flush() just does nothing and returns true. Each newly created transaction is idempotent.

Returns:

true if transaction is idempotent

See Also:

flush(), commit()

isReadonly

boolean isReadonly()

Returns:

true if the transaction is read-only

isFinished

boolean isFinished()

Returns:

true if the transaction is finished, committed or aborted

See Also:

commit(), abort()

commit

boolean commit()

Tries to commits all changes and finish the StoreTransaction. If the method succeed, it returns true. Use abort() method to finish transaction ignoring changes.

Typical pattern for committing changes can look like this:

 final StoreTransaction transaction = entityStore.beginTransaction();
 while(true) {
     try {
         // do your changes here
     } catch(Throwable t) {
         transaction.abort();
         throw ExodusException.toRuntime(t);
     }
     if (transaction.commit()) {
         break;
     }
 }
 

Returns:

true if the StoreTransaction is committed

See Also:

flush(), abort(), revert()

abort

void abort()

Ignores all changes and finishes the StoreTransaction.

Typical pattern for committing changes (abort() is called in catch block) can look like this:

 final StoreTransaction transaction = entityStore.beginTransaction();
 while(true) {
     try {
         // do your changes here
     } catch(Throwable t) {
         transaction.abort();
         throw ExodusException.toRuntime(t);
     }
     if (transaction.commit()) {
         break;
     }
 }
 

See Also:

commit(), flush(), revert()

flush

boolean flush()

Tries to flush all changes without finishing the StoreTransaction. If the method succeed, it returns true. After successful flush, the StoreTransaction moves to the latest database snapshot.

Typical pattern for flushing changes can look like this:

     final StoreTransaction transaction = entityStore.beginTransaction();
     while(true) {
         try {
             // do your changes here
         } catch(Throwable t) {
             transaction.abort();
             throw ExodusException.toRuntime(t);
         }
         if (transaction.flush()) {
             break;
         }
     }
     // here continue working with transaction
 

See Also:

commit(), abort(), revert()

revert

void revert()

Reverts all changes without finishing the StoreTransaction. After revert, the StoreTransaction moves to the latest database snapshot.

See Also:

commit(), abort(), flush()

getSnapshot

StoreTransaction getSnapshot()

Gets read-only StoreTransaction that holds snapshot of this StoreTransaction.

newEntity

@NotNull
@NotNull Entity newEntity(@NotNull
                                    @NotNull java.lang.String entityType)

Creates new Entity of specified type. Created entity gets its unique EntityId.

Parameters:

entityType - entity type

Returns:

new Entity instance

See Also:

saveEntity(Entity), Entity, EntityId

saveEntity

void saveEntity(@NotNull
                @NotNull Entity entity)

Saves new Entity which earlier was created by newEntity(String) but StoreTransaction failed to flush() or commit().

 final Entity user = txn.newEntity("User"|;
 if (!txn.flush()) {
     // if flush didn't succeed you don't need to create one more new entity since user has already got its
     // unique id, and it is enough to save it against the new database snapshot
     txn.saveEntity(user);
     // ...
 }
 

Parameters:

entity - entity earlier returned by newEntity(String)

See Also:

newEntity(String), Entity, EntityId

getEntity

@NotNull
@NotNull Entity getEntity(@NotNull
                                    @NotNull EntityId id)

Loads up-to-date version of entity by its EntityId if it exists in the database. No properties and links are loaded with the entity.

Parameters:

id - unique EntityId

Returns:

entity instance

Throws:

EntityRemovedInDatabaseException - if no entity exists with specified unique id

See Also:

EntityId

getEntityTypes

@NotNull
@NotNull java.util.List<java.lang.String> getEntityTypes()

Returns all entity types available in the EntityStore.

Returns:

list of entity types

See Also:

EntityStore

getAll

@NotNull
@NotNull EntityIterable getAll(@NotNull
                                         @NotNull java.lang.String entityType)

Gets all entities of specified type.

Parameters:

entityType - entity type

Returns:

EntityIterable instance

See Also:

EntityIterable

getSingletonIterable

@NotNull
@NotNull EntityIterable getSingletonIterable(@NotNull
                                                       @NotNull Entity entity)

Returns singleton EntityIterable with the single specified Entity.

Parameters:

entity - entity

Returns:

EntityIterable instance

See Also:

EntityIterable, Entity

find

@NotNull
@NotNull EntityIterable find(@NotNull
                                       @NotNull java.lang.String entityType,
                                       @NotNull
                                       @NotNull java.lang.String propertyName,
                                       @NotNull
                                       @NotNull java.lang.Comparable value)

Returns EntityIterable with entities of specified type with specified property equal to specified value.

Parameters:

entityType - entity type

propertyName - name of the property to search for

value - value of the property to search for

Returns:

EntityIterable instance

See Also:

EntityIterable

find

@NotNull
@NotNull EntityIterable find(@NotNull
                                       @NotNull java.lang.String entityType,
                                       @NotNull
                                       @NotNull java.lang.String propertyName,
                                       @NotNull
                                       @NotNull java.lang.Comparable minValue,
                                       @NotNull
                                       @NotNull java.lang.Comparable maxValue)

Returns EntityIterable with entities of specified type with specified property equal to a value in specified range [minValue, maxValue].

Parameters:

entityType - entity type

propertyName - name of the property to search for

minValue - minimum value of the property (inclusively, >=).

maxValue - maximum value of the property (inclusively <=).

Returns:

EntityIterable instance

See Also:

EntityIterable

findStartingWith

@NotNull
@NotNull EntityIterable findStartingWith(@NotNull
                                                   @NotNull java.lang.String entityType,
                                                   @NotNull
                                                   @NotNull java.lang.String propertyName,
                                                   @NotNull
                                                   @NotNull java.lang.String value)

Returns EntityIterable with entities of specified type which have String values of specified property starting with specified value.

Parameters:

entityType - entity type

propertyName - name of the property to search for

value - String value which searched properties are starting with

Returns:

EntityIterable instance

See Also:

EntityIterable

findIds

@NotNull
@NotNull EntityIterable findIds(@NotNull
                                          @NotNull java.lang.String entityType,
                                          long minValue,
                                          long maxValue)

Returns EntityIterable with entities of specified type with ids having their local ids in specified range [minValue, maxValue].

Parameters:

entityType - entity type

minValue - minimum value of EntityId.getLocalId() amongst all returned entities

maxValue - maximum value of EntityId.getLocalId() amongst all returned entities

Returns:

EntityIterable instance

See Also:

EntityIterable, EntityId

findWithProp

@NotNull
@NotNull EntityIterable findWithProp(@NotNull
                                               @NotNull java.lang.String entityType,
                                               @NotNull
                                               @NotNull java.lang.String propertyName)

Returns EntityIterable with entities of specified type which have not-null property values with specified name.

Parameters:

entityType - entity type

propertyName - property name

Returns:

EntityIterable instance

See Also:

EntityIterable

findWithBlob

@NotNull
@NotNull EntityIterable findWithBlob(@NotNull
                                               @NotNull java.lang.String entityType,
                                               @NotNull
                                               @NotNull java.lang.String blobName)

Returns EntityIterable with entities of specified type which have not-null blob values with specified name.

Parameters:

entityType - entity type

blobName - blob name

Returns:

EntityIterable instance

See Also:

EntityIterable

findLinks

@NotNull
@NotNull EntityIterable findLinks(@NotNull
                                            @NotNull java.lang.String entityType,
                                            @NotNull
                                            @NotNull Entity entity,
                                            @NotNull
                                            @NotNull java.lang.String linkName)

Returns EntityIterable with entities of specified type which are linked to specified entity by specified link.

Parameters:

entityType - entity type

entity - entity which resulting entities are linked to

linkName - link name to search for

Returns:

EntityIterable instance

See Also:

EntityIterable

findLinks

@NotNull
@NotNull EntityIterable findLinks(@NotNull
                                            @NotNull java.lang.String entityType,
                                            @NotNull
                                            @NotNull EntityIterable entities,
                                            @NotNull
                                            @NotNull java.lang.String linkName)

Returns EntityIterable with entities of specified type which are linked to an entity in the specified entity set by specified link.

Parameters:

entityType - entity type

entities - entity set which entities from resulting EntityIterable are linked to (each resulting entity is linked to at least to one entity from the set)

linkName - link name to search for

Returns:

EntityIterable instance

See Also:

EntityIterable

findWithLinks

@NotNull
@NotNull EntityIterable findWithLinks(@NotNull
                                                @NotNull java.lang.String entityType,
                                                @NotNull
                                                @NotNull java.lang.String linkName)

Returns EntityIterable with entities of specified type which have links with specified name.

Parameters:

entityType - entity type

linkName - link name

Returns:

EntityIterable instance

See Also:

EntityIterable

findWithLinks

@NotNull
@NotNull EntityIterable findWithLinks(@NotNull
                                                @NotNull java.lang.String entityType,
                                                @NotNull
                                                @NotNull java.lang.String linkName,
                                                @NotNull
                                                @NotNull java.lang.String oppositeEntityType,
                                                @NotNull
                                                @NotNull java.lang.String oppositeLinkName)

Returns the same EntityIterable as findWithLinks(String, String) does, but faster if extra indices are available in the database.

This method can be used in the following case. Let t1 be an Entity of the "T1" type and t2 - an Entity of the "T2" type. If they are mutually linked so that t1.getLink("linkName") == t2 and t2.getLink("oppositeLinkName") == t1, then it worth to use this method.

Parameters:

entityType - entity type ("T1")

linkName - link name

oppositeEntityType - opposite entity type ("T@")

oppositeLinkName - opposite link name

Returns:

EntityIterable instance

See Also:

EntityIterable

sort

@NotNull
@NotNull EntityIterable sort(@NotNull
                                       @NotNull java.lang.String entityType,
                                       @NotNull
                                       @NotNull java.lang.String propertyName,
                                       boolean ascending)

Returns EntityIterable with entities of specified type sorted by values of specified property.

Parameters:

entityType - entity type

propertyName - property name

ascending - true is sorting order is ascending

Returns:

EntityIterable instance

See Also:

sort(String, String, EntityIterable, boolean), sortLinks(String, EntityIterable, boolean, String, EntityIterable), sortLinks(String, EntityIterable, boolean, String, EntityIterable, String, String), mergeSorted(List, Comparator), EntityIterable, EntityIterable.isSortResult(), EntityIterable.asSortResult()

sort

@NotNull
@NotNull EntityIterable sort(@NotNull
                                       @NotNull java.lang.String entityType,
                                       @NotNull
                                       @NotNull java.lang.String propertyName,
                                       @NotNull
                                       @NotNull EntityIterable rightOrder,
                                       boolean ascending)

Returns EntityIterable with entities of specified type from rightOrder sorted by values of specified property. Stable sort is used if rightOrder is is sort result.

Parameters:

entityType - entity type

propertyName - property name

rightOrder - EntityIterable to sort by

ascending - true is sorting order is ascending

Returns:

EntityIterable instance

See Also:

sort(String, String, boolean), sortLinks(String, EntityIterable, boolean, String, EntityIterable), sortLinks(String, EntityIterable, boolean, String, EntityIterable, String, String), mergeSorted(List, Comparator), EntityIterable, EntityIterable.isSortResult(), EntityIterable.asSortResult()

sortLinks

@NotNull
@NotNull EntityIterable sortLinks(@NotNull
                                            @NotNull java.lang.String entityType,
                                            @NotNull
                                            @NotNull EntityIterable sortedLinks,
                                            boolean isMultiple,
                                            @NotNull
                                            @NotNull java.lang.String linkName,
                                            @NotNull
                                            @NotNull EntityIterable rightOrder)

Returns EntityIterable with entities of specified type from rightOrder sorted by links with specified name. Order of links is defined by the sortedLinks iterable.

 // creation of user
 final Entity user = txn.newEntity("User"); // entityType is "User"
 user.setProperty("login", ...);
 user.setProperty("password", ...);
 user.setProperty("fullName", ...);
 final Entity emailAccount = txn.newEntity("EmailAccount");
 emailAccount.setProperty("email", ...);
 user.addLink("emailAccount", emailAccount); // linkName is "emailAccount"
 // and so on
 // ...
 // given we have some EntityIterable users, sorting users by e-mail looks like this:
 final EntityIterable linkedEmails = users.selectManyDistinct("emailAccount");
 // linked email accounts sorted by email:
 final EntityIterable sortedLinks = txn.sort("EmailAccount", "email", linkedEmails, true);
 // and finally, given users sorted by email:
 final EntityIterable result = txn.sortLinks("User",
                             sortedLinks,
                             true,  // link "emailAccount" is multiple since user can have more than one account
                             "emailAccount",
                             users);
 

Parameters:

entityType - entity type

sortedLinks - some custom order of links

isMultiple - true if the link is multiple

linkName - link name

rightOrder - EntityIterable to sort by

Returns:

EntityIterable instance

See Also:

sort(String, String, boolean), sort(String, String, EntityIterable, boolean), sortLinks(String, EntityIterable, boolean, String, EntityIterable, String, String), mergeSorted(List, Comparator), EntityIterable, EntityIterable.isSortResult(), EntityIterable.asSortResult()

sortLinks

@NotNull
@NotNull EntityIterable sortLinks(@NotNull
                                            @NotNull java.lang.String entityType,
                                            @NotNull
                                            @NotNull EntityIterable sortedLinks,
                                            boolean isMultiple,
                                            @NotNull
                                            @NotNull java.lang.String linkName,
                                            @NotNull
                                            @NotNull EntityIterable rightOrder,
                                            @NotNull
                                            @NotNull java.lang.String oppositeEntityType,
                                            @NotNull
                                            @NotNull java.lang.String oppositeLinkName)

Returns the same EntityIterable as sortLinks(String, EntityIterable, boolean, String, EntityIterable) does, but faster if extra indices are available in the database.

 // creation of user
 final Entity user = txn.newEntity("User"); // entityType is "User"
 user.setProperty("login", ...);
 user.setProperty("password", ...);
 user.setProperty("fullName", ...);
 final Entity emailAccount = txn.newEntity("EmailAccount"); // oppositeEntityType is "EmailAccount"
 emailAccount.setProperty("email", ...);
 user.addLink("emailAccount", emailAccount); // linkName is "emailAccount"
 emailAccount.setLink("user", user);         // oppositeLinkName is "user"
 // and so on
 // ...
 // given we have some EntityIterable users, sorting users by e-mail looks like this:
 final EntityIterable linkedEmails = users.selectManyDistinct("emailAccount");
 // linked email accounts sorted by email:
 final EntityIterable sortedLinks = txn.sort("EmailAccount", "email", linkedEmails, true);
 // and finally, given users sorted by email:
 final EntityIterable result = txn.sortLinks("User",
                             sortedLinks,
                             true,  // link "emailAccount" is multiple since user can have more than one account
                             "emailAccount",
                             users,
                             "EmailAccount",
                             "user");
 

Parameters:

entityType - entity type

sortedLinks - some custom order of links

isMultiple - true if the link is multiple

linkName - link name

rightOrder - EntityIterable to sort by

oppositeEntityType - oppositeEntityType

oppositeLinkName - oppositeLinkName

Returns:

EntityIterable instance

See Also:

sort(String, String, boolean), sort(String, String, EntityIterable, boolean), sortLinks(String, EntityIterable, boolean, String, EntityIterable, String, String), mergeSorted(List, Comparator), EntityIterable, EntityIterable.isSortResult(), EntityIterable.asSortResult()

mergeSorted

@Deprecated
 @NotNull
@NotNull EntityIterable mergeSorted(@NotNull
                                                            @NotNull java.util.List<EntityIterable> sorted,
                                                            @NotNull
                                                            @NotNull java.util.Comparator<Entity> comparator)

Deprecated.

Returns merged EntityIterable with entities from several specified sorted iterables using specified comparator. The method is useful to sort entities of different types: at first, the list of sorted EntityIterables for each entity type should be prepared, then this method merges the list.

Parameters:

sorted - list of sorted EntityIterables

comparator - comparator that defines order of entities

Returns:

EntityIterable instance

See Also:

sort(String, String, boolean), sort(String, String, EntityIterable, boolean), sortLinks(String, EntityIterable, boolean, String, EntityIterable), sortLinks(String, EntityIterable, boolean, String, EntityIterable, String, String), EntityIterable, EntityIterable.isSortResult(), EntityIterable.asSortResult()

toEntityId

@NotNull
@NotNull EntityId toEntityId(@NotNull
                                       @NotNull java.lang.String representation)

Parses string representation of an entity id and returns corresponding EntityId instance.

Parameters:

representation - EntityId string representation

Returns:

EntityId instance

See Also:

EntityId

getSequence

@NotNull
@NotNull Sequence getSequence(@NotNull
                                        @NotNull java.lang.String sequenceName)

Returns existing or creates the new named Sequence.

Parameters:

sequenceName - name of sequence, unique in the EntityStore

Returns:

Sequence instance having specified name

See Also:

Sequence

setQueryCancellingPolicy

void setQueryCancellingPolicy(QueryCancellingPolicy policy)

Sets a query cancelling policy for the StoreTransaction.

Parameters:

policy - query cancelling policy

See Also:

getQueryCancellingPolicy(), QueryCancellingPolicy

getQueryCancellingPolicy

@Nullable
@Nullable QueryCancellingPolicy getQueryCancellingPolicy()

Returns:

query cancelling policy set by setQueryCancellingPolicy(QueryCancellingPolicy) or null

See Also:

setQueryCancellingPolicy(QueryCancellingPolicy), QueryCancellingPolicy