Interface DataContext
- All Known Subinterfaces:
DataContextInternal
- All Known Implementing Classes:
DataContextImpl
,NoopDataContext
Within DataContext
, an entity with the given identifier is represented by a single object instance, no matter
where and how many times it is used in object graphs.
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic class
Event sent when the context detects changes in an entity, a new instance is merged or an entity is removed.static class
Event sent after saving changes.static class
Event sent before saving changes. -
Method Summary
Modifier and TypeMethodDescriptionaddChangeListener
(Consumer<DataContext.ChangeEvent> listener) Adds a listener toDataContext.ChangeEvent
.addPostSaveListener
(Consumer<DataContext.PostSaveEvent> listener) Adds a listener toDataContext.PostSaveEvent
.addPreSaveListener
(Consumer<DataContext.PreSaveEvent> listener) Adds a listener toDataContext.PreSaveEvent
.void
clear()
Evicts all tracked entities.boolean
Returns true if the context contains the given entity (distinguished by its class and id).<T> T
Creates an entity instance and merges it into the context.void
Removes the entity from the context so the context stops tracking it.void
Clears the lists of created/modified/deleted entities and evicts these entities.<T> T
Returns an entity instance by its class and id.<T> T
find
(T entity) Returns the instance of entity with the same id if it exists in this context.Returns an immutable set of entities registered as modified.Returns a parent context, if any.Returns an immutable set of entities registered for removal.Returns a function which will be used to save data instead of standard implementation.boolean
Returns true if the context has detected changes in the tracked entities.boolean
isModified
(Object entity) Returns true if the context has detected changes in the given entity.boolean
Returns true if the context has registered removal of the given entity.merge
(Collection entities) Merge the given entities into the context.merge
(Collection entities, MergeOptions options) Merge the given entities into the context.<T> T
merge
(T entity) Same asmerge(Object, MergeOptions)
with default options.<T> T
merge
(T entity, MergeOptions options) Merge the given entity into the context.void
Removes the entity from the context and registers it as deleted.save()
Saves changed and removed instances using DataManager or a custom save delegate.save
(boolean reloadSaved) Saves changed and removed instances using DataManager, custom save delegate or merges them to parent data context if it is set.void
setModified
(Object entity, boolean modified) Registers or unregisters the given entity as modified.void
setParent
(DataContext parentContext) Sets the parent context.void
setSaveDelegate
(Function<SaveContext, Set<Object>> delegate) Sets a function which will be used to save data instead of standard implementation.
-
Method Details
-
find
Returns an entity instance by its class and id.- Returns:
- entity instance or null if there is no such entity in the context
-
find
@Nullable <T> T find(T entity) Returns the instance of entity with the same id if it exists in this context.- Returns:
- entity instance or null if there is no such entity in the context
-
contains
Returns true if the context contains the given entity (distinguished by its class and id). -
merge
Merge the given entity into the context. The whole object graph with all references will be merged.If an entity with the same identifier already exists in the context, the passed entity state is copied into it and the existing instance is returned. Otherwise, a copy of the passed instance is registered in the context and returned.
If the given instance is new and the context doesn't contain an instance with the same identifier, the context will save the new instance on
save()
. Otherwise, even if some attributes of the merged instance are changed as a result of copying the state of the passed instance, the merged instance will not be saved. Such modifications are considered as a result of loading more fresh state from the database.WARNING: use the returned value because it is always a different object instance. The only case when you get the same instance is if the input was previously returned from the same context as a result of
find(Class, Object)
ormerge()
.- Parameters:
entity
- instance to mergeoptions
- merge options- Returns:
- the instance which is tracked by the context
-
merge
@CheckReturnValue <T> T merge(T entity) Same asmerge(Object, MergeOptions)
with default options. -
merge
Merge the given entities into the context. The whole object graph for each element of the collection with all references will be merged.Same as
merge(Object)
but for a collection of instances.- Returns:
- set of instances tracked by the context
-
merge
Merge the given entities into the context. The whole object graph for each element of the collection with all references will be merged.Same as
merge(Object, MergeOptions)
but for a collection of instances.- Returns:
- set of instances tracked by the context
-
remove
Removes the entity from the context and registers it as deleted. The entity will be removed from the data store upon subsequent call tosave()
.If the given entity is not in the context, nothing happens.
-
evict
Removes the entity from the context so the context stops tracking it.If the given entity is not in the context, nothing happens.
-
evictModified
void evictModified()Clears the lists of created/modified/deleted entities and evicts these entities. -
clear
void clear()Evicts all tracked entities.- See Also:
-
create
Creates an entity instance and merges it into the context.Same as:
Foo foo = dataContext.merge(metadata.create(Foo.class));
- Parameters:
entityClass
- entity class- Returns:
- a new instance which is tracked by the context
-
hasChanges
boolean hasChanges()Returns true if the context has detected changes in the tracked entities. -
isModified
Returns true if the context has detected changes in the given entity. -
setModified
Registers or unregisters the given entity as modified.- Parameters:
entity
- entity instance which is already merged into the contextmodified
- true to register or false to unregister
-
getModified
Returns an immutable set of entities registered as modified. -
isRemoved
Returns true if the context has registered removal of the given entity. -
getRemoved
Returns an immutable set of entities registered for removal. -
save
EntitySet save()Saves changed and removed instances using DataManager or a custom save delegate. After successful save, the context contains updated instances returned from the backend code.- Returns:
- set of saved and merged back to the context instances. Does not contain removed instances.
- See Also:
-
save
Saves changed and removed instances using DataManager, custom save delegate or merges them to parent data context if it is set. If reloadSaved is set, merge and reload of saved instances is performed so the context will contain updated instances after successful save.- Parameters:
reloadSaved
- flag indicating whether to reload and merge entities after save using DataManager- Returns:
- set of saved and merged back to the context instances if reloadSaved is true. Empty set otherwise.
- See Also:
-
getParent
Returns a parent context, if any. If the parent context is set,save()
method merges the changed instances to it instead of sending them to DataManager or a custom save delegate. -
setParent
Sets the parent context. If the parent context is set,save()
andsave(boolean)
methods merge the changed instances to it instead of sending them to DataManager or a custom save delegate. -
addChangeListener
Adds a listener toDataContext.ChangeEvent
. -
addPreSaveListener
Adds a listener toDataContext.PreSaveEvent
.You can also add an event listener declaratively using a controller method annotated with
Subscribe
:@Subscribe(target = Target.DATA_CONTEXT) protected void onPreSave(DataContext.PreSaveEvent event) { // handle event here }
- Parameters:
listener
- listener- Returns:
- subscription
-
addPostSaveListener
Adds a listener toDataContext.PostSaveEvent
.You can also add an event listener declaratively using a controller method annotated with
Subscribe
:@Subscribe(target = Target.DATA_CONTEXT) protected void onPostSave(DataContext.PostSaveEvent event) { // handle event here }
- Parameters:
listener
- listener- Returns:
- subscription
-
getSaveDelegate
Returns a function which will be used to save data instead of standard implementation. -
setSaveDelegate
Sets a function which will be used to save data instead of standard implementation.
-