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 {@link #persist(Object, cz.cvut.kbss.jopa.model.descriptors.Descriptor)}
46: */
47: public 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: public 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: public <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: public <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: public 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: public <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: public <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: public 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: public 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: public 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: public 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: public 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: public 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: public <T> TypedQuery<T> createQuery(String query, Class<T> resultClass);
275:
276: //
277: // /**
278: // * Create an instance of Query for executing a named query (in the Java
279: // * Persistence query language or in native SQL).
280: // *
281: // * @param name
282: // * the name of a query defined in metadata
283: // * @return the new query instance
284: // * @throws IllegalArgumentException
285: // * if a query has not been defined with the given name
286: // */
287: // public Query createNamedQuery(String name);
288: //
289: // TODO JPA 2.0 TypedQuery<T> createNamedQuery(String query, Class<T>
290: // resultClass)
291:
292: /**
293: * Create an instance of Query for executing a native SPARQL-DL query in SPARQL syntax.
294: *
295: * @param sqlString a native SPARQL query string
296: * @return the new query instance
297: */
298: Query createNativeQuery(String sqlString);
299:
300: /**
301: * Create an instance of Query for executing a native SPARQL-DL query returning only specific object type.
302: *
303: * @param sqlString a native SQL query string
304: * @param resultClass the class of the resulting instance(s)
305: * @return the new query instance
306: */
307: <T> TypedQuery<T> createNativeQuery(String sqlString, Class<T> resultClass);
308:
309: // /**
310: // * Create an instance of Query for executing a native SQL query.
311: // *
312: // * @param sqlString
313: // * a native SQL query string
314: // * @param resultSetMapping
315: // * the name of the result set mapping
316: // * @return the new query instance
317: // */
318: // public Query createNativeQuery(String sqlString, String
319: // resultSetMapping);
320:
321: // /**
322: // * Indicate to the EntityManager that a JTA transaction is active. This
323: // * method should be called on a JTA application managed EntityManager that
324: // * was created outside the scope of the active transaction to associate it
325: // * with the current JTA transaction.
326: // *
327: // * @throws TransactionRequiredException
328: // * if there is no transaction.
329: // */
330: // public void joinTransaction();
331:
332: /**
333: * Return an object of the specified type to allow access to the provider-specific API. If the provider's
334: * EntityManager implementation does not support the specified class, the {@link OWLPersistenceException} is
335: * thrown.
336: *
337: * @param cls The class of the object to be returned. This can be also an implementation of the underlying driver
338: * @return an instance of the specified class
339: * @throws OWLPersistenceException If the provider does not support the specified class
340: */
341: <T> T unwrap(Class<T> cls);
342:
343: /**
344: * Return the underlying provider object for the EntityManager, if available. The result of this method is
345: * implementation specific.
346: */
347: public Object getDelegate();
348:
349: /**
350: * Close an application-managed EntityManager. After the close method has been invoked, all methods on the
351: * EntityManager instance and any Query objects obtained from it will throw the IllegalStateException except for
352: * getTransaction and isOpen (which will return false). If this method is called when the EntityManager is
353: * associated with an active transaction, the persistence context remains managed until the transaction completes.
354: *
355: * @throws IllegalStateException if the EntityManager is container-managed.
356: */
357: public void close();
358:
359: /**
360: * Determine whether the EntityManager is open.
361: *
362: * @return true until the EntityManager has been closed.
363: */
364: public boolean isOpen();
365:
366: /**
367: * Return the resource-level transaction object. The EntityTransaction instance may be used serially to begin and
368: * commit multiple transactions.
369: *
370: * @return EntityTransaction instance
371: * @throws IllegalStateException if invoked on a JTA EntityManager.
372: */
373: public EntityTransaction getTransaction();
374:
375: /**
376: * @since JPA 2.0
377: */
378: public EntityManagerFactory getEntityManagerFactory();
379:
380: //        /**
381: //         * Returns a label for the given IRI. The label is returned with the
382: //         * following preference: 1) label in the language specified for the entity
383: //         * manager 2) label without language tag 3) any (unspecified) label
384: //         *
385: //         * @param iri
386: //         * @return
387: //         */
388: //        @NonJPA
389: //        public String getLabel(final String iri);
390:
391: /**
392: * Returns a list of repository contexts available to this entity manager. </p>
393: *
394: * @return List of repository context URIs
395: */
396: @NonJPA
397: public List<URI> getContexts();
398:
399: // TODO JPA 2.0 public CriteriaBuilder getCriteriaBuilder();
400: public Metamodel getMetamodel();
401:
402: /**
403: * Sets the transactional ontology as the one which will be used when processing SPARQL queries. </p> <p> This
404: * setting may have significant impact on query results, since changes made during transaction are propagated to the
405: * transactional ontology, which is private to this persistence context, before commit. The ontology can even be in
406: * an inconsistent state. </p>
407: * <p>
408: * This is the default setting, unless changed by properties passed on persistence initialization.
409: *
410: * @see #setUseBackupOntologyForQueryProcessing()
411: */
412: @NonJPA
413: public void setUseTransactionalOntologyForQueryProcessing();
414:
415: /**
416: * Returns true if the transactional ontology should be used for SPARQL query processing.
417: *
418: * @return {@code true} if transactional ontology will be used, {@code false} otherwise
419: * @see #setUseTransactionalOntologyForQueryProcessing()
420: */
421: @NonJPA
422: public boolean useTransactionalOntologyForQueryProcessing();
423:
424: /**
425: * Sets the backup ontology as the one which will be used for processing of SPARQL queries. </p>
426: * <p>
427: * The backup ontology represents the ontology after the last commit done by any transaction and therefore can
428: * produce different results from those produced by the transactional ontology, which is private to this persistence
429: * context.
430: *
431: * @see #setUseTransactionalOntologyForQueryProcessing()
432: */
433: @NonJPA
434: public void setUseBackupOntologyForQueryProcessing();
435:
436: /**
437: * Returns true if the backup (central) ontology should be used for SPARQL query processing. </p>
438: *
439: * @return {@code true} if the central ontology will be used, {@code false} otherwise
440: * @see #setUseBackupOntologyForQueryProcessing()
441: */
442: @NonJPA
443: public boolean useBackupOntologyForQueryProcessing();
444: }