Package: UnitOfWork

UnitOfWork

Coverage

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