Package: UnitOfWork

UnitOfWork

Coverage

1: /**
2: * Copyright (C) 2016 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.descriptors.Descriptor;
19:
20: import java.lang.reflect.Field;
21: import java.net.URI;
22: import java.util.List;
23: import java.util.function.Consumer;
24:
25: /**
26: * Represents a persistence context.
27: * <p>
28: * All interactions with objects managed in a persistence context are tracked by its corresponding UoW and on commit,
29: * the UoW propagates them into the changes into the storage.
30: */
31: public interface UnitOfWork extends Session {
32:
33: /**
34: * Clears this Unit of Work.
35: */
36: void clear();
37:
38: /**
39: * Commit changes to the ontology.
40: */
41: void commit();
42:
43: /**
44: * Rolls back changes done since last commit.
45: *
46: * @see #commit()
47: */
48: void rollback();
49:
50: /**
51: * Returns true if the specified entity is managed in the current
52: * persistence context. This method is used by the EntityManager's contains
53: * 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
69: * a currently running transaction.
70: *
71: * @return True if in an active transaction
72: */
73: boolean isInTransaction();
74:
75: /**
76: * Return true if the given entity is managed. This means it is either in
77: * the shared session cache or it is a new object ready for persist.
78: *
79: * @param entity Object
80: * @return boolean
81: */
82: boolean isObjectManaged(Object entity);
83:
84: /**
85: * Checks whether context specified by {@code context} is consistent.
86: * <p>
87: * Can be {@code null}, indicating that consistency of the whole repository
88: * should be checked.
89: *
90: * @param context Context URI
91: * @return {@code true} if the context is consistent, {@code false} otherwise
92: * @throws OWLPersistenceException If an ontology access error occurs
93: */
94: boolean isConsistent(URI context);
95:
96: /**
97: * Loads value of the specified field for the specified entity.
98: * <p>
99: * The value is set on the entity.
100: *
101: * @param entity The entity to load field for
102: * @param field The field to load
103: * @throws NullPointerException If {@code entity} or {@code field} is {@code null}
104: * @throws OWLPersistenceException If an error occurs, this may be e. g. that the field is not present on the
105: * entity, an ontology access error occurred etc.
106: */
107: <T> void loadEntityField(T entity, Field field);
108:
109: /**
110: * Merges the state of the given entity into the current persistence
111: * context.
112: * <p>
113: * The {@code descriptor} argument specified the ontology contexts into
114: * which the detached entity and its fields belong and should be merged.
115: *
116: * @param entity entity instance
117: * @param descriptor Entity descriptor, specifies repository context
118: * @return the managed instance that the state was merged to
119: * @throws NullPointerException If {@code entity} or {@code repository} is {@code null}
120: */
121: <T> T mergeDetached(T entity, Descriptor descriptor);
122:
123: /**
124: * Retrieves object with the specified primary key.
125: * <p>
126: * The object as well as its fields are looked for in contexts specified by
127: * the descriptor. The result is then cast to the specified type.
128: *
129: * @param cls The type of the returned object
130: * @param primaryKey Primary key
131: * @param descriptor Entity descriptor
132: * @return The retrieved object or {@code null} if there is no object with the specified primary key in the
133: * specified repository
134: * @throws NullPointerException If {@code cls}, {@code primaryKey} or {@code repository} is {@code null}
135: * @throws OWLPersistenceException If {@code repository} is not valid or if an error during object loading occurs
136: */
137: <T> T readObject(Class<T> cls, Object primaryKey, Descriptor descriptor);
138:
139: /**
140: * Register an existing object in this Unit of Work.
141: * <p>
142: * This method creates a working clone of this object and puts the given object into this Unit of Work
143: * cache.
144: *
145: * @param object Object
146: * @param descriptor Entity descriptor identifying repository contexts
147: * @return Object Returns clone of the registered object
148: */
149: Object registerExistingObject(Object object, Descriptor descriptor);
150:
151: /**
152: * Registers an existing object in this Unit of Work.
153: * <p>
154: * Invokes the specified postClone procedures after the cloning takes place, passing the newly created clone as argument.
155: *
156: * @param object The object to register
157: * @param descriptor Descriptor identifying repository contexts
158: * @param postClone Handlers to be called after the original object is cloned on the clone
159: * @return Clone of the registered object
160: * @see #registerExistingObject(Object, Descriptor)
161: */
162: Object registerExistingObject(Object object, Descriptor descriptor, List<Consumer<Object>> postClone);
163:
164: /**
165: * Registers the specified new object in this Unit of Work.
166: * <p>
167: * The object will be persisted into the context specified by
168: * {@code descriptor}.
169: *
170: * @param object The object to register
171: * @param descriptor Entity descriptor
172: * @throws NullPointerException If {@code entity} or {@code context} is {@code null}
173: * @throws OWLPersistenceException If {@code context} is not a valid context URI or if an error during registration
174: * occurs
175: */
176: void registerNewObject(Object object, Descriptor descriptor);
177:
178: /**
179: * Remove the given object. Calling this method causes the entity to be
180: * removed from the shared cache and a delete query is initiated on the
181: * ontology.
182: *
183: * @param object Object
184: */
185: void removeObject(Object object);
186:
187: /**
188: * Restores the specified removed object.
189: * <p>
190: * This means it is reinstated as a managed entity and reinserted into the repository.
191: *
192: * @param entity The object to restore
193: */
194: void restoreRemovedObject(Object entity);
195:
196: /**
197: * Release the current unit of work. Calling this method disregards any
198: * changes made to clones.
199: */
200: @Override
201: void release();
202:
203: /**
204: * Refreshes state of the object from the storage, overwriting any changes made to it.
205: *
206: * @param object The object to revert
207: * @param <T> Object type
208: * @throws IllegalArgumentException If the object is not managed
209: */
210: <T> void refreshObject(T object);
211:
212: /**
213: * This method returns true, if the UnitOfWork should be released after the
214: * commit call. This is done for inferred attributes, which cause the whole
215: * session cache to be invalidated.
216: *
217: * @return True if the UnitOfWork should be released after commit.
218: */
219: boolean shouldReleaseAfterCommit();
220:
221: /**
222: * Writes any uncommitted changes into the ontology. This method may be
223: * useful when flushing entity manager or closing sessions, because we don't
224: * want to let the changes to get lost.
225: */
226: void writeUncommittedChanges();
227:
228: /**
229: * Gets repository contexts available to this session.
230: *
231: * @return Unmodifiable list of context URIs
232: */
233: List<URI> getContexts();
234:
235: /**
236: * Sets the transactional ontology as the one used for SPARQL query
237: * processing.
238: */
239: void setUseTransactionalOntologyForQueryProcessing();
240:
241: /**
242: * Returns true if the transactional ontology is set as the one processing
243: * SPARQL queries.
244: *
245: * @return boolean
246: */
247: boolean useTransactionalOntologyForQueryProcessing();
248:
249: /**
250: * Sets the backup (central) ontology as the one used for SPARQL query
251: * processing.
252: */
253: void setUseBackupOntologyForQueryProcessing();
254:
255: /**
256: * Returns true if the backup (central) ontology is set as the one
257: * processing SPARQL queries.
258: *
259: * @return boolean
260: */
261: boolean useBackupOntologyForQueryProcessing();
262: }