Package: UnitOfWork

UnitOfWork

Coverage

1: /*
2: * JOPA
3: * Copyright (C) 2023 Czech Technical University in Prague
4: *
5: * This library is free software; you can redistribute it and/or
6: * modify it under the terms of the GNU Lesser General Public
7: * License as published by the Free Software Foundation; either
8: * version 3.0 of the License, or (at your option) any later version.
9: *
10: * This library is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13: * Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General Public
16: * License along with this library.
17: */
18: package cz.cvut.kbss.jopa.sessions;
19:
20: import cz.cvut.kbss.jopa.exceptions.OWLPersistenceException;
21: import cz.cvut.kbss.jopa.model.LoadState;
22: import cz.cvut.kbss.jopa.model.descriptors.Descriptor;
23: import cz.cvut.kbss.jopa.model.metamodel.FieldSpecification;
24:
25: import java.lang.reflect.Field;
26: import java.net.URI;
27: import java.util.List;
28: import java.util.function.Consumer;
29:
30: /**
31: * Represents a persistence context.
32: * <p>
33: * All interactions with objects managed in a persistence context are tracked by its corresponding UoW and on commit,
34: * the UoW propagates them into the changes into the storage.
35: */
36: public interface UnitOfWork extends Session {
37:
38: /**
39: * Clears this Unit of Work.
40: */
41: void clear();
42:
43: /**
44: * Commit changes to the ontology.
45: */
46: void commit();
47:
48: /**
49: * Rolls back changes done since last commit.
50: *
51: * @see #commit()
52: */
53: void rollback();
54:
55: /**
56: * Returns true if the specified entity is managed in the current persistence context. This method is used by the
57: * EntityManager's contains method.
58: *
59: * @param entity Object
60: * @return {@literal true} if entity is managed, {@literal false} otherwise
61: */
62: boolean contains(Object entity);
63:
64: /**
65: * Is this Unit of Work active?
66: *
67: * @return boolean
68: */
69: boolean isActive();
70:
71: /**
72: * Returns true if this {@code UnitOfWork} represents persistence context of a currently running transaction.
73: *
74: * @return True if in an active transaction
75: */
76: boolean isInTransaction();
77:
78: /**
79: * Return true if the given entity is managed. This means it is either in the shared session cache or it is a new
80: * object ready for persist.
81: *
82: * @param entity Object
83: * @return boolean
84: */
85: boolean isObjectManaged(Object entity);
86:
87: /**
88: * Checks whether context specified by {@code context} is consistent.
89: * <p>
90: * Can be {@code null}, indicating that consistency of the whole repository should be checked.
91: *
92: * @param context Context URI
93: * @return {@code true} if the context is consistent, {@code false} otherwise
94: * @throws OWLPersistenceException If an ontology access error occurs
95: */
96: boolean isConsistent(URI context);
97:
98: /**
99: * Loads value of the specified field for the specified entity.
100: * <p>
101: * The value is set on the entity.
102: *
103: * @param entity The entity to load field for
104: * @param field The field to load
105: * @throws NullPointerException If {@code entity} or {@code field} is {@code null}
106: * @throws OWLPersistenceException If an error occurs, this may be e. g. that the field is not present on the
107: * entity, an ontology access error occurred etc.
108: */
109: <T> void loadEntityField(T entity, Field field);
110:
111: /**
112: * Merges the state of the given entity into the current persistence context.
113: * <p>
114: * The {@code descriptor} argument specified the ontology contexts into which the detached entity and its fields
115: * belong and should be merged.
116: *
117: * @param entity entity instance
118: * @param descriptor Entity descriptor, specifies repository context
119: * @return the managed instance that the state was merged to
120: * @throws NullPointerException If {@code entity} or {@code repository} is {@code null}
121: */
122: <T> T mergeDetached(T entity, Descriptor descriptor);
123:
124: /**
125: * Retrieves object with the specified identifier.
126: * <p>
127: * The object as well as its fields are looked for in contexts specified by the descriptor. The result is then cast
128: * to the specified type.
129: *
130: * @param cls The type of the returned object
131: * @param identifier Instance identifier
132: * @param descriptor Entity descriptor
133: * @return The retrieved object or {@code null} if there is no object with the specified identifier in the specified
134: * repository
135: * @throws NullPointerException If {@code cls}, {@code identifier} or {@code repository} is {@code null}
136: * @throws OWLPersistenceException If an error occurs during object loading
137: */
138: <T> T readObject(Class<T> cls, Object identifier, Descriptor descriptor);
139:
140: /**
141: * Retrieves a reference to an object with the specified identifier.
142: * <p>
143: * A reference is permitted to have its state fetched lazily.
144: *
145: * @param cls The type of the returned object
146: * @param identifier Instance identifier
147: * @param descriptor Entity descriptor
148: * @param <T> Entity type
149: * @return The retrieved object or {@code null} if none can be found
150: * @throws OWLPersistenceException If an error occurs during object loading
151: */
152: <T> T getReference(Class<T> cls, Object identifier, Descriptor descriptor);
153:
154: /**
155: * Register an existing object in this Unit of Work.
156: * <p>
157: * This method creates a working clone of this object and puts the given object into this Unit of Work cache.
158: *
159: * @param object Object
160: * @param descriptor Entity descriptor identifying repository contexts
161: * @return Object Returns clone of the registered object
162: */
163: Object registerExistingObject(Object object, Descriptor descriptor);
164:
165: /**
166: * Registers an existing object in this Unit of Work.
167: * <p>
168: * Invokes the specified postClone procedures after the cloning takes place, passing the newly created clone as
169: * argument.
170: *
171: * @param object The object to register
172: * @param descriptor Descriptor identifying repository contexts
173: * @param postClone Handlers to be called after the original object is cloned on the clone
174: * @return Clone of the registered object
175: * @see #registerExistingObject(Object, Descriptor)
176: */
177: Object registerExistingObject(Object object, Descriptor descriptor, List<Consumer<Object>> postClone);
178:
179: /**
180: * Registers the specified new object in this Unit of Work.
181: * <p>
182: * The object will be persisted into the context specified by {@code descriptor}.
183: *
184: * @param object The object to register
185: * @param descriptor Entity descriptor
186: * @throws NullPointerException If {@code entity} or {@code context} is {@code null}
187: * @throws OWLPersistenceException If {@code context} is not a valid context URI or if an error during registration
188: * occurs
189: */
190: void registerNewObject(Object object, Descriptor descriptor);
191:
192: /**
193: * Remove the given object. Calling this method causes the entity to be removed from the shared cache and a delete
194: * query is initiated on the ontology.
195: *
196: * @param object Object
197: */
198: void removeObject(Object object);
199:
200: /**
201: * Restores the specified removed object.
202: * <p>
203: * This means it is reinstated as a managed entity and reinserted into the repository.
204: *
205: * @param entity The object to restore
206: */
207: void restoreRemovedObject(Object entity);
208:
209: /**
210: * Release the current unit of work. Calling this method disregards any changes made to clones.
211: */
212: @Override
213: void release();
214:
215: /**
216: * Refreshes state of the object from the storage, overwriting any changes made to it.
217: *
218: * @param object The object to revert
219: * @param <T> Object type
220: * @throws IllegalArgumentException If the object is not managed
221: */
222: <T> void refreshObject(T object);
223:
224: /**
225: * This method returns true, if the UnitOfWork should be released after the commit call. This is done for inferred
226: * attributes, which cause the whole session cache to be invalidated.
227: *
228: * @return True if the UnitOfWork should be released after commit.
229: */
230: boolean shouldReleaseAfterCommit();
231:
232: /**
233: * Writes any uncommitted changes into the ontology. This method may be useful when flushing entity manager or
234: * closing sessions, because we don't want to let the changes to get lost.
235: */
236: void writeUncommittedChanges();
237:
238: /**
239: * Gets repository contexts available to this session.
240: *
241: * @return Unmodifiable list of context URIs
242: */
243: List<URI> getContexts();
244:
245: /**
246: * Gets the load status of the specified attribute on the specified entity.
247: *
248: * @param entity Entity instance
249: * @param attributeName Attribute whose load status is to be determined
250: * @return Attribute load status
251: * @see cz.cvut.kbss.jopa.model.ProviderUtil#isLoadedWithoutReference(Object, String)
252: */
253: LoadState isLoaded(Object entity, String attributeName);
254:
255: /**
256: * Gets the load status of the specified entity.
257: *
258: * @param entity Entity whose load status is to be determined.
259: * @return Entity load status
260: * @see cz.cvut.kbss.jopa.model.ProviderUtil#isLoaded(Object)
261: */
262: LoadState isLoaded(Object entity);
263:
264: /**
265: * Checks whether the specified attribute value of the specified entity is inferred in the underlying repository.
266: * <p>
267: * Note that given the nature of the repository implementation, this method may return true if the corresponding
268: * statement is both inferred and asserted. Also note that this method will use the descriptor associated with the
269: * specified entity in this persistence context to resolve the repository context, but some underlying repositories
270: * do not store inferences in data contexts, so the attribute context may be ignored.
271: *
272: * @param entity Entity whose attribute to examine. Must be managed by this persistence context
273: * @param attribute Attribute whose value to examine
274: * @param value The value whose inference to examine
275: * @return {@code true} if the entity attribute value is inferred, {@code false} otherwise
276: */
277: <T> boolean isInferred(T entity, FieldSpecification<? super T, ?> attribute, Object value);
278: }