Package: EntityManager

EntityManager

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