Package: EntityManager

EntityManager

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.model;
16:
17: import cz.cvut.kbss.jopa.NonJPA;
18: import cz.cvut.kbss.jopa.exceptions.OWLEntityExistsException;
19: import cz.cvut.kbss.jopa.exceptions.OWLPersistenceException;
20: import cz.cvut.kbss.jopa.exceptions.TransactionRequiredException;
21: import cz.cvut.kbss.jopa.model.descriptors.Descriptor;
22: import cz.cvut.kbss.jopa.model.metamodel.Metamodel;
23: import cz.cvut.kbss.jopa.model.query.Query;
24: import cz.cvut.kbss.jopa.model.query.TypedQuery;
25: import cz.cvut.kbss.jopa.transactions.EntityTransaction;
26:
27: import java.net.URI;
28: import java.util.List;
29:
30: public interface EntityManager {
31:
32: /**
33: * Make an instance managed and persistent.
34: * <p>
35: * The entity is persisted into the default context.
36: *
37: * @param entity entity instance
38: * @throws OWLEntityExistsException if the entity already exists. (The EntityExistsException may be thrown when
39: * the persist operation is invoked, or the EntityExistsException or another
40: * PersistenceException may be thrown at flush or commit time.)
41: * @throws IllegalArgumentException if not an entity
42: * @throws NullPointerException If {@code entity} is {@code null}
43: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
44: * PersistenceContextType.TRANSACTION and there is no transaction.
45: * @see #persist(Object, Descriptor)
46: */
47: void persist(final Object entity);
48:
49: /**
50: * Make an instance managed and persistent.
51: * <p>
52: * The {@code descriptor} represents repository and context into which the entity and its fields should be
53: * persisted.
54: *
55: * @param entity entity instance
56: * @param descriptor Entity descriptor
57: * @throws OWLEntityExistsException if the entity already exists. (The EntityExistsException may be thrown when
58: * the persist operation is invoked, or the EntityExistsException or another
59: * PersistenceException may be thrown at flush or commit time.)
60: * @throws IllegalArgumentException if not an entity
61: * @throws NullPointerException If {@code entity} or {@code descriptor} is {@code null}
62: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
63: * PersistenceContextType.TRANSACTION and there is no transaction.
64: */
65: void persist(final Object entity, final Descriptor descriptor);
66:
67: /**
68: * Merge the state of the given entity into the current persistence context.
69: * <p>
70: * The entity is merged into the default repository context.
71: *
72: * @param entity The entity to merge
73: * @return the instance that the state was merged to
74: * @throws IllegalArgumentException if instance is not an entity or is a removed entity
75: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
76: * PersistenceContextType.TRANSACTION and there is no transaction.
77: */
78: <T> T merge(final T entity);
79:
80: /**
81: * Merge the state of the given entity into the current persistence context and into the repository specified by
82: * {@code descriptor}.
83: *
84: * @param entity The entity to merge
85: * @param descriptor Entity descriptor
86: * @return the instance that the state was merged to
87: * @throws IllegalArgumentException if instance is not an entity or is a removed entity
88: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
89: * PersistenceContextType.TRANSACTION and there is no transaction.
90: */
91: <T> T merge(final T entity, Descriptor descriptor);
92:
93: /**
94: * Remove the entity instance.
95: *
96: * @param entity The instance to remove
97: * @throws IllegalArgumentException if not an entity or if a detached entity
98: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
99: * PersistenceContextType.TRANSACTION and there is no transaction.
100: */
101: void remove(final Object entity);
102:
103: /**
104: * Find by identifier.
105: * <p>
106: * Search for an entity of the specified class and identifier. If the entity instance is contained in the
107: * persistence context, it is returned from there.
108: *
109: * @param entityClass Entity class
110: * @param identifier Entity identifier
111: * @return the found entity instance or {@code null} if the entity does not exist in the given ontology context
112: * @throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is
113: * not a valid type for that entity’s identifier
114: * @throws NullPointerException If {@code entityClass}, {@code identifier} is {@code null}
115: */
116: <T> T find(final Class<T> entityClass, final Object identifier);
117:
118: /**
119: * Find by identifier.
120: * <p>
121: * Search for an entity of the specified class and identifier. If the entity instance is contained in the
122: * persistence context, it is returned from there.
123: * <p>
124: * The {@code descriptor} parameter represents repository and context in which the entity should be looked for.
125: *
126: * @param entityClass Entity class
127: * @param identifier Entity identifier
128: * @param descriptor Entity descriptor
129: * @return the found entity instance or {@code null} if the entity does not exist in the given ontology context
130: * @throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is
131: * not a valid type for that entity’s identifier
132: * @throws NullPointerException If {@code entityClass}, {@code identifier} or {@code contextUri} is {@code
133: * null}
134: * @see #getContexts()
135: */
136: <T> T find(final Class<T> entityClass, final Object identifier,
137: final Descriptor descriptor);
138:
139: // TODO JPA 2.0 find with properties
140:
141: // TODO JPA 2.0 find with lock mode
142:
143: // TODO JPA 2.0 find with lock mode and properties
144:
145: /**
146: * Get an instance, whose state may be lazily fetched.
147: * <p>
148: * If the requested instance does not exist in the database, {@code null} is returned.
149: * <p>
150: * The application should not expect that the instance state will be available upon detachment, unless it was
151: * accessed by the application while the entity manager was open.
152: *
153: * @param entityClass entity class
154: * @param identifier identifier of the instance
155: * @return the found entity instance
156: * @throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is
157: * not a valid type for that entity’s identifier
158: */
159: <T> T getReference(final Class<T> entityClass, final Object identifier);
160:
161: /**
162: * Get an instance, whose state may be lazily fetched.
163: * <p>
164: * If the requested instance does not exist in the database, {@code null} is returned.
165: * <p>
166: * The application should not expect that the instance state will be available upon detachment, unless it was
167: * accessed by the application while the entity manager was open.
168: * <p>
169: * The {@code descriptor} parameter represents configuration of the entity loading (e.g., repository context).
170: *
171: * @param entityClass entity class
172: * @param identifier identifier of the instance
173: * @param descriptor Entity descriptor
174: * @return the found entity instance
175: * @throws IllegalArgumentException if the first argument does not denote an entity type or the second argument is
176: * not a valid type for that entity’s identifier
177: */
178: <T> T getReference(final Class<T> entityClass, final Object identifier, final Descriptor descriptor);
179:
180: /**
181: * Synchronize the persistence context to the underlying database.
182: *
183: * @throws TransactionRequiredException if there is no transaction
184: * @throws OWLPersistenceException if the flush fails
185: */
186: void flush();
187:
188: // /**
189: // * Set the flush mode that applies to all objects contained in the
190: // * persistence context.
191: // *
192: // * @param flushMode
193: // */
194: // public void setFlushMode(FlushModeType flushMode);
195:
196: // TODO JPA 2.0 getFlushMode
197:
198: // /**
199: // * Set the lock mode for an entity object contained in the persistence
200: // * context.
201: // *
202: // * @param entity
203: // * @param lockMode
204: // * @throws PersistenceException
205: // * if an unsupported lock call is made
206: // * @throws IllegalArgumentException
207: // * if the instance is not an entity or is a detached entity
208: // * @throws TransactionRequiredException
209: // * if there is no transaction
210: // */
211: // public void lock(Object entity, LockModeType lockMode);
212:
213: // TODO JPA 2.0 lock with lock mode and properties
214:
215: /**
216: * Refresh the state of the instance from the data source, overwriting changes made to the entity, if any.
217: *
218: * @param entity The entity instance to refresh
219: * @throws IllegalArgumentException if not an entity or entity is not managed
220: * @throws TransactionRequiredException if invoked on a container-managed entity manager of type
221: * PersistenceContextType.TRANSACTION and there is no transaction.
222: */
223: void refresh(final Object entity);
224:
225: // TODO JPA 2.0 refresh with lock mode
226: // TODO JPA 2.0 refresh with properties
227: // TODO JPA 2.0 refresh with lock mode and properties
228:
229: /**
230: * Clear the persistence context, causing all managed entities to become detached. Changes made to entities that
231: * have not been flushed to the database will not be persisted.
232: */
233: void clear();
234:
235: /**
236: * Remove the given entity from the persistence context, causing a managed entity to become detached. Unflushed
237: * changes made to the entity if any (including removal of the entity), will not be synchronized to the database.
238: * Entities which previously referenced the detached entity will continue to reference it.
239: *
240: * @param entity The instance to detach
241: * @throws IllegalArgumentException if the instance is not an entity
242: */
243: void detach(Object entity);
244:
245: /**
246: * Check if the instance belongs to the current persistence context.
247: *
248: * @param entity The instance to check
249: * @return True if the instance is managed, false otherwise
250: * @throws IllegalArgumentException if not an entity
251: */
252: boolean contains(Object entity);
253:
254: /**
255: * Checks consistency of the specified context.
256: * <p>
257: * The context URI can be {@code null}, which indicates that consistency of the whole repository should be
258: * verified.
259: *
260: * @param context Context URI, can be {@code null}
261: * @return {@code true} if consistent, {@code false} otherwise
262: */
263: @NonJPA
264: boolean isConsistent(URI context);
265:
266: // TODO JPA 2.0 public LockModeType getLockMode(Object entity)
267: // TODO JPA 2.0 setProperty
268: // TODO JPA 2.0 getProperties
269:
270: /**
271: * Create an instance of Query for executing a Java Persistence query language statement.
272: *
273: * @param qlString a Java Persistence query string
274: * @return the new query instance
275: * @throws IllegalArgumentException if query string is not valid
276: */
277: @NonJPA
278: Query createQuery(String qlString);
279:
280: // TODO JPA 2.0 TypedQuery<T> createQuery(CriteriaQuery<T> criteriaQuery)
281:
282: /**
283: * Creates an instance of query for executing Java persistence query language statement.
284: *
285: * @param query query string
286: * @param resultClass result type
287: * @return the new query instance
288: */
289: @NonJPA
290: <T> TypedQuery<T> createQuery(String query, Class<T> resultClass);
291:
292:
293: /**
294: * Create an instance of Query for executing a named query (in native SPARQL).
295: *
296: * @param name the name of a query defined in metadata
297: * @return the new query instance
298: * @throws IllegalArgumentException if a query has not been defined with the given name
299: */
300: Query createNamedQuery(String name);
301:
302: /**
303: * Create an instance of TypedQuery for executing a SPARQL named query.
304: * <p>
305: * The select list of the query must contain only a single item, which must be assignable to the type specified by
306: * the resultClass argument.
307: *
308: * @param name the name of a query defined in metadata
309: * @param resultClass the type of the query result
310: * @return the new query instance
311: * @throws IllegalArgumentException if a query has not been defined with the given name or if the query string is
312: * found to be invalid or if the query result is found to not be assignable to the
313: * specified type
314: */
315: <T> TypedQuery<T> createNamedQuery(String name, Class<T> resultClass);
316:
317: /**
318: * Create an instance of Query for executing a native SPARQL(-DL) query in SPARQL syntax.
319: *
320: * @param sparqlString a native SPARQL query string
321: * @return the new query instance
322: */
323: Query createNativeQuery(String sparqlString);
324:
325: /**
326: * Create an instance of Query for executing a native SPARQL(-DL) query returning only specific object type.
327: *
328: * @param sparqlString a native SQL query string
329: * @param resultClass the class of the resulting instance(s)
330: * @return the new query instance
331: */
332: <T> TypedQuery<T> createNativeQuery(String sparqlString, Class<T> resultClass);
333:
334: /**
335: * Create an instance of Query for executing a native SPARQL query.
336: *
337: * @param sparqlString a native SQL query string
338: * @param resultSetMapping the name of the result set mapping
339: * @return the new query instance
340: */
341: Query createNativeQuery(String sparqlString, String resultSetMapping);
342:
343: // /**
344: // * Indicate to the EntityManager that a JTA transaction is active. This
345: // * method should be called on a JTA application managed EntityManager that
346: // * was created outside the scope of the active transaction to associate it
347: // * with the current JTA transaction.
348: // *
349: // * @throws TransactionRequiredException
350: // * if there is no transaction.
351: // */
352: // public void joinTransaction();
353:
354: /**
355: * Return an object of the specified type to allow access to the provider-specific API. If the provider's
356: * EntityManager implementation does not support the specified class, the {@link OWLPersistenceException} is
357: * thrown.
358: *
359: * @param cls The class of the object to be returned. This can be also an implementation of the underlying driver
360: * @return an instance of the specified class
361: * @throws OWLPersistenceException If the provider does not support the specified class
362: */
363: <T> T unwrap(Class<T> cls);
364:
365: /**
366: * Return the underlying provider object for the EntityManager, if available. The result of this method is
367: * implementation specific.
368: *
369: * @return underlying provider object for EntityManager
370: */
371: Object getDelegate();
372:
373: /**
374: * Close an application-managed EntityManager. After the close method has been invoked, all methods on the
375: * EntityManager instance and any Query objects obtained from it will throw the IllegalStateException except for
376: * getTransaction and isOpen (which will return false). If this method is called when the EntityManager is
377: * associated with an active transaction, the persistence context remains managed until the transaction completes.
378: *
379: * @throws IllegalStateException if the EntityManager is container-managed.
380: */
381: void close();
382:
383: /**
384: * Determine whether the EntityManager is open.
385: *
386: * @return true until the EntityManager has been closed.
387: */
388: boolean isOpen();
389:
390: /**
391: * Return the resource-level transaction object. The EntityTransaction instance may be used serially to begin and
392: * commit multiple transactions.
393: *
394: * @return EntityTransaction instance
395: * @throws IllegalStateException if invoked on a JTA EntityManager.
396: */
397: EntityTransaction getTransaction();
398:
399: /**
400: * Return the entity manager factory for the entity manager.
401: *
402: * @return EntityManagerFactory instance
403: * @since JPA 2.0
404: */
405: EntityManagerFactory getEntityManagerFactory();
406:
407: //        /**
408: //         * Returns a label for the given IRI. The label is returned with the
409: //         * following preference: 1) label in the language specified for the entity
410: //         * manager 2) label without language tag 3) any (unspecified) label
411: //         *
412: //         * @param iri
413: //         * @return
414: //         */
415: //        @NonJPA
416: //        public String getLabel(final String iri);
417:
418: /**
419: * Returns a list of repository contexts available to this entity manager.
420: *
421: * @return List of repository context URIs
422: */
423: @NonJPA
424: List<URI> getContexts();
425:
426: // TODO JPA 2.0 public CriteriaBuilder getCriteriaBuilder();
427:
428: /**
429: * Return an instance of Metamodel interface for access to the metamodel of the persistence unit.
430: *
431: * @return Metamodel instance
432: */
433: Metamodel getMetamodel();
434:
435: // TODO Remove the following methods and replace them with implementation of JPA flush modes
436:
437: /**
438: * Sets the transactional ontology as the one which will be used when processing SPARQL queries.
439: * <p>
440: * This setting may have significant impact on query results, since changes made during transaction are propagated
441: * to the transactional ontology, which is private to this persistence context, before commit. The ontology can even
442: * be in an inconsistent state.
443: * <p>
444: * This is the default setting, unless changed by properties passed on persistence initialization.
445: *
446: * @see #setUseBackupOntologyForQueryProcessing
447: */
448: @NonJPA
449: @Deprecated
450: void setUseTransactionalOntologyForQueryProcessing();
451:
452: /**
453: * Returns true if the transactional ontology should be used for SPARQL query processing.
454: *
455: * @return {@code true} if transactional ontology will be used, {@code false} otherwise
456: * @see #setUseTransactionalOntologyForQueryProcessing()
457: */
458: @NonJPA
459: @Deprecated
460: boolean useTransactionalOntologyForQueryProcessing();
461:
462: /**
463: * Sets the backup ontology as the one which will be used for processing of SPARQL queries.
464: * <p>
465: * The backup ontology represents the ontology after the last commit done by any transaction and therefore can
466: * produce different results from those produced by the transactional ontology, which is private to this persistence
467: * context.
468: *
469: * @see #setUseTransactionalOntologyForQueryProcessing()
470: */
471: @NonJPA
472: @Deprecated
473: void setUseBackupOntologyForQueryProcessing();
474:
475: /**
476: * Returns true if the backup (central) ontology should be used for SPARQL query processing.
477: *
478: * @return {@code true} if the central ontology will be used, {@code false} otherwise
479: * @see #setUseBackupOntologyForQueryProcessing()
480: */
481: @NonJPA
482: @Deprecated
483: boolean useBackupOntologyForQueryProcessing();
484: }