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